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.
Antes de começar
Seção intitulada “Antes de começar”- 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ê.
O ciclo de vida
Seção intitulada “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) |
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.
1. Criar o rascunho
Seção intitulada “1. Criar o rascunho”No painel: Campanhas → Nova campanha, escolha a conexão e o template. Pela API:
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.
2. Mapear as variáveis
Seção intitulada “2. Mapear as variáveis”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 (formatoNAMED).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
Seção intitulada “3. Enviar a lista”Baixe o CSV de exemplo para começar:
to,nome,cupom5511999990001,Ana,BF10+55 (21) 99999-0002,Bruno,ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20- Cabeçalho obrigatório. A coluna do destino é
to(ou outra, comto_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 octc_…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:
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.
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \ -H "Authorization: Bearer $MESSAJO_API_KEY" \O teto é 100 000 destinatários por campanha (422 campaign_too_many_recipients).
4. Conferir a prévia
Seção intitulada “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
Seção intitulada “5. Agendar ou começar agora”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_atentre 1 minuto e 90 dias à frente (422campaign_schedule_invalid).- Precisa de pelo menos um destinatário válido (
campaign_no_recipients) e de nenhuma importação em andamento (campaign_import_in_progress). POST /startdispara agora;POST /unschedulevolta para rascunho.
Velocidade e a faixa do portfólio
Seção intitulada “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 comrate_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
Seção intitulada “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
Seção intitulada “131049 e as 24 horas”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
Seção intitulada “Acompanhar e o relatório”GET /v1/campaigns/{id}/recipients?status=failedlista 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}/reportdevolve um CSV comto,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.completedecampaign.canceled. As mensagens saem comcampaign: { id, recipient_id }emmessage.sentemessage.status. Veja Eventos.