Pular para o conteúdo

Templates

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.

  • Uma conexão de WhatsApp Ativa ou Restrita (veja Conectar o 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ê.
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)
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; uma ação que não vale no status atual devolve 409 campaign_invalid_state.

No painel: Campanhas → Nova campanha, escolha a conexão e o template. Pela API:

Janela do terminal
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.

Cada parâmetro do template precisa de uma origem. Faltou algum → 422 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).

Baixe o CSV de exemplo para começar:

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:

Janela do terminal
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.

Janela do terminal
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).

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.

Janela do terminal
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" }'
  • 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.

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

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.

  • 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.