# Campanhas no WhatsApp

> Template aprovado + lista CSV/JSON + variáveis + agendamento: como montar, enviar, acompanhar e retomar uma campanha.

Uma campanha manda **um template aprovado** para uma lista de contatos, no ritmo do número e dentro da faixa de 24 horas do portfólio. Ela existe só no WhatsApp: Instagram e Messenger não permitem envio em massa.

## Antes de começar

- Uma conexão de WhatsApp **Ativa** ou **Restrita** (veja [Conectar o WhatsApp](/connect/whatsapp/)).
- Um template **Aprovado** da categoria **Marketing** ou **Utilidade** nessa conexão.
- Uma chave com a permissão `send` (para criar e disparar) ou um membro com papel dono, admin ou dev no painel. O papel viewer só lê.

## O ciclo de vida

| Status | O que quer dizer |
|---|---|
| `draft` | Rascunho. Só aqui dá para trocar template, variáveis e destinatários |
| `scheduled` | Agendada para `scheduled_at` |
| `running` | Enviando |
| `waiting_limit` | A faixa de 24 h do portfólio acabou; volta sozinha em `limit_wait_until` |
| `paused` | Pausada por alguém |
| `auto_paused` | Pausada pelo Messajo para proteger o número (veja [Pausas](#pausas-e-o-que-fazer)) |
| `completed` | Não sobrou destinatário na fila |
| `canceled` | Cancelada; os destinatários na fila viram `skipped` |

Nome e velocidade (`rate_limit_mps`) também mudam em `scheduled`, `paused` e `auto_paused`. Editar outra coisa fora do rascunho devolve `409` [`campaign_not_editable`](/errors#campaign_not_editable); uma ação que não vale no status atual devolve `409` [`campaign_invalid_state`](/errors#campaign_invalid_state).

## 1. Criar o rascunho

No painel: **Campanhas → Nova campanha**, escolha a conexão e o template. Pela 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": "pt_BR" },
    "variables": {
      "body": [
        { "contact": "display_name", "default": "cliente" },
        { "column": "cupom" }
      ]
    }
  }'
```

A resposta é a campanha em `draft`. Template que não está aprovado ou não é de marketing/utilidade → `422` [`campaign_template_not_approved`](/errors#campaign_template_not_approved).

## 2. Mapear as variáveis

Cada parâmetro do template precisa de uma origem. Faltou algum → `422` [`campaign_template_mapping_invalid`](/errors#campaign_template_mapping_invalid), com o parâmetro em `details`.

| Origem | Exemplo | De onde vem o valor |
|---|---|---|
| Coluna | `{ "column": "cupom", "default": "BF10" }` | coluna do CSV ou chave de `variables` no JSON |
| Fixo | `{ "value": "até domingo" }` | o mesmo texto para todos |
| Contato | `{ "contact": "display_name", "default": "cliente" }` | nome do contato, quando o Messajo conhece |

- `body`: lista na ordem de `{{1}}`, `{{2}}`… (formato posicional) ou objeto por nome (formato `NAMED`).
- `header`: `{ "params": [...] }` para texto, `{ "media_id": "med_..." }` para imagem, vídeo ou documento, ou `{ "location": {...} }`.
- `buttons`: `[{ "index": 0, "param": {...} }]` para URL dinâmica, código de cupom e payload.

Use `default` quando a coluna pode vir vazia. Sem `default`, a linha vira `invalid` com o motivo `missing_variable:<coluna>`. Valor com mais de 1024 caracteres vira `invalid` (`variable_too_long`).

## 3. Enviar a lista

Baixe o [CSV de exemplo](/examples/campanha-exemplo.csv) para começar:

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

- Cabeçalho obrigatório. A coluna do destino é `to` (ou outra, com `to_column`); as outras viram variáveis.
- Separador `,`, `;` ou tab. BOM do Excel é aceito.
- O destino pode ser telefone (o Messajo tira `+ ( ) - .` e espaços; de 8 a 15 dígitos), BSUID ou o `ctc_…` de um contato da organização.
- Repetidos são ignorados e contados em `rows_duplicate`.

Até 10 000 destinatários por chamada vão no corpo, em JSON, e a importação volta pronta:

```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": { "cupom": "BF10" } } ] }'
```

Arquivo (CSV, JSON ou NDJSON, até 20 MiB) vai por `multipart` e volta `202` com a importação em fila. Acompanhe em `GET /v1/campaigns/{id}/imports/{import_id}`: os 100 primeiros erros saem em `errors` com linha, coluna e código.

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

O teto é 100 000 destinatários por campanha (`422` [`campaign_too_many_recipients`](/errors#campaign_too_many_recipients)).

## 4. Conferir a prévia

`POST /v1/campaigns/{id}/preview` (ou o passo **Prévia** no painel) mostra as primeiras mensagens já montadas, com o corpo e os parâmetros trocados. Confira antes de agendar: mensagem errada não volta.

## 5. Agendar ou começar agora

```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 e 90 dias à frente (`422` [`campaign_schedule_invalid`](/errors#campaign_schedule_invalid)).
- Precisa de pelo menos um destinatário válido ([`campaign_no_recipients`](/errors#campaign_no_recipients)) e de nenhuma importação em andamento ([`campaign_import_in_progress`](/errors#campaign_import_in_progress)).
- `POST /start` dispara agora; `POST /unschedule` volta para rascunho.

## Velocidade e a faixa do portfólio

- **Velocidade:** por padrão, 80 % da vazão do número (`send_rate_mps`); os 20 % restantes ficam para os envios da API. Ajuste com `rate_limit_mps`, de 1 até a vazão do número.
- **Faixa de 24 h:** a Meta limita quantos contatos **únicos** recebem template por dia (250, 2 000, 10 000, 100 000 ou ilimitado). O limite é do **portfólio**: todos os números do mesmo Business dividem a faixa. O Messajo para em 95 % da faixa e a campanha vai para `waiting_limit`; quando os envios mais antigos saem da janela de 24 h, ela volta sozinha.
- Contato com a janela de atendimento aberta não gasta faixa.
- O contador só enxerga o que sai pelo Messajo. Se você também envia por outra ferramenta no mesmo portfólio, deixe folga.

`GET /v1/campaigns/{id}` traz `estimate`: destinatários válidos, velocidade efetiva, duração estimada e quanto resta da faixa.

## Pausas e o que fazer

O Messajo pausa sozinho (`auto_paused`), avisa por e-mail donos, admins e quem criou a campanha, e emite `campaign.paused` com `auto: true`. Para continuar, `POST /resume` (ou **Retomar** no painel): retomar aceita a qualidade atual como nova referência.

| `pause_reason` | Por quê | O que fazer |
|---|---|---|
| `quality_low` | A qualidade do número caiu (ou o envio ficou limitado) | Revise conteúdo e lista; insistir derruba a qualidade e a faixa |
| `template_paused` | O template saiu de **Aprovado** | Espere voltar a Aprovado em **Templates** |
| `template_quality_low` | A qualidade do template caiu | Ajuste o template ou a lista: muita gente bloqueando ou denunciando |
| `error_rate` | 20 % ou mais de falhas nos últimos 100 envios | Baixe o relatório e veja os códigos |
| `marketing_limit` | 10 % ou mais de `131049` | Veja abaixo |
| `spam_limit` | A Meta respondeu `131048` (suspeita de spam) | Espere algumas horas e reduza a velocidade |
| `policy` | Bloqueio por política ou token caído | Resolva na conexão; pode precisar reconectar |
| `connection_not_active` | A conexão não está ativa | Reconecte e retome |
| `spend_cap` | O teto de gasto do mês foi atingido | Suba o teto em Configurações → Custos ou espere virar o mês, e retome |
| `manual` | Alguém pausou | Retome quando quiser |

### 131049 e as 24 horas

[`marketing_limit_reached`](/errors#marketing_limit_reached) (`131049`) é a Meta segurando marketing para quem já recebeu demais. Não é falha do número e não adianta repetir logo: o contato só volta a receber depois de um tempo que a Meta não informa (na prática, um dia ou mais). Termine a campanha, espere pelo menos 24 horas e use **Duplicar** com `recipients: "failed"` para mandar só para quem falhou.

## Acompanhar e o relatório

- `GET /v1/campaigns/{id}/recipients?status=failed` lista os destinatários por status: `pending`, `invalid`, `sending`, `sent`, `delivered`, `read`, `failed`, `unknown`, `skipped`.
- `unknown` é envio que pode ter saído (queda da Meta ou do processo no meio). O Messajo **nunca** reenvia às cegas; se a Meta mandar o status depois, o destinatário é atualizado.
- `GET /v1/campaigns/{id}/report` devolve um CSV com `to`, `contact_id`, `status`, `message_id`, `external_id`, `error_code`, `meta_code`, as datas e as colunas de variáveis.
- Os status de entrega continuam chegando até 72 horas depois de `completed`.
- Eventos: `campaign.scheduled`, `campaign.started`, `campaign.paused`, `campaign.resumed`, `campaign.progress` (no máximo 1 por minuto), `campaign.completed` e `campaign.canceled`. As mensagens saem com `campaign: { id, recipient_id }` em `message.sent` e `message.status`. Veja [Eventos](/webhooks/events/).
