# 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](/es/desarrolladores/modo-prueba/).

## 1. Lo que necesita antes

```bash
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

```bash
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

```bash
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

```bash
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](/es/desarrolladores/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:

```bash
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.