Envelope
Todo evento chega no mesmo formato. Só o conteúdo dedata muda.
Todos os eventos
Mensagens
message.status_updated
Dispara a cada mudança de status de uma mensagem que você enviou.
O
status vem em minúsculas. Na API REST o mesmo status vem em maiúsculas, e PENDING aparece aqui como queued.
Quando status é failed, errorDetails traz o motivo já traduzido pela Arara, em um de dois formatos:
-
String, com o que aconteceu e o que fazer. É o formato dos números no provedor atual.
-
Objeto, com
code,whatHappenedehowToAct. É o formato dos números legados.
message.received
Dispara quando o cliente manda mensagem para um número próprio da organização.
Mensagem digitada não traz
reply. Num toque de botão, body repete o texto que o cliente viu. Decida pelo reply.id, não pelo title: o texto pode mudar, o id é seu.
Este evento não dispara para:
- mensagem recebida no número compartilhado da Arara;
- palavras de opt-out (“SAIR”, “PARAR”, “STOP”);
- respostas a confirmações de agendamento.
message.echo
Dispara quando sua equipe manda uma mensagem pelo app do WhatsApp Business, num número em coexistência. Serve para manter o histórico completo no seu sistema.
message.link_clicked
Dispara quando o cliente toca no botão de link de uma mensagem. Vale para template com botão de link dinâmico que usa um link curto da Arara e leva o ID da mensagem no fim da URL. Você recebe um aviso por mensagem, no primeiro clique. Cliques de robôs não contam.
message.flow_reply
Dispara quando o cliente envia a resposta de um formulário. As chaves de fields são as que você definiu ao criar o formulário e não mudam.
Na conversa, a resposta aparece como mensagem do cliente com o texto
Formulário respondido.
Templates
template.updated
Dispara quando o status de um template muda: aprovação, reprovação, pausa ou desativação. Inclui a pausa automática feita pela Arara.
template.category_changed
Dispara quando a Meta muda a categoria de um template. A categoria define o preço por mensagem.
template.quality_updated
Dispara quando a Meta atualiza a qualidade de um template.
Campanhas
campaign.completed
Dispara quando a campanha termina de processar todos os contatos. Não significa que todas as mensagens foram entregues.
O evento não dispara enquanto a campanha está em teste A/B nem quando ela é cancelada. Para métricas detalhadas, consulte
GET /v1/campaigns/{id}.
Conversas
conversation.needs_human
Dispara quando o Brain passa a conversa para um atendente.
Valores comuns de
reason: CUSTOMER_REQUEST, LOW_CONFIDENCE, MAX_MESSAGES, QUOTA_EXCEEDED, LEAD_QUALIFIED_HOT. O Brain também pode escrever um motivo próprio, então não trate a lista como fechada.
Para encerrar o atendimento: POST /v1/brain/handoffs/{handoffId}/resolve, com chave de API de permissão ADMIN.
Números
number.status
Dispara quando a Meta bane, restringe ou reabilita um número, e quando a conexão de um número não é concluída.
status:
number.tier_updated
Dispara quando o limite de envio ou a sinalização de qualidade do número muda.
O que cada limite significa está em Números.
number.name_status
Dispara quando a Meta decide sobre o nome de exibição do número.
Conta
account.review
Dispara quando a Meta conclui a revisão da conta WhatsApp Business.
account.capability
Dispara quando a Meta muda os limites da conta WhatsApp Business.
Os dois valores vêm como string, não como número. Podem vir vazios.
Cobranças
charge.sent, charge.paid, charge.failed, charge.canceled, charge.expired
Disparam quando uma cobrança é enviada ou muda de status, venha de onde vier: conversa, template, automação ou link da automação. Os cinco eventos têm o mesmo data.
Em
charge.sent, status é o status da cobrança no momento do envio, normalmente pending.
O código Pix e o link de pagamento nunca vão no evento. charge.expired dispara quando o expiresAt passa sem pagamento.
Teste
webhook.test
Dispara quando você usa o botão de teste na tela de Webhooks do painel. Gera uma entrega real no histórico, sem efeito em mensagens, templates ou campanhas.
Próximos passos
Webhooks
Receptor, assinatura, retentativas e teste local.
Por que minha mensagem falhou
O que cada motivo de falha significa.