Skip to main content
Esta página lista cada evento que a Arara envia para o seu webhook. Para receber, verificar a assinatura e tratar retentativas, veja Webhooks.

Envelope

Todo evento chega no mesmo formato. Só o conteúdo de data muda.

Todos os eventos

Duas armadilhas ao escrever o handler:
  • Os nomes de campo não seguem um padrão único. message.received, message.echo, message.flow_reply e charge.* usam snake_case (media_url, sender_name, flow_id, amount_cents). message.status_updated e os demais usam camelCase (messageId, providerSid, errorDetails). Não reaproveite o mesmo tipo para os dois.
  • errorDetails muda de tipo. Em message.status_updated ele pode vir como string, como objeto ou null. Confira o tipo antes de ler.

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, whatHappened e howToAct. É o formato dos números legados.
Trate os dois:
O significado de cada motivo está em Por que minha mensagem falhou.

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.
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 nome do evento é o mesmo quando a campanha falha. Confira sempre data.status.
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.
Os campos mudam conforme o 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.