# Webhooks do WhatsApp

Bird envia a atividade de WhatsApp ao seu endpoint em tempo real, dispensando a necessidade de polling. Inscreva-se pela página [**Webhooks**](https://bird.com/dashboard/w/webhooks) ou com [`POST /v1/webhooks`](/docs/api/reference/create-webhook). O [Guia de webhooks](/docs/guides/webhooks) cobre endpoints, verificação de assinatura e tentativas de reenvio.

## Eventos disponíveis para inscrição

Cada evento contém um link para seu payload.

| Evento                                                                                              | Dispara quando                                             |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`whatsapp.accepted`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                     | Bird aceita uma solicitação de envio                       |
| [`whatsapp.sent`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                         | Bird entrega a mensagem à rede WhatsApp                    |
| [`whatsapp.delivered`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                    | WhatsApp confirma a entrega no dispositivo do destinatário |
| [`whatsapp.read`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                         | O destinatário abre a mensagem                             |
| [`whatsapp.failed`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                       | A mensagem falha na entrega                                |
| [`whatsapp.rejected`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                     | Bird recusa a mensagem antes de enviá-la                   |
| [`whatsapp.received`](/docs/guides/whatsapp/webhooks/lifecycle#incoming-messages)                   | Um contato envia uma mensagem a você                       |
| [`whatsapp.reacted`](/docs/guides/whatsapp/webhooks/reactions)                                      | Um contato adiciona, altera ou remove uma reação           |
| [`whatsapp_suppression.created`](/docs/guides/whatsapp/webhooks/suppressions)                       | Uma supressão é aberta no seu espaço de trabalho           |
| [`whatsapp.group.join_request_created`](/docs/guides/whatsapp/webhooks/groups#join-request-created) | Alguém solicita participar de um grupo                     |
| [`whatsapp.group.join_request_revoked`](/docs/guides/whatsapp/webhooks/groups#join-request-revoked) | Alguém cancela a solicitação de participar de um grupo     |

A lista de tipos de evento é aberta: novos tipos podem ser adicionados com o tempo, então trate um valor não reconhecido como um evento futuro, não como um erro.

## O envelope do evento

Todo evento WhatsApp usa o [envelope de webhook](/docs/guides/webhooks) padrão: um `type`, um `timestamp` e um objeto `data` específico do tipo.

```json
{
  "data": {
    "direction": "outbound",
    "from": { "phone_number": "+13124495569" },
    "metadata": { "session_id": "sess_4821" },
    "tags": [{ "name": "flow", "value": "login-otp" }],
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:39.913Z",
  "type": "whatsapp.delivered"
}
```

## Campos presentes em todo evento de mensagem

Cada payload de webhook WhatsApp para uma mensagem inclui `whatsapp_id`, `workspace_id`, `direction`, `from`, `to`, `tags` e `metadata`. Os eventos de reação, supressão e grupo não se referem a uma mensagem, então cada um tem sua própria estrutura, descrita na respectiva página.

- **Endereços**: `from` e `to` podem incluir um `phone_number` E.164, um [ID de usuário com escopo de negócio](/docs/guides/whatsapp/business-scoped-user-ids) da Meta em `bsuid`, ou ambos. Uma mensagem recebida de um usuário do WhatsApp também traz o perfil que ele publica, em `username` e `display_name`.
- **`tags` e `metadata`** são `null` quando o envio não incluiu nenhum.
- **`in_reply_to_message_id`** aparece em todo evento de saída de uma mensagem enviada como resposta, de `whatsapp.accepted` até `whatsapp.read`, `whatsapp.failed` ou `whatsapp.rejected`, indicando a mensagem respondida.

Payloads de evento não incluem custo. Consulte a mensagem com [`GET /v1/whatsapp/messages/{message_id}`](/docs/api/reference/get-whatsapp-message) para ver quanto custou.

## Próximos passos

- [Webhooks do ciclo de vida da mensagem](/docs/guides/whatsapp/webhooks/lifecycle): payloads de entrega e de mensagem recebida
- [Eventos do ciclo de vida](/docs/guides/whatsapp/events/lifecycle): consulte a mesma linha do tempo pela API
- [Guia de webhooks](/docs/guides/webhooks): endpoints, assinaturas, tentativas de reenvio e o catálogo completo de eventos

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/whatsapp-api) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)