Como criar, conferir, iniciar e acompanhar campanhas do WhatsApp oficial e do não oficial, com público, variáveis, disparo em ondas, verificação de início e rascunhos.
Uma campanha envia a mesma mensagem para muitos contatos de uma vez, cada um com os seus valores nas variáveis. Há dois canais:
- WhatsApp oficial: envia um modelo aprovado pela Meta por um número da conta do WhatsApp Business. O custo de cada envio sai do saldo do workspace.
- WhatsApp não oficial: envia uma mensagem livre (texto, mídia ou menu) por um número conectado (instância), com um intervalo entre os envios, para leads ou para grupos.
As rotas estão nos grupos WhatsApp: campanhas, WhatsApp não oficial: campanhas, Público de campanhas e Rascunhos de campanha da Referência da API. Esta página explica como as peças se encaixam.
O caminho de uma campanha
- Monte o público. Escolha os contatos: uma lista de números no próprio pedido, uma seleção de leads ou uma planilha enviada. Conte antes de criar.
- Crie a campanha. Ela nasce parada (
statusigual aSTOPPED), com um número por contato. - Confira. No oficial, a verificação de início diz o que impede o envio e quais riscos pedem confirmação.
- Inicie ou agende. O envio segue em segundo plano. No oficial, ele pode sair em ondas.
- Acompanhe. Progresso ao vivo, linha do tempo, números um a um e exportação em CSV.
- Pause, pare ou reinicie quando precisar.
O assistente de criação também pode guardar tudo num rascunho e concluir em um pedido só.
Os dois canais lado a lado
| Assunto | WhatsApp oficial | WhatsApp não oficial |
|---|---|---|
| Rotas | /whatsapp/campaigns | /unofficial-whatsapp/campaigns |
| Mensagem | templateId, um modelo aprovado, enviado por businessPhoneId. | message, com o tipo e o texto, enviada por instanceId. |
| Contatos no pedido | phoneNumbers | targets |
| Público por leads ou planilha | recipients | recipients (só campanhas para leads) |
| Variáveis | As do modelo, na ordem do envio. | Os marcadores {{1}}, {{2}} do texto. |
| Ritmo | Tudo de uma vez ou em ondas (smartPolicy). | Intervalo entre envios (sendDelayMinMs, sendDelayMaxMs) e limite diário (dailyCap). |
| Verificação de início | Bloqueios, riscos que pedem confirmação e recomendações. | Só bloqueios. |
| Saída do lead | A do modelo; sem saída, a criação exige exitRiskAcknowledged. | Cada mensagem precisa mostrar um comando como /sair. |
Criar uma campanha oficial
POST /whatsapp/campaigns (referência) cria a campanha com o modelo, o número que envia e os contatos.
{
"name": "Promoção de novembro",
"templateId": "6f1d1c1e-7a1b-4c2d-9e3f-111111111111",
"businessPhoneId": "8a2e4b6c-1d3f-4a5b-9c7d-222222222222",
"phoneNumbers": [
{ "number": "5584999990001", "name": "Maria Souza", "variables": ["Maria", "20%"] },
{ "number": "5584999990002", "name": "João Lima", "variables": ["João", "15%"], "metadata": { "turma": "A" } }
]
}| Campo | O que é |
|---|---|
name | Nome da campanha. Obrigatório. |
templateId | O modelo, que precisa estar pronto para envio e ser da mesma conta do número. Obrigatório. |
businessPhoneId | O número do WhatsApp Business que envia. Obrigatório. |
departmentId | O departamento da campanha. Obrigatório para quem participa de mais de um departamento. |
phoneNumbers | Os contatos, um por item: number, name, variables e metadata. Use este campo ou recipients, nunca os dois. |
recipients | O público por leads ou por planilha. Veja Público: leads ou planilha, abaixo. |
workflowId, enableWorkflow | O fluxo que atende as respostas. |
agentId, enableAgentResponses | O agente de IA que atende as respostas. |
pipelineId | O funil em que as conversas da campanha entram. |
enableAnalysis, enableAutoStaging, enableAutoMemory | Análise de IA das conversas, mudança automática de etapa e memória automática. Ficam desligadas quando o agente responde. |
showTemplateInCrm | Grava o modelo enviado no histórico da conversa. |
exitRiskAcknowledged | true confirma que você sabe que o modelo não mostra uma saída ao lead. Sem isso, um modelo sem saída recusa a criação com 422 exit_risk_not_acknowledged. Veja Modelos e botões. |
smartPolicy | O disparo em ondas. Veja Disparo inteligente em ondas. |
scheduledStart | Início agendado, em RFC 3339, entre 5 minutos e 1 ano à frente. Veja Agendar. |
confirmedFingerprint | A confirmação dos riscos da verificação, ao agendar. |
Regras de phoneNumbers:
numbervai só com dígitos, com o código do país 55 e o DDD, como5584999990001. Outro formato recusa a criação com400ephoneNumbersemexpected. Números repetidos entram uma vez só.- Cada número vira um lead (o existente, quando o número já é de um lead, ou um novo) e uma entrada da campanha.
variablespreenche as variáveis do modelo na ordem do envio: primeiro a variável do texto do cabeçalho, depois as do corpo. Num modelo com variáveis nomeadas, a ordem é a mesma, e o nome vai junto no envio.metadatafica guardado na entrada; é onde o fluxo e o agente leem as variáveis que pedem.- Até 150.000 contatos por campanha.
A resposta 201 traz a campanha criada, parada (status igual a STOPPED). Leads bloqueados, sem número, com opt-out, no intervalo entre disparos ou em outra campanha em andamento entram pulados, com o motivo (veja Quem fica de fora).
PUT /whatsapp/campaigns/{id} (referência) recebe o mesmo corpo, mas muda só as configurações (nome, modelo, número, funil, fluxo, agente, IA e agendamento). Os contatos mudam pelas rotas de Números da campanha, abaixo.
Criar uma campanha não oficial
POST /unofficial-whatsapp/campaigns (referência) cria a campanha com a mensagem, o número conectado que envia e os destinos.
{
"name": "Abertura de turma",
"instanceId": "4d5e6f70-8192-4a3b-9c4d-888888888888",
"message": {
"kind": "text",
"bodies": [
"Oi {{1}}, a turma {{2}} começa amanhã. Responda /sair para não receber mais mensagens.",
"Olá, {{1}}! Amanhã começa a turma {{2}}. Para sair da lista, responda /sair."
]
},
"sendDelayMinMs": 4000,
"sendDelayMaxMs": 15000,
"dailyCap": 300,
"targets": [
{ "number": "5584999990001", "name": "Maria Souza", "variables": ["Maria", "Inglês 1"] },
{ "number": "5584999990002", "name": "João Lima", "variables": ["João", "Inglês 2"] }
]
}| Campo | O que é |
|---|---|
name | Nome da campanha. Obrigatório. |
audience | leads (padrão) ou groups. |
instanceId | O número conectado que envia. Obrigatório numa campanha para leads; numa campanha para grupos fica vazio, porque cada grupo sai por um dos seus números que participa dele. |
message | A mensagem. Veja Mensagens do não oficial, abaixo. |
targets | Os destinos: number, name, variables e metadata para leads; groupJid e name para grupos. Use este campo ou recipients, nunca os dois. |
recipients | O público por leads ou por planilha, só em campanhas para leads. |
sendDelayMinMs, sendDelayMaxMs | O intervalo entre um envio e o próximo do mesmo número, em milissegundos. O padrão é de 3.000 a 12.000, e o mínimo é 500. |
dailyCap | Quantos envios a campanha faz por dia. 0 usa o limite do número; um valor acima do limite do número vale o do número. |
workflowId, agentId, pipelineId e os campos enable* | Como no oficial. Numa campanha para grupos, o funil fica vazio. |
scheduledStart | Início agendado, entre 5 minutos e 1 ano à frente. |
A resposta 201 traz a campanha parada. Antes de criar, POST /unofficial-whatsapp/campaigns/estimate (referência) estima quanto tempo o envio vai levar com esse ritmo. PUT /unofficial-whatsapp/campaigns/{id} (referência) edita uma campanha que não está em andamento.
Mensagens do não oficial
message.kind escolhe o tipo da mensagem:
kind | Campos | Regras |
|---|---|---|
text | bodies | Pelo menos um texto. |
image, video, document | mediaId, bodies (legenda, opcional), fileName | mediaId obrigatório. |
audio | mediaId, exitText | mediaId obrigatório. O áudio não mostra legenda: o comando de saída vai em exitText, um texto curto enviado logo depois do áudio. |
menu | bodies, style, options, footer, button | Pelo menos uma opção. style é buttons (padrão, até 3 opções) ou list (até 10). button é o texto do botão que abre a lista. |
mediaIdé oidde um arquivo da biblioteca de mídias, enviado comPOST /medias(referência).- Cada opção do menu tem
id(obrigatório),title(até 24 caracteres) edescription(opcional). exitTextsó vale no áudio; nos outros tipos ele é descartado.- Cada texto tem até 65.536 caracteres.
Variáveis e variações
O texto usa marcadores numerados, {{1}}, {{2}}, preenchidos pela posição em variables de cada destino: {{1}} recebe o primeiro valor, {{2}} o segundo. Cada destino precisa trazer pelo menos tantos valores quanto o maior marcador, sem valores vazios.
bodies aceita até 10 variações do texto. Todas precisam usar os mesmos marcadores. Cada destino recebe sempre a mesma variação, escolhida a partir da entrada dele, o que espalha as variações pelo público.
A saída do lead
Numa campanha para leads, cada variação precisa mostrar um comando com barra, como /sair, que o lead pode responder para deixar de receber mensagens. No áudio, o comando vai em exitText. Sem ele, a criação responde 422 unofficial_campaign_needs_exit. Ao editar, a exigência vale quando a mensagem muda.
Um menu em lista:
{
"kind": "menu",
"bodies": ["Oi {{1}}, qual horário você prefere para a aula? Responda /sair para sair da lista."],
"style": "list",
"button": "Ver horários",
"footer": "Escolha uma opção",
"options": [
{ "id": "manha", "title": "Manhã", "description": "Das 8h às 12h" },
{ "id": "tarde", "title": "Tarde", "description": "Das 14h às 18h" },
{ "id": "noite", "title": "Noite" }
]
}Um áudio:
{
"kind": "audio",
"mediaId": "0a1b2c3d-4e5f-4a6b-8c7d-999999999999",
"exitText": "Para não receber mais mensagens, responda /sair."
}Público: leads ou planilha
Em vez de mandar os contatos no pedido (phoneNumbers ou targets), o pedido pode trazer recipients, o mesmo público que o grupo Público de campanhas monta e conta:
| Campo | O que é |
|---|---|
source | leads (uma seleção de leads) ou list (uma planilha enviada). |
selection | A seleção de leads, com source igual a leads. |
listId | A lista enviada, com source igual a list. |
variables | De onde vem cada variável. Veja Variáveis do público, abaixo. |
Mandar recipients junto de phoneNumbers ou targets responde 400 audience_source_ambiguous. Numa campanha para grupos, recipients responde 422 audience_source_unsupported.
Seleção de leads
A seleção usa a linguagem de filtro dos leads. Os modos (ids, all_matching, first_n e everyone), os campos e os limites estão em Filtros. Na criação, fora do modo ids, a seleção precisa vir confirmada pela contagem: expectedCount e fingerprint, como mostra Contar antes de criar.
{
"name": "Reativação de clientes",
"templateId": "6f1d1c1e-7a1b-4c2d-9e3f-111111111111",
"businessPhoneId": "8a2e4b6c-1d3f-4a5b-9c7d-222222222222",
"recipients": {
"source": "leads",
"selection": {
"mode": "all_matching",
"filter": {
"groups": [
{
"conjunction": "and",
"predicates": [
{ "field": "label", "operator": "in", "values": ["5b0f2c1a-3d4e-4f6a-8b7c-9d0e1f2a3b4c"] }
]
}
]
},
"expectedCount": 1250,
"fingerprint": "1b070b1713e2d096d7f2ab6230d488214145d9a26f30dc7390e097c2d43b13fb"
},
"variables": [
{ "key": "1", "source": "lead.first_name", "missing": "text", "text": "cliente" },
{ "key": "2", "source": "literal", "value": "20%" }
]
}
}Planilha enviada
POST /campaign-audience/{channel}/lists (referência), com channel igual a whatsapp ou unofficial, lê no servidor uma planilha CSV, TSV, TXT ou XLSX (a primeira aba) de até 20 MB e 150.000 linhas, ou um texto colado, e guarda a lista por 24 horas. Envie a planilha em multipart/form-data no campo file ou, em JSON, o texto em text. Nenhum lead é criado no envio: a prévia diz quantas linhas já são leads (existing) e quantos leads serão criados na criação da campanha (new).
A primeira linha é lida como cabeçalho quando nomeia alguma coluna conhecida (como telefone, numero, whatsapp, nome, var1), senão as colunas são lidas pela posição. Com o modelo ou a mensagem em context, a prévia diz qual coluna preenche cada variável. As linhas podem ser listadas, incluídas, editadas e removidas pelas rotas de /campaign-audience/{channel}/lists/{listId}/rows, e POST /campaign-audience/{channel}/sample (referência) baixa um modelo da planilha.
Depois, crie a campanha com o listId:
{
"name": "Turma de dezembro",
"templateId": "6f1d1c1e-7a1b-4c2d-9e3f-111111111111",
"businessPhoneId": "8a2e4b6c-1d3f-4a5b-9c7d-222222222222",
"recipients": {
"source": "list",
"listId": "c3d4e5f6-0718-4a29-b3c4-555555555555",
"variables": [
{ "key": "1", "column": "nome" },
{ "key": "2", "source": "literal", "value": "20%" }
]
}
}Uma lista vencida responde 410 audience_list_expired; uma lista de outro canal, 422 audience_list_channel_mismatch.
Variáveis do público
Cada item de variables diz de onde vem uma variável:
| Campo | O que é |
|---|---|
key | Qual variável. Nas variáveis do modelo ou da mensagem, a posição: "1", "2", na ordem do envio (no oficial, a do cabeçalho primeiro). Nas variáveis de um fluxo ou agente, o nome da variável. |
source | Um campo do lead, literal (um texto fixo) ou default (o valor padrão de uma variável de agente). |
value | O texto fixo, com source igual a literal. |
column | Numa lista, a coluna pelo nome do cabeçalho (nunca pela posição). |
missing | O que fazer com quem não tem o valor: text (usa o texto padrão) ou exclude (deixa o contato de fora). |
text | O texto padrão, com missing igual a text. Não pode ser vazio. |
Os campos do lead que uma variável pode usar:
source | Valor |
|---|---|
lead.first_name | Primeiro nome. |
lead.name | Nome completo. |
lead.nickname | Apelido. |
lead.district | Bairro do endereço principal. |
lead.city | Cidade do endereço principal. |
lead.owner_name | Nome do responsável pelo lead. |
lead.custom:CHAVE | Um campo personalizado do lead, pela chave. Campos marcados como sensíveis não podem ir numa mensagem. |
GET /campaign-audience/{channel}/fields (referência) lista os campos disponíveis no workspace.
Regras:
- No WhatsApp, quando algum lead não tem o valor de uma variável, a escolha de
missingé obrigatória. Sem ela, a criação responde422 audience_variable_choice_required, com a chave da variável emdetails.variable. Um lead deixado de fora porexcludeentra pulado, com o motivomissing_variable. - Numa lista, a coluna com o nome da variável vem sugerida. Uma coluna que a lista não tem responde
422 audience_list_column_unknown. As células vazias de uma variável com campo sugerido são preenchidas pelo lead; uma linha que continua sem valor responde422 audience_list_variables_missing. columnnuma seleção de leads responde400 audience_variable_column_needs_list;columnjunto desource,400 audience_variable_column_with_source;defaultnuma variável sem padrão,400 audience_variable_default_unavailable.- Uma chave que a mensagem não tem responde
400 audience_variable_unknown; a mesma chave duas vezes,400 audience_variable_duplicate. - Com
workflowIdouagentId, cada variável que o fluxo ou o agente pede vem do público do mesmo jeito, comkeyigual ao nome dela, e o valor vai para os metadados de cada entrada. A variável de agente com valor padrão é opcional.
Contar antes de criar
POST /campaign-audience/{channel}/count (referência) conta quem recebe antes de a campanha existir, pelas mesmas regras do envio. O corpo é o público mais os campos do canal: no oficial, templateId e, para contar o intervalo entre disparos, businessPhoneId; no não oficial, message e instanceId; e workflowId e agentId quando houver.
{
"source": "leads",
"selection": {
"mode": "all_matching",
"filter": {
"groups": [
{
"conjunction": "and",
"predicates": [
{ "field": "label", "operator": "in", "values": ["5b0f2c1a-3d4e-4f6a-8b7c-9d0e1f2a3b4c"] }
]
}
]
}
},
"templateId": "6f1d1c1e-7a1b-4c2d-9e3f-111111111111",
"businessPhoneId": "8a2e4b6c-1d3f-4a5b-9c7d-222222222222",
"variables": [
{ "key": "1", "source": "lead.first_name", "missing": "text", "text": "cliente" },
{ "key": "2", "source": "literal", "value": "20%" }
]
}A resposta, resumida:
{
"channel": "whatsapp",
"source": "leads",
"matched": 1250,
"withContact": 1236,
"sendable": 1180,
"out": { "no_identity": 14, "opted_out": 31, "already_in_running_campaign": 25 },
"outTotal": 70,
"requiredVariables": 2,
"variables": [
{ "key": "1", "name": "1", "header": false, "source": "lead.first_name", "missing": 14, "policy": "text", "text": "cliente", "choiceRequired": false, "kind": "template" },
{ "key": "2", "name": "2", "header": false, "source": "literal", "value": "20%", "missing": 0, "policy": "", "choiceRequired": false, "kind": "template" }
],
"blockers": [],
"selection": {
"selected": 1250,
"confirmCount": 1250,
"fingerprint": "1b070b1713e2d096d7f2ab6230d488214145d9a26f30dc7390e097c2d43b13fb"
},
"list": null,
"metadataMissing": []
}| Campo | O que é |
|---|---|
matched | Quantos leads ou linhas o público encontrou. |
withContact | Quantos têm número. |
sendable | Quantos recebem. Fica null enquanto houver um bloqueio em blockers. |
out, outTotal | Quem fica de fora, contado uma vez pelo primeiro motivo. |
variables | Uma variável por posição, na ordem do envio, com quantos não têm o valor (missing) e se a escolha de missing ainda falta (choiceRequired). |
blockers | O que impede a criação, como variable_choice_required, template_required, message_required ou list_column_missing. |
selection | Com source igual a leads: confirmCount e fingerprint, a confirmação que a criação exige. |
list | Com source igual a list: linhas, já leads e leads novos. |
Para criar, mande a mesma seleção com expectedCount igual a selection.confirmCount e o fingerprint recebido. Se o filtro mudou depois da contagem, a criação responde 400 selection_fingerprint_mismatch; se a contagem agora é outra, responde 409 selection_changed, com a contagem esperada e a atual em details.expected e details.matched. Conte de novo e confirme. Fora do modo ids, criar sem expectedCount responde 400 selection_count_required.
Quem fica de fora
Os contatos que não podem receber entram na campanha pulados, com o motivo e um código de falha:
| Motivo | Código | Quando |
|---|---|---|
no_identity | 920003 | O lead não tem número. |
blocked | 920001 | O lead está bloqueado. |
opted_out | 920002 | O lead pediu para não receber mensagens. |
cooldown | 920004 | O lead está no intervalo entre disparos. Entra com o status NOT_ELIGIBLE_POSSIBLE_SPAM. |
already_in_running_campaign | 920007 | O lead está em outra campanha em andamento. |
missing_variable | 920006 | Falta o valor de uma variável com missing igual a exclude. |
over_cap | 920008 | O limite mensal de envios do workspace não comporta o contato. |
Disparo inteligente em ondas
Só no oficial. Sem política, a campanha envia todos os contatos de uma vez. Com uma política de ondas, ela envia uma onda, observa o resultado e decide a próxima: cresce quando está tudo bem, diminui quando aparecem sinais de risco e pausa ou para sozinha quando a Meta indica um problema sério.
A política vai em smartPolicy na criação ou em PUT /whatsapp/campaigns/{id}/smart (referência), só com a campanha fora de execução. DELETE na mesma rota desliga as ondas, e GET mostra a política, a fase atual e o histórico de ondas.
{
"preset": "conservative",
"firstWaveSize": 100,
"minWaveSize": 50,
"maxWaveSize": 2000,
"growth": 1.5,
"shrink": 0.5,
"observeWaitMinutes": 180,
"maxObserveWaitMinutes": 300,
"maxWavesPerDay": 4,
"maxSlowWavesAtFloor": 3,
"minSample": 50,
"failureRateSlow": 0.05,
"failureRateStop": 0.1,
"engagementRateSlow": 0.02,
"onTemplateYellow": "pause",
"onPhoneYellow": "pause",
"onPhoneRed": "stop",
"sendHours": {
"timezone": "America/Sao_Paulo",
"days": {
"mon": [{ "start": "08:00", "end": "12:00" }, { "start": "14:00", "end": "18:00" }],
"sat": [{ "start": "09:00", "end": "12:00" }]
},
"holidays": ["2026-12-25"]
}
}| Campo | O que é | Regra |
|---|---|---|
preset | O perfil de partida: conservative, standard ou aggressive. | Obrigatório. |
firstWaveSize, minWaveSize, maxWaveSize | Tamanho da primeira onda, o menor e o maior. | 1 ≤ mínimo ≤ primeira ≤ máximo. |
growth | Quanto a onda cresce quando tudo vai bem. | De 1 a 4. |
shrink | Quanto a onda diminui quando há sinal de risco. | Maior que 0 e menor que 1. |
observeWaitMinutes | Quanto tempo observar cada onda antes de decidir a próxima. | Pelo menos 20. |
maxObserveWaitMinutes | Quanto esperar pela leitura da saúde do modelo e do número antes de pausar. | Entre observeWaitMinutes e 1.440. |
maxWavesPerDay | Ondas por dia. 0 não limita. | Não negativo. |
maxSlowWavesAtFloor | Quantas ondas seguidas reduzidas no tamanho mínimo antes de pausar. | De 1 a 10. |
minSample | Quantos envios avaliados antes de julgar as taxas. | Pelo menos 20. |
failureRateSlow, failureRateStop | Taxas de falha que reduzem e que param, em fração (0.08 é 8%). | Reduzir maior que 0 e menor que parar; parar até 0.5. |
engagementRateSlow | Fatia de envios barrados pelo limite de engajamento da Meta que reduz a onda. | Maior que 0 e menor que 1. |
onTemplateYellow, onPhoneYellow, onPhoneRed | O que fazer com o modelo de qualidade amarela e com o número amarelo ou vermelho: slow_down, pause ou stop. | Pelo menos slow_down. Sem os dois do número, vale o do perfil. |
sendHours | Os horários de envio: timezone, days (de sun a sat, cada um com janelas start e end em HH:MM) e holidays (AAAA-MM-DD). | Obrigatório. |
Uma política que não cumpre essas regras responde 400.
Os três perfis:
| Campo | conservative | standard | aggressive |
|---|---|---|---|
firstWaveSize | 100 | 200 | 500 |
minWaveSize | 50 | 50 | 100 |
maxWaveSize | 2.000 | 5.000 | 20.000 |
growth | 1,5 | 2 | 3 |
observeWaitMinutes | 180 | 120 | 60 |
failureRateSlow / failureRateStop | 0,05 / 0,10 | 0,08 / 0,15 | 0,10 / 0,20 |
engagementRateSlow | 0,02 | 0,03 | 0,05 |
onTemplateYellow | pause | pause | slow_down |
onPhoneYellow / onPhoneRed | pause / stop | slow_down / pause | slow_down / pause |
Nos três, shrink é 0,5, maxObserveWaitMinutes é 300, maxSlowWavesAtFloor é 3, minSample é 50 e maxWavesPerDay é 0. GET /whatsapp/campaign-waves/defaults (referência) devolve os perfis com o horário de envio do departamento ou do workspace já preenchido, e POST /whatsapp/campaign-waves/projection (referência) prevê quando cada onda pode sair, no melhor caso.
Como cada onda é decidida
Antes de cada onda, o motor junta os sinais e aplica o mais forte, nesta ordem de força: continue, wait, slow_down, pause, stop.
- Param sempre (
stop): limite de spam, conta bloqueada, problema de pagamento ou acesso removido nos erros da última onda; modelo desativado, recusado, pausado ou de qualidade vermelha; número banido; taxa de falhas do modelo que, com margem estatística, chega afailureRateStop. - Pausam sempre (
pause): modelo em revisão; número indisponível para envio; modelo reclassificado como marketing; modelo sinalizado pela Meta. - Seguem a política: modelo de qualidade amarela (
onTemplateYellow), número amarelo ou vermelho (onPhoneYellow,onPhoneRed). - Reduzem (
slow_down): taxa de falhas acima defailureRateSlow, ou envios barrados pelo limite de engajamento acima deengagementRateSlow. As taxas só contam depois deminSampleenvios avaliados.
Sem nada que pause ou pare:
- Sem contatos pendentes, a campanha termina.
- Reduzida no tamanho mínimo por
maxSlowWavesAtFloorondas seguidas, ela pausa. - Sem conseguir ler a saúde do modelo e do número, ela espera; depois de
maxObserveWaitMinutes, pausa. - Sem espaço no limite mensal de envios, ela pausa.
- Fora do horário de envio, espera a próxima janela; com
maxWavesPerDayatingido, espera o dia seguinte. - Senão, sai a próxima onda: a primeira com
firstWaveSize; depois, multiplicada porgrowthatémaxWaveSize, ou porshrinkatéminWaveSizequando reduzida. Ao retomar depois de uma pausa automática, recomeça pelo tamanho mínimo. A onda nunca passa dos pendentes nem do espaço no limite mensal.
Iniciar uma campanha cujos sinais ainda pedem pausa responde 409 smart_campaign_blocked, com as regras em expected.reasons.
Verificação de início
Só no oficial. GET /whatsapp/campaigns/{id}/launch-check (referência) roda as mesmas regras que todo início usa e devolve o que encontrou:
{
"findings": [
{ "code": "template_yellow", "level": "confirm" },
{ "code": "opted_out_pending", "level": "advice", "observed": 12 }
],
"fingerprint": "7db9b78975d75265",
"blocks": false,
"needsConfirmation": true
}Cada achado tem um nível:
block: impede o início até ser resolvido.confirm: um risco que pede confirmação.advice: uma recomendação; não impede nada.
| Código | Nível | Quando |
|---|---|---|
audience_empty | block | O público ainda não tem ninguém para receber. |
nothing_pending | block | Não há números pendentes. |
access_revoked | block | O workspace não pode mais usar o número ou o modelo. |
plan_inactive | block | O workspace não tem assinatura ativa. |
template_missing | block | O modelo não existe mais. |
template_not_ready | block | O modelo não está pronto para envio. |
form_not_sendable | block | O formulário do modelo não pode ser enviado. |
phone_unavailable | block | O número não pode enviar agora. |
health_unreadable | block | Algum dado da verificação não pôde ser lido agora; observed diz quantos. |
monthly_cap_full | block | O limite mensal de envios do workspace acabou. |
sheet_variable_unfit, sheet_variable_attention | block | A planilha de uma variável do fluxo ou do agente não serve. |
template_red, template_yellow | confirm | A qualidade do modelo está vermelha ou amarela. |
template_flagged | confirm | O modelo foi sinalizado pela Meta. |
template_reclassified | confirm | O modelo foi criado em outra categoria e agora é marketing. |
no_exit | confirm | O modelo não oferece uma saída ao lead. |
last_run_failures | confirm | A última execução teve 15% ou mais de falhas do modelo (com pelo menos 50 envios avaliados). |
last_run_spam_limit | confirm | A última execução bateu no limite de spam da Meta. |
balance_short | confirm | O saldo não cobre o envio. |
last_run_engagement | advice | A última execução teve 3% ou mais de envios barrados pelo limite de engajamento. |
last_run_undeliverable | advice | A última execução teve mensagens não entregues. |
opted_out_pending | advice | Há pendentes que pediram para não receber; observed diz quantos. |
cap_below_pending | advice | O limite mensal comporta menos que os pendentes (observed é o espaço, limit os pendentes). |
fingerprint resume os riscos de nível confirm. Para iniciar com riscos, envie esse valor em confirmedFingerprint no início:
{ "confirmedFingerprint": "7db9b78975d75265" }Sem a confirmação atual, o início responde 409 campaign_launch_unconfirmed; com um bloqueio, 409 campaign_launch_blocked. Se os riscos mudarem, o fingerprint muda e é preciso confirmar de novo. Em POST /whatsapp/campaigns/{id}/start, a recusa traz em expected os códigos de blocks e confirms separados por vírgula e o fingerprint atual. Na criação com agendamento e no lançamento de um rascunho, ela traz em details as listas blocks e confirms, o fingerprint e os findings.
No não oficial não há confirmação: a verificação só bloqueia, com audience_empty, number_unusable (o número não pode fazer campanhas), number_restricted (o número está restrito pelo WhatsApp), number_cannot_send ou groups_unsendable (há grupos que nenhum dos seus números pode enviar).
Agendar
Com scheduledStart na criação ou na edição, a campanha passa antes pela mesma verificação do início. Um bloqueio responde 409 campaign_launch_blocked e, no oficial, riscos pedem confirmação com 409 campaign_launch_unconfirmed: reenvie com o confirmedFingerprint dos detalhes. Nada é criado nesses casos. A confirmação fica guardada com o agendamento e, no horário, a campanha só inicia se os riscos ainda forem os mesmos; senão, ela fica parada com o motivo em scheduleFailure e quem agendou recebe uma notificação. Agendar exige a permissão de iniciar campanhas (403 start_permission_required).
Rascunhos
O assistente de criação guarda o que já foi preenchido num rascunho, com channel igual a whatsapp ou unofficial_whatsapp. Um rascunho nunca envia e não entra em contagens, métricas, ondas, agendamentos ou verificações.
POST /campaign-drafts/{channel} (referência) salva o nome (até 255 caracteres) e payload, um objeto JSON de até 1 MB com duas partes:
request: o corpo de criação da campanha do canal, o mesmo dePOST /whatsapp/campaignsou dePOST /unofficial-whatsapp/campaigns. Pode ter tambémdealPipelineId(o funil de negociações automáticas) e, no oficial,buttonRoutes(veja Desvios dos botões).scheduledStartaqui é ignorado: o agendamento vem no lançamento.state: o estado do assistente, guardado como veio.
{
"name": "Reativação de clientes",
"payload": {
"request": {
"name": "Reativação de clientes",
"templateId": "6f1d1c1e-7a1b-4c2d-9e3f-111111111111",
"businessPhoneId": "8a2e4b6c-1d3f-4a5b-9c7d-222222222222",
"recipients": {
"source": "list",
"listId": "c3d4e5f6-0718-4a29-b3c4-555555555555",
"variables": [{ "key": "1", "column": "nome" }]
},
"dealPipelineId": "9e8d7c6b-5a49-4382-9170-666666666666",
"buttonRoutes": [
{ "buttonIndex": 0, "buttonText": "Quero saber mais", "kind": "hand_off", "params": { "departmentId": "2b3c4d5e-6f70-4812-9a3b-777777777777" } }
]
},
"state": { "step": "review" }
}
}Salvar não valida a campanha. As verificações completas rodam em duas rotas:
POST /campaign-drafts/{channel}/{id}/review(referência) calcula o público (audience, a mesma contagem do passo de público), o custo (quoteno oficial,estimateno não oficial) e a verificação de início (check, comfindings,fingerprint,blockseneedsConfirmation). Nada é criado.POST /campaign-drafts/{channel}/{id}/launch(referência) cria a campanha e decide o início commode:
mode | O que faz | Permissão |
|---|---|---|
ready | Cria a campanha parada, pronta para iniciar depois. | Criar campanhas. |
now | Roda a verificação, cria, aplica as configurações do rascunho e inicia. | Iniciar campanhas. |
schedule | Roda a verificação e cria com scheduledStart, guardando a confirmação. | Iniciar campanhas. |
{ "mode": "now", "confirmedFingerprint": "3f2a9c1b7d4e8a60" }{ "mode": "schedule", "scheduledStart": "2026-12-01T12:00:00Z" }Se a verificação bloqueia ou pede confirmação, nada é criado e o rascunho continua. Criada a campanha, o rascunho é apagado. A resposta 201 traz campaign, started, mode, warnings e, quando o início ainda recusou depois de criar, startRefusal com o código. warnings avisa o que não pôde ser aplicado: deal_automation_not_applied (o funil de negociações) e button_routes_not_applied (os desvios dos botões).
Um rascunho sem request responde 422 campaign_draft_incomplete; um mode desconhecido, 400 campaign_launch_mode_invalid; schedule sem scheduledStart, 400 campaign_launch_schedule_missing.
Iniciar, pausar, parar e reiniciar
| Ação | Oficial | Não oficial |
|---|---|---|
| Iniciar ou retomar | POST /whatsapp/campaigns/{id}/start, com confirmedFingerprint opcional. Responde 202. | POST /unofficial-whatsapp/campaigns/{id}/start. Responde 200 com {"status": "START"}. |
| Pausar | POST /whatsapp/campaigns/{id}/pause. Só em execução; os pendentes aguardam. | POST /unofficial-whatsapp/campaigns/{id}/pause. |
| Parar | POST /whatsapp/campaigns/{id}/stop. Os pendentes não são enviados. | POST /unofficial-whatsapp/campaigns/{id}/stop. |
| Envio rápido | POST /whatsapp/campaigns/{id}/quick-send: inclui os números de phoneNumbers (opcional) e dispara os pendentes. | POST /unofficial-whatsapp/campaigns/{id}/quick-send, com numbers. |
| Conferir números | POST /unofficial-whatsapp/campaigns/{id}/validate: confere no WhatsApp quais pendentes têm conta e marca os outros para pular. |
O status da campanha é RUNNING, PAUSED, STOPPED ou COMPLETED. Iniciar uma campanha já em execução, pausar uma que não está em execução ou parar uma já parada é recusado. No oficial, sem assinatura ativa, o início responde 402 com error igual a NO_ACTIVE_SUBSCRIPTION.
Uma campanha preparada a partir de leads pela tela de Leads (origem lead_selection) segue regras próprias: parada, ela só começa pela revisão (POST /leads/actions/sends/start), e o início por aqui responde 409 send_start_from_leads; pausada, ela retoma por aqui. Ela também não aceita números novos, envio rápido nem reinício (409 send_selection_locked).
Reiniciar e limpar o histórico
As duas ações pedem confirmação em dois passos:
- Reiniciar.
POST /whatsapp/campaigns/{id}/reset/prepare(referência) devolveresetCode.POST /whatsapp/campaigns/{id}/resetcom{"resetCode": "..."}volta todos os números paraPENDINGe devolve a campanha, quantos números voltaram (resetCount) e um novo código (newResetCode). Não vale com a campanha em execução. - Limpar o histórico.
POST /whatsapp/campaigns/{id}/clear-history/preparedevolveclearCodee quantas conversas serão apagadas (messageCount).POST /whatsapp/campaigns/{id}/clear-historycom{"clearCode": "..."}apaga de forma definitiva as conversas abertas pelos envios; a campanha e os números continuam.
O não oficial tem as mesmas rotas em /unofficial-whatsapp/campaigns/{id}. Um código errado responde 400 no oficial e 403 no não oficial.
Números da campanha
| Rota | O que faz |
|---|---|
GET /whatsapp/campaigns/{id}/entries | Lista paginada dos números, com o lead, o status do envio, o erro da Meta e a conversa. Filtra por status, search, errorCode, etapa e dados da conversa. |
POST /whatsapp/campaigns/{id}/entries | Inclui números (phoneNumbers) numa campanha fora de execução. |
PATCH /whatsapp/campaigns/{id}/entries/{entryId} | Troca número, nome, variáveis, metadados ou liga e desliga a IA do número (automationEnabled). |
DELETE /whatsapp/campaigns/{id}/entries/{entryId} | Tira um número de uma campanha fora de execução. |
GET /whatsapp/campaigns/{id}/entries/export | Exporta os números em CSV. |
GET /whatsapp/campaigns/{id}/progress | O progresso ao vivo. |
GET /whatsapp/campaigns/{id}/timeline | A linha do tempo dos envios. |
O não oficial tem as mesmas rotas em /unofficial-whatsapp/campaigns/{id}, com numbers em vez de phoneNumbers e sem automationEnabled; nele, remover um número vale mesmo com a campanha em andamento. O status de cada número é PENDING, SENT, DELIVERED, READ, FAILED, NOT_ELIGIBLE_POSSIBLE_SPAM ou SKIPPED_NOT_ON_WHATSAPP.
As exportações rodam em segundo plano: a resposta 202 traz o relatório, acompanhado por GET /reports/{id} (referência) até o arquivo ficar pronto. GET /whatsapp/campaigns/entries/export exporta os números de todas as campanhas oficiais do workspace de uma vez.
Desvios dos botões
Só no oficial. Cada botão de resposta rápida do modelo pode ter uma ação, definida no próprio modelo. A campanha pode mudar para onde leva um botão que não é de saída: GET /whatsapp/campaigns/{id}/button-routes (referência) mostra os desvios e PUT na mesma rota os substitui, com a versão lida no cabeçalho If-Match.
- A saída do lead é sempre a do modelo:
opt_out,consent_grantou um botão cuja ação no modelo é de saída respondem422 button_action_exit_locked. - Cada desvio leva
buttonText, o texto do botão que a pessoa viu; um texto que o botão não tem mais responde422 button_action_stale. - No toque, vale a saída do modelo, depois o desvio da campanha, depois a ação do modelo.
Os tipos de ação e os parâmetros de cada um estão em Ações de botão.
Erros mais comuns
| Código | Status | O que fazer |
|---|---|---|
audience_source_ambiguous | 400 | Mande recipients ou os contatos no pedido, não os dois. |
audience_variable_choice_required | 422 | Escolha missing (text ou exclude) para a variável de details.variable. |
audience_list_column_unknown | 422 | Use em column um cabeçalho que a lista tem. |
audience_list_variables_missing | 422 | Preencha as linhas sem o valor de uma variável. |
audience_list_not_found / audience_list_expired | 404 / 410 | Envie a planilha de novo. |
selection_fingerprint_mismatch | 400 | Conte de novo com o filtro atual. |
selection_changed | 409 | Conte de novo e confirme a nova contagem. |
selection_count_required | 400 | Mande expectedCount e fingerprint da contagem. |
exit_risk_not_acknowledged | 422 | Use um modelo com saída ou mande exitRiskAcknowledged: true. |
unofficial_campaign_needs_exit | 422 | Mostre um comando como /sair em cada variação, ou em exitText no áudio. |
campaign_launch_blocked | 409 | Resolva os bloqueios da verificação. |
campaign_launch_unconfirmed | 409 | Reenvie com o fingerprint atual em confirmedFingerprint. |
start_permission_required | 403 | Agendar e iniciar exigem a permissão de iniciar campanhas. |
campaign_template_not_ready | 422 | Use um modelo pronto para envio. |
campaign_template_phone_mismatch | 422 | Use um modelo da mesma conta do número. |
campaign_schedule_in_past / campaign_schedule_out_of_window | 400 | Agende entre 5 minutos e 1 ano à frente. |
campaign_running | 409 | Pause a campanha antes de mudar o agendamento. |
send_start_from_leads / send_selection_locked | 409 | Campanha preparada a partir de leads: inicie pela revisão em Leads. |
smart_campaign_blocked | 409 | Os sinais da Meta ainda pedem pausa; veja expected.reasons. |
campaign_draft_incomplete | 422 | Salve o corpo da campanha em payload.request. |
O formato das respostas de erro está em Erros.
Veja também
- Filtros: a linguagem de filtro e a seleção de leads.
- Modelos e botões: modelos, saída do lead e ações de botão.
- Ações de botão: os tipos de ação de um botão.
- Guia de fluxos e Guia de agentes: as automações que atendem as respostas da campanha.
- Paginação: as listas de campanhas e de números.