Guia de campanhas

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

  1. 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.
  2. Crie a campanha. Ela nasce parada (status igual a STOPPED), com um número por contato.
  3. Confira. No oficial, a verificação de início diz o que impede o envio e quais riscos pedem confirmação.
  4. Inicie ou agende. O envio segue em segundo plano. No oficial, ele pode sair em ondas.
  5. Acompanhe. Progresso ao vivo, linha do tempo, números um a um e exportação em CSV.
  6. 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

AssuntoWhatsApp oficialWhatsApp não oficial
Rotas/whatsapp/campaigns/unofficial-whatsapp/campaigns
MensagemtemplateId, um modelo aprovado, enviado por businessPhoneId.message, com o tipo e o texto, enviada por instanceId.
Contatos no pedidophoneNumberstargets
Público por leads ou planilharecipientsrecipients (só campanhas para leads)
VariáveisAs do modelo, na ordem do envio.Os marcadores {{1}}, {{2}} do texto.
RitmoTudo de uma vez ou em ondas (smartPolicy).Intervalo entre envios (sendDelayMinMs, sendDelayMaxMs) e limite diário (dailyCap).
Verificação de inícioBloqueios, riscos que pedem confirmação e recomendações.Só bloqueios.
Saída do leadA 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" } }
  ]
}
CampoO que é
nameNome da campanha. Obrigatório.
templateIdO modelo, que precisa estar pronto para envio e ser da mesma conta do número. Obrigatório.
businessPhoneIdO número do WhatsApp Business que envia. Obrigatório.
departmentIdO departamento da campanha. Obrigatório para quem participa de mais de um departamento.
phoneNumbersOs contatos, um por item: number, name, variables e metadata. Use este campo ou recipients, nunca os dois.
recipientsO público por leads ou por planilha. Veja Público: leads ou planilha, abaixo.
workflowId, enableWorkflowO fluxo que atende as respostas.
agentId, enableAgentResponsesO agente de IA que atende as respostas.
pipelineIdO funil em que as conversas da campanha entram.
enableAnalysis, enableAutoStaging, enableAutoMemoryAnálise de IA das conversas, mudança automática de etapa e memória automática. Ficam desligadas quando o agente responde.
showTemplateInCrmGrava o modelo enviado no histórico da conversa.
exitRiskAcknowledgedtrue 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.
smartPolicyO disparo em ondas. Veja Disparo inteligente em ondas.
scheduledStartInício agendado, em RFC 3339, entre 5 minutos e 1 ano à frente. Veja Agendar.
confirmedFingerprintA confirmação dos riscos da verificação, ao agendar.

Regras de phoneNumbers:

  • number vai só com dígitos, com o código do país 55 e o DDD, como 5584999990001. Outro formato recusa a criação com 400 e phoneNumbers em expected. 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.
  • variables preenche 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.
  • metadata fica 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"] }
  ]
}
CampoO que é
nameNome da campanha. Obrigatório.
audienceleads (padrão) ou groups.
instanceIdO 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.
messageA mensagem. Veja Mensagens do não oficial, abaixo.
targetsOs destinos: number, name, variables e metadata para leads; groupJid e name para grupos. Use este campo ou recipients, nunca os dois.
recipientsO público por leads ou por planilha, só em campanhas para leads.
sendDelayMinMs, sendDelayMaxMsO 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.
dailyCapQuantos 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.
scheduledStartIní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:

kindCamposRegras
textbodiesPelo menos um texto.
image, video, documentmediaId, bodies (legenda, opcional), fileNamemediaId obrigatório.
audiomediaId, exitTextmediaId obrigatório. O áudio não mostra legenda: o comando de saída vai em exitText, um texto curto enviado logo depois do áudio.
menubodies, style, options, footer, buttonPelo 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 é o id de um arquivo da biblioteca de mídias, enviado com POST /medias (referência).
  • Cada opção do menu tem id (obrigatório), title (até 24 caracteres) e description (opcional).
  • exitText só 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:

CampoO que é
sourceleads (uma seleção de leads) ou list (uma planilha enviada).
selectionA seleção de leads, com source igual a leads.
listIdA lista enviada, com source igual a list.
variablesDe 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:

CampoO que é
keyQual 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.
sourceUm campo do lead, literal (um texto fixo) ou default (o valor padrão de uma variável de agente).
valueO texto fixo, com source igual a literal.
columnNuma lista, a coluna pelo nome do cabeçalho (nunca pela posição).
missingO que fazer com quem não tem o valor: text (usa o texto padrão) ou exclude (deixa o contato de fora).
textO texto padrão, com missing igual a text. Não pode ser vazio.

Os campos do lead que uma variável pode usar:

sourceValor
lead.first_namePrimeiro nome.
lead.nameNome completo.
lead.nicknameApelido.
lead.districtBairro do endereço principal.
lead.cityCidade do endereço principal.
lead.owner_nameNome do responsável pelo lead.
lead.custom:CHAVEUm 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 responde 422 audience_variable_choice_required, com a chave da variável em details.variable. Um lead deixado de fora por exclude entra pulado, com o motivo missing_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 responde 422 audience_list_variables_missing.
  • column numa seleção de leads responde 400 audience_variable_column_needs_list; column junto de source, 400 audience_variable_column_with_source; default numa 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 workflowId ou agentId, cada variável que o fluxo ou o agente pede vem do público do mesmo jeito, com key igual 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": []
}
CampoO que é
matchedQuantos leads ou linhas o público encontrou.
withContactQuantos têm número.
sendableQuantos recebem. Fica null enquanto houver um bloqueio em blockers.
out, outTotalQuem fica de fora, contado uma vez pelo primeiro motivo.
variablesUma 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).
blockersO que impede a criação, como variable_choice_required, template_required, message_required ou list_column_missing.
selectionCom source igual a leads: confirmCount e fingerprint, a confirmação que a criação exige.
listCom 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:

MotivoCódigoQuando
no_identity920003O lead não tem número.
blocked920001O lead está bloqueado.
opted_out920002O lead pediu para não receber mensagens.
cooldown920004O lead está no intervalo entre disparos. Entra com o status NOT_ELIGIBLE_POSSIBLE_SPAM.
already_in_running_campaign920007O lead está em outra campanha em andamento.
missing_variable920006Falta o valor de uma variável com missing igual a exclude.
over_cap920008O 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"]
  }
}
CampoO que éRegra
presetO perfil de partida: conservative, standard ou aggressive.Obrigatório.
firstWaveSize, minWaveSize, maxWaveSizeTamanho da primeira onda, o menor e o maior.1 ≤ mínimo ≤ primeira ≤ máximo.
growthQuanto a onda cresce quando tudo vai bem.De 1 a 4.
shrinkQuanto a onda diminui quando há sinal de risco.Maior que 0 e menor que 1.
observeWaitMinutesQuanto tempo observar cada onda antes de decidir a próxima.Pelo menos 20.
maxObserveWaitMinutesQuanto esperar pela leitura da saúde do modelo e do número antes de pausar.Entre observeWaitMinutes e 1.440.
maxWavesPerDayOndas por dia. 0 não limita.Não negativo.
maxSlowWavesAtFloorQuantas ondas seguidas reduzidas no tamanho mínimo antes de pausar.De 1 a 10.
minSampleQuantos envios avaliados antes de julgar as taxas.Pelo menos 20.
failureRateSlow, failureRateStopTaxas 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.
engagementRateSlowFatia de envios barrados pelo limite de engajamento da Meta que reduz a onda.Maior que 0 e menor que 1.
onTemplateYellow, onPhoneYellow, onPhoneRedO 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.
sendHoursOs 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:

Campoconservativestandardaggressive
firstWaveSize100200500
minWaveSize5050100
maxWaveSize2.0005.00020.000
growth1,523
observeWaitMinutes18012060
failureRateSlow / failureRateStop0,05 / 0,100,08 / 0,150,10 / 0,20
engagementRateSlow0,020,030,05
onTemplateYellowpausepauseslow_down
onPhoneYellow / onPhoneRedpause / stopslow_down / pauseslow_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 a failureRateStop.
  • 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 de failureRateSlow, ou envios barrados pelo limite de engajamento acima de engagementRateSlow. As taxas só contam depois de minSample envios avaliados.

Sem nada que pause ou pare:

  • Sem contatos pendentes, a campanha termina.
  • Reduzida no tamanho mínimo por maxSlowWavesAtFloor ondas 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 maxWavesPerDay atingido, espera o dia seguinte.
  • Senão, sai a próxima onda: a primeira com firstWaveSize; depois, multiplicada por growth até maxWaveSize, ou por shrink até minWaveSize quando 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ódigoNívelQuando
audience_emptyblockO público ainda não tem ninguém para receber.
nothing_pendingblockNão há números pendentes.
access_revokedblockO workspace não pode mais usar o número ou o modelo.
plan_inactiveblockO workspace não tem assinatura ativa.
template_missingblockO modelo não existe mais.
template_not_readyblockO modelo não está pronto para envio.
form_not_sendableblockO formulário do modelo não pode ser enviado.
phone_unavailableblockO número não pode enviar agora.
health_unreadableblockAlgum dado da verificação não pôde ser lido agora; observed diz quantos.
monthly_cap_fullblockO limite mensal de envios do workspace acabou.
sheet_variable_unfit, sheet_variable_attentionblockA planilha de uma variável do fluxo ou do agente não serve.
template_red, template_yellowconfirmA qualidade do modelo está vermelha ou amarela.
template_flaggedconfirmO modelo foi sinalizado pela Meta.
template_reclassifiedconfirmO modelo foi criado em outra categoria e agora é marketing.
no_exitconfirmO modelo não oferece uma saída ao lead.
last_run_failuresconfirmA última execução teve 15% ou mais de falhas do modelo (com pelo menos 50 envios avaliados).
last_run_spam_limitconfirmA última execução bateu no limite de spam da Meta.
balance_shortconfirmO saldo não cobre o envio.
last_run_engagementadviceA última execução teve 3% ou mais de envios barrados pelo limite de engajamento.
last_run_undeliverableadviceA última execução teve mensagens não entregues.
opted_out_pendingadviceHá pendentes que pediram para não receber; observed diz quantos.
cap_below_pendingadviceO 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 de POST /whatsapp/campaigns ou de POST /unofficial-whatsapp/campaigns. Pode ter também dealPipelineId (o funil de negociações automáticas) e, no oficial, buttonRoutes (veja Desvios dos botões). scheduledStart aqui é 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 (quote no oficial, estimate no não oficial) e a verificação de início (check, com findings, fingerprint, blocks e needsConfirmation). Nada é criado.
  • POST /campaign-drafts/{channel}/{id}/launch (referência) cria a campanha e decide o início com mode:
modeO que fazPermissão
readyCria a campanha parada, pronta para iniciar depois.Criar campanhas.
nowRoda a verificação, cria, aplica as configurações do rascunho e inicia.Iniciar campanhas.
scheduleRoda 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çãoOficialNão oficial
Iniciar ou retomarPOST /whatsapp/campaigns/{id}/start, com confirmedFingerprint opcional. Responde 202.POST /unofficial-whatsapp/campaigns/{id}/start. Responde 200 com {"status": "START"}.
PausarPOST /whatsapp/campaigns/{id}/pause. Só em execução; os pendentes aguardam.POST /unofficial-whatsapp/campaigns/{id}/pause.
PararPOST /whatsapp/campaigns/{id}/stop. Os pendentes não são enviados.POST /unofficial-whatsapp/campaigns/{id}/stop.
Envio rápidoPOST /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úmerosPOST /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:

  1. Reiniciar. POST /whatsapp/campaigns/{id}/reset/prepare (referência) devolve resetCode. POST /whatsapp/campaigns/{id}/reset com {"resetCode": "..."} volta todos os números para PENDING e devolve a campanha, quantos números voltaram (resetCount) e um novo código (newResetCode). Não vale com a campanha em execução.
  2. Limpar o histórico. POST /whatsapp/campaigns/{id}/clear-history/prepare devolve clearCode e quantas conversas serão apagadas (messageCount). POST /whatsapp/campaigns/{id}/clear-history com {"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

RotaO que faz
GET /whatsapp/campaigns/{id}/entriesLista 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}/entriesInclui 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/exportExporta os números em CSV.
GET /whatsapp/campaigns/{id}/progressO progresso ao vivo.
GET /whatsapp/campaigns/{id}/timelineA 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_grant ou um botão cuja ação no modelo é de saída respondem 422 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 responde 422 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ódigoStatusO que fazer
audience_source_ambiguous400Mande recipients ou os contatos no pedido, não os dois.
audience_variable_choice_required422Escolha missing (text ou exclude) para a variável de details.variable.
audience_list_column_unknown422Use em column um cabeçalho que a lista tem.
audience_list_variables_missing422Preencha as linhas sem o valor de uma variável.
audience_list_not_found / audience_list_expired404 / 410Envie a planilha de novo.
selection_fingerprint_mismatch400Conte de novo com o filtro atual.
selection_changed409Conte de novo e confirme a nova contagem.
selection_count_required400Mande expectedCount e fingerprint da contagem.
exit_risk_not_acknowledged422Use um modelo com saída ou mande exitRiskAcknowledged: true.
unofficial_campaign_needs_exit422Mostre um comando como /sair em cada variação, ou em exitText no áudio.
campaign_launch_blocked409Resolva os bloqueios da verificação.
campaign_launch_unconfirmed409Reenvie com o fingerprint atual em confirmedFingerprint.
start_permission_required403Agendar e iniciar exigem a permissão de iniciar campanhas.
campaign_template_not_ready422Use um modelo pronto para envio.
campaign_template_phone_mismatch422Use um modelo da mesma conta do número.
campaign_schedule_in_past / campaign_schedule_out_of_window400Agende entre 5 minutos e 1 ano à frente.
campaign_running409Pause a campanha antes de mudar o agendamento.
send_start_from_leads / send_selection_locked409Campanha preparada a partir de leads: inicie pela revisão em Leads.
smart_campaign_blocked409Os sinais da Meta ainda pedem pausa; veja expected.reasons.
campaign_draft_incomplete422Salve o corpo da campanha em payload.request.

O formato das respostas de erro está em Erros.

Veja também