## Visão geral

Vários módulos da plataforma emitem **eventos** quando algo muda — uma conversa é criada, um pagamento
é confirmado, um negócio muda de etapa, etc. Você pode reagir a esses eventos via **webhooks** ou
pelas **regras de automação** internas.

## Pré-requisitos

- Webhooks configurados (para consumo externo) ou acesso à Automação (para reações internas).

## Passo a passo

1. Identifique o evento do módulo que você quer consumir (ex.: conversa criada, pagamento pago).
2. Para consumo externo: assine o evento no webhook e trate o payload no seu endpoint.
3. Para reações internas: crie uma regra de automação com o gatilho correspondente.
4. Valide e processe o payload de forma idempotente.

## Configurações & opções

- **Webhooks**: assinatura por inbox/conta.
- **Automação**: gatilhos por evento, com condições e ações.
- **Payload**: contém o contexto do evento (ids e dados relevantes).

### Novos eventos por módulo (payloads reais)

Os campos abaixo vêm da fonte real de cada evento — não invente formato. Todos são entregues a
**webhooks de conta**; chamadas e respostas de Flow também vão para o webhook do **canal de API**. A
entrega de cada grupo exige o **recurso do módulo habilitado** na conta (a assinatura funciona mesmo
com o recurso desligado, mas nada é entregue).

### Gestão de Equipe — recurso: Gestão de Equipe

- `wfm_status_changed`, `wfm_break_started` — o agente mudou de status / entrou em pausa. Campos:
  `account_id`, `account_user_id`, `user_id`, `status_key`, `status_event_id`, `base_availability`, `family`.
- `wfm_break_breached` — a pausa ultrapassou o limite. Campos: os acima mais `expected_seconds` e `over_by_seconds`.
- `wfm_break_ended` — o agente saiu de uma pausa (qualquer caminho: troca manual, seletor nativo ou auto-offline).
  Campos: os do início de pausa mais `duration_seconds`, `within_limit` e, se estourou, `over_by_seconds`.
- `wfm_shift_started`, `wfm_shift_ended` — o turno planejado do agente abriu/fechou a janela (avaliado a cada
  minuto pelo servidor). Campos: `account_id`, `account_user_id`, `user_id`, `shift_id`, `schedule_id` (quando
  gerado de um modelo), `date`, `starts_at`, `ends_at`. Cada evento do ciclo dispara exatamente uma vez por turno.

### Transmissões do WhatsApp Hub — recurso: WhatsApp Hub

- `whatsapp_broadcast_started`, `whatsapp_broadcast_completed`, `whatsapp_broadcast_failed` — a transmissão
  mudou de estado. Campos (sem conteúdo de mensagem): `account_id`, `inbox_id`, `broadcast_id`, `display_id`,
  `title`, `status`, `target_type`, `recipients_count`. Funciona em caixas Cloud e WazMeow (WhatsApp Web).

### Boas-vindas e despedidas de grupo do WhatsApp — recurso: WhatsApp Hub

- `whatsapp_group_member_welcomed`, `whatsapp_group_member_farewelled` — disparam **somente quando** a
  mensagem de boas-vindas/despedida foi realmente enviada (idempotente, uma vez por participante por janela de
  deduplicação). Campos: `account_id`, `inbox_id`, `whatsapp_group_id`, `group_jid`, `participant_jid`,
  `participant_phone`, `trigger` (`welcome` ou `farewell`). Sem conteúdo de mensagem.

### Ads Manager — recurso: Growth Ads ou Ads Manager

- `ads_campaign_status_changed` — o status efetivo de uma campanha espelhada mudou. Campos: `account_id`,
  `ad_account_id`, `campaign_id`, `remote_id`, `status`, `effective_status`, `previous_effective_status`.
- `ctwa_conversation_started` — uma conversa via Clique-para-WhatsApp começou (sai na mensagem do cliente). Nesse momento a janela do anúncio fica aguardando a primeira resposta, e `expires_at` é o **prazo de 24 horas para responder**. Se a empresa responde dentro desse prazo, a janela gratuita abre por até 7 dias, ou até o fim exato que a Meta informar. Campos:
  `account_id`, `conversation_id`, `contact_id`, `inbox_id`, `window_id`, `expires_at`.
- `ad_window_expiring` — essa janela está perto de expirar. Mesmos campos.

### Chamadas e respostas de Flow do WhatsApp — recurso: WhatsApp Inbox Suite

- `whatsapp_call_started`, `whatsapp_call_ended`, `whatsapp_call_recording_ready` — ciclo de vida da chamada.
  Campos (os presentes variam por etapa): `provider_call_id`, `conversation_id`, `realtime`, `status`,
  `recording_url`. Entregue a webhooks de conta e de canal de API.
  Na gravação pelo navegador, `whatsapp_call_recording_ready` é emitido depois que a gravação de áudio
  está habilitada na caixa e o áudio enviado é salvo no armazenamento. Só encerrar a chamada não o emite.
  O webhook precisa assinar esse evento; `recording_url` aponta para a gravação disponível.
- `whatsapp_flow_response_received` — o cliente concluiu um WhatsApp Flow. Campos: o objeto `flow_response`
  (`id`, `whatsapp_flow_id`, `screen`, `response`, `contact_id`, `conversation_id`) e o objeto `conversation`.
  Entregue a webhooks de conta e de canal de API.

### Sessões do FlowBuilder — recurso: Flow Builder

- `flow_session_started`, `flow_session_updated`, `flow_session_completed`, `flow_session_failed` — a sessão do
  fluxo iniciou, pausou, concluiu ou falhou. Campos: `id`, `flow_id`, `status`, `current_node_id`,
  `conversation_id`, `account_id`.

## Casos de uso

- Atualizar um sistema externo quando um pagamento é confirmado.
- Disparar uma cadência de follow-up quando um negócio muda de etapa.

## Dicas, limites e boas práticas

- Consulte sempre a fonte real do payload antes de mapear campos (não invente formato).
- Garanta idempotência por identificador do evento.

## Solução de problemas

- **Evento não chega**: confirme a assinatura e o status do endpoint.
- **Campos inesperados**: revise o payload real recebido e ajuste o mapeamento.

## Veja também

- [API REST, tokens e webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-pt-br)
- [Regras de automação](/hc/ajuda/articles/automation-flows-regras-de-automacao-pt-br)
- [Canal de API: o contrato de eventos estruturados](/hc/ajuda/articles/api-developers-api-channel-contract-pt-br)