Campañas, de principio a fin

Una campaña envía una plantilla aprobada por Meta, desde uno de sus números, a una lista de contactos, y lleva las respuestas a quien usted elija (un equipo, un flujo o un asistente de IA). Esta guía hace una campaña entera por la API. Pruébelo todo antes con la clave de demostración.

1. Lo que necesita antes

curl https://api.donetalk.com/v1/c/{empresa}/channels -H "Authorization: Bearer $DONETALK_KEY"
curl https://api.donetalk.com/v1/c/{empresa}/templates -H "Authorization: Bearer $DONETALK_KEY"
curl https://api.donetalk.com/v1/c/{empresa}/teams -H "Authorization: Bearer $DONETALK_KEY"

Número (channelId): desde dónde sale el mensaje.
Plantilla (templateId): una plantilla approved de la cuenta del número. Sus variables aparecen en el texto como {{1}}, {{2}}.
Equipo (reply.id): quién recibe las respuestas.

2. Crear el borrador, con la lista

curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Idempotency-Key: reactivacion-2026-10" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reactivación · octubre",
    "channelId": "…",
    "templateId": "…",
    "variables": [
      { "slot": "body.1", "source": "first_name", "fallback": "hola" },
      { "slot": "body.2", "source": "value.cupon", "format": "upper" }
    ],
    "audience": {
      "kind": "contacts",
      "people": [
        { "phone": "+5548999990001", "name": "Ana Souza", "values": { "cupon": "ana10" } },
        { "phone": "+5548999990002", "name": "Bruno Lima", "values": { "cupon": "bru15" } }
      ]
    },
    "reply": { "kind": "team", "id": "…" },
    "startAt": "2026-10-24T12:00:00.000Z"
  }'

Público: people trae el teléfono, el nombre y los valores de cada persona (hasta 20.000; cada teléfono se vuelve un contacto, creado o actualizado, lo que pide también el alcance contacts:write). También puede usar contactos existentes (contactIds), un segmento ({"kind": "segment", "segmentId": "…"}) o un filtro.
Variables: cada {{n}} de la plantilla viene de name, first_name, phone, un campo del contacto (field.<clave>), un valor de la lista (value.<clave>) o un texto fijo. fallback entra cuando falta el valor.
Cuándo: sin startAt empieza al enviar; con él, queda programada. Por omisión solo envía de lunes a viernes, de 9:00 a 18:00, en la zona horaria de la empresa (sendWindow).

3. Revisar antes de enviar

curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/message-preview -H "Authorization: Bearer $DONETALK_KEY"
curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/review -H "Authorization: Bearer $DONETALK_KEY"

La vista previa muestra el texto de cinco personas y las variables vacías. La revisión trae el costo estimado (hasta), el límite diario del número, los presupuestos y si necesitará aprobación. POST /campaigns/{id}/test envía el mensaje a su teléfono.

4. Enviar

curl -X POST https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/submit -H "Authorization: Bearer $DONETALK_KEY"

La respuesta dice running (empezó), scheduled (programada) o pending_approval (la regla de la empresa pide aprobación, y alguien la aprueba en la app). Una clave marcada "Enviar campañas sin esperar aprobación" no espera. Quien recibió marketing en los últimos 7 días, pidió salir o está bloqueado queda fuera; la vista previa del público dice cuántos y por qué.

5. Seguirla

Por los avisos, sin consultar: campaign.started, campaign.recipient.sent, .delivered, .read, .replied, .failed, .opted_out y campaign.completed, con los totales. Cuando la conversación que abrió la campaña concluye, llega conversation.closed con el desenlace y el campaignId.

O consultando:

curl "https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}" -H "Authorization: Bearer $DONETALK_KEY"
curl "https://api.donetalk.com/v1/c/{empresa}/campaigns/{id}/recipients?status=replied" -H "Authorization: Bearer $DONETALK_KEY"

6. Pausar, reanudar, cancelar, reenviar

POST /campaigns/{id}/pause, /resume, /cancel. Las fallas que vale la pena repetir vuelven a la cola con POST /campaigns/{id}/retry (todas, o solo algunos contactos o códigos de error). La campaña también se pausa sola si Meta pausa la plantilla, baja la calidad del número, muchos piden salir o se acaba el presupuesto.

Esta página en Markdown