# Campañas en WhatsApp

> Plantilla aprobada + lista CSV/JSON + variables + programación: cómo armar, enviar, seguir y reanudar una campaña.

Una campaña envía **una plantilla aprobada** a una lista de contactos, al ritmo del número y dentro del nivel de 24 horas del portafolio. Solo existe en WhatsApp: Instagram y Messenger no permiten envíos masivos.

## Antes de empezar

- Una conexión de WhatsApp **Activa** o **Restringida** (consulta [Conectar WhatsApp](/es/connect/whatsapp/)).
- Una plantilla **Aprobada** de la categoría **Marketing** o **Utilidad** en esa conexión.
- Una clave con el permiso `send` (para crear y lanzar) o un miembro con rol de propietario, admin o dev en el panel. El rol viewer solo lee.

## Ciclo de vida

| Estado | Qué significa |
|---|---|
| `draft` | Borrador. Solo aquí se pueden cambiar plantilla, variables y destinatarios |
| `scheduled` | Programada para `scheduled_at` |
| `running` | Enviando |
| `waiting_limit` | Se agotó el nivel de 24 h del portafolio; vuelve sola en `limit_wait_until` |
| `paused` | Pausada por alguien |
| `auto_paused` | Pausada por Messajo para proteger el número (consulta [Pausas](#pausas-y-qué-hacer)) |
| `completed` | No quedó ningún destinatario en la cola |
| `canceled` | Cancelada; los destinatarios en la cola pasan a `skipped` |

El nombre y la velocidad (`rate_limit_mps`) también cambian en `scheduled`, `paused` y `auto_paused`. Editar otra cosa fuera del borrador devuelve `409` [`campaign_not_editable`](/es/errors#campaign_not_editable); una acción que no vale en el estado actual devuelve `409` [`campaign_invalid_state`](/es/errors#campaign_invalid_state).

## 1. Crear el borrador

En el panel: **Campañas → Nueva campaña**, elige la conexión y la plantilla. Por la API:

```bash
curl https://api.messajo.com/v1/campaigns \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "connection_id": "conn_...",
    "template": { "name": "promo_bf", "language": "es" },
    "variables": {
      "body": [
        { "contact": "display_name", "default": "cliente" },
        { "column": "cupon" }
      ]
    }
  }'
```

La respuesta es la campaña en `draft`. Plantilla no aprobada o que no es de marketing/utilidad → `422` [`campaign_template_not_approved`](/es/errors#campaign_template_not_approved).

## 2. Mapear las variables

Cada parámetro de la plantilla necesita un origen. Si falta alguno → `422` [`campaign_template_mapping_invalid`](/es/errors#campaign_template_mapping_invalid), con el parámetro en `details`.

| Origen | Ejemplo | De dónde sale el valor |
|---|---|---|
| Columna | `{ "column": "cupon", "default": "BF10" }` | columna del CSV o clave de `variables` en el JSON |
| Fijo | `{ "value": "hasta el domingo" }` | el mismo texto para todos |
| Contacto | `{ "contact": "display_name", "default": "cliente" }` | nombre del contacto, cuando Messajo lo conoce |

- `body`: lista en el orden de `{{1}}`, `{{2}}`… (formato posicional) u objeto por nombre (formato `NAMED`).
- `header`: `{ "params": [...] }` para texto, `{ "media_id": "med_..." }` para imagen, video o documento, o `{ "location": {...} }`.
- `buttons`: `[{ "index": 0, "param": {...} }]` para URL dinámica, código de cupón y payload.

Usa `default` cuando la columna puede venir vacía. Sin `default`, la fila queda `invalid` con el motivo `missing_variable:<columna>`. Un valor de más de 1024 caracteres queda `invalid` (`variable_too_long`).

## 3. Subir la lista

Descarga el [CSV de ejemplo](/examples/campana-ejemplo.csv) para empezar:

```csv
to,nombre,cupon
5511999990001,Ana,BF10
+55 (21) 99999-0002,Bruno,
ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20
```

- La fila de encabezado es obligatoria. La columna del destino es `to` (u otra, con `to_column`); las demás pasan a ser variables.
- Separador `,`, `;` o tabulador. Se acepta el BOM de Excel.
- El destino puede ser un teléfono (Messajo quita `+ ( ) - .` y espacios; de 8 a 15 dígitos), un BSUID o el `ctc_…` de un contacto de la organización.
- Los repetidos se ignoran y se cuentan en `rows_duplicate`.

Hasta 10 000 destinatarios por llamada van en el cuerpo, en JSON, y la importación vuelve terminada:

```bash
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": [ { "to": "5511999990001", "variables": { "cupon": "BF10" } } ] }'
```

Un archivo (CSV, JSON o NDJSON, hasta 20 MiB) va por `multipart` y vuelve `202` con la importación en cola. Síguela en `GET /v1/campaigns/{id}/imports/{import_id}`: los primeros 100 errores salen en `errors` con fila, columna y código.

```bash
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -F "file=@campana-ejemplo.csv" -F "to_column=to"
```

El tope es de 100 000 destinatarios por campaña (`422` [`campaign_too_many_recipients`](/es/errors#campaign_too_many_recipients)).

## 4. Revisar la vista previa

`POST /v1/campaigns/{id}/preview` (o el paso **Vista previa** en el panel) muestra los primeros mensajes ya armados, con el cuerpo y los parámetros reemplazados. Revísala antes de programar: un mensaje equivocado no vuelve.

## 5. Programar o empezar ya

```bash
curl -X POST https://api.messajo.com/v1/campaigns/cmp_.../schedule \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-27T12:00:00Z" }'
```

- `scheduled_at` entre 1 minuto y 90 días adelante (`422` [`campaign_schedule_invalid`](/es/errors#campaign_schedule_invalid)).
- Necesita al menos un destinatario válido ([`campaign_no_recipients`](/es/errors#campaign_no_recipients)) y ninguna importación en curso ([`campaign_import_in_progress`](/es/errors#campaign_import_in_progress)).
- `POST /start` lanza ahora; `POST /unschedule` vuelve a borrador.

## Velocidad y el nivel del portafolio

- **Velocidad:** por defecto, el 80 % del caudal del número (`send_rate_mps`); el 20 % restante queda para los envíos de la API. Ajústala con `rate_limit_mps`, de 1 hasta el caudal del número.
- **Nivel de 24 h:** Meta limita cuántos contactos **únicos** reciben plantillas por día (250, 2000, 10 000, 100 000 o ilimitado). El límite es del **portafolio**: todos los números del mismo Business comparten el nivel. Messajo se detiene en el 95 % del nivel y la campaña pasa a `waiting_limit`; cuando los envíos más antiguos salen de la ventana de 24 horas, vuelve sola.
- Un contacto con la ventana de atención abierta no gasta nivel.
- El contador solo ve lo que sale por Messajo. Si también envías con otra herramienta en el mismo portafolio, deja margen.

`GET /v1/campaigns/{id}` trae `estimate`: destinatarios válidos, velocidad efectiva, duración estimada y cuánto queda del nivel.

## Pausas y qué hacer

Messajo pausa solo (`auto_paused`), avisa por correo a propietarios, admins y a quien creó la campaña, y emite `campaign.paused` con `auto: true`. Para continuar, `POST /resume` (o **Reanudar** en el panel): reanudar acepta la calidad actual como nueva referencia.

| `pause_reason` | Por qué | Qué hacer |
|---|---|---|
| `quality_low` | Bajó la calidad del número (o el envío quedó limitado) | Revisa contenido y lista; insistir baja la calidad y el nivel |
| `template_paused` | La plantilla dejó de estar **Aprobada** | Espera a que vuelva a Aprobada en **Plantillas** |
| `template_quality_low` | Bajó la calidad de la plantilla | Ajusta la plantilla o la lista: mucha gente bloquea o denuncia |
| `error_rate` | 20 % o más de fallos en los últimos 100 envíos | Descarga el informe y revisa los códigos |
| `marketing_limit` | 10 % o más de `131049` | Consulta abajo |
| `spam_limit` | Meta respondió `131048` (sospecha de spam) | Espera unas horas y baja la velocidad |
| `policy` | Bloqueo por política o token caído | Resuélvelo en la conexión; puede pedir reconexión |
| `connection_not_active` | La conexión no está activa | Reconecta y reanuda |
| `spend_cap` | Se alcanzó el tope de gasto del mes | Sube el tope en Configuración → Costos o espera al próximo mes, y reanuda |
| `manual` | Alguien la pausó | Reanuda cuando quieras |

### 131049 y las 24 horas

[`marketing_limit_reached`](/es/errors#marketing_limit_reached) (`131049`) es Meta frenando el marketing a quien ya recibió demasiado. No es un problema del número y no sirve repetir enseguida: el contacto solo vuelve a recibir después de un tiempo que Meta no informa (en la práctica, un día o más). Termina la campaña, espera al menos 24 horas y usa **Duplicar** con `recipients: "failed"` para enviar solo a quienes fallaron.

## Seguimiento e informe

- `GET /v1/campaigns/{id}/recipients?status=failed` lista los destinatarios por estado: `pending`, `invalid`, `sending`, `sent`, `delivered`, `read`, `failed`, `unknown`, `skipped`.
- `unknown` es un envío que puede haber salido (caída de Meta o del proceso a mitad de camino). Messajo **nunca** reenvía a ciegas; si Meta manda el estado después, el destinatario se actualiza.
- `GET /v1/campaigns/{id}/report` devuelve un CSV con `to`, `contact_id`, `status`, `message_id`, `external_id`, `error_code`, `meta_code`, las fechas y las columnas de variables.
- Los estados de entrega siguen llegando hasta 72 horas después de `completed`.
- Eventos: `campaign.scheduled`, `campaign.started`, `campaign.paused`, `campaign.resumed`, `campaign.progress` (como máximo 1 por minuto), `campaign.completed` y `campaign.canceled`. Los mensajes llevan `campaign: { id, recipient_id }` en `message.sent` y `message.status`. Consulta [Eventos](/es/webhooks/events/).
