> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp events

> The events that your endpoint receives about WhatsApp numbers, messages and templates.

Register a [webhook endpoint](https://docs.impellabs.tech/partners/webhooks.md) to receive these events. Each event holds the same objects that the
Partner API answers with, in `data.object`. A key needs the scope in the last column for the endpoint to hear the event.

| Event | When | Scope |
| - | - | - |
| `message.received` | A customer message comes in. | `messages:read` |
| `message.sent` | A message went out, or the business typed it on its own phone. | `messages:read` |
| `message.delivered` | A message reached the customer. | `messages:read` |
| `message.read` | The customer read a message. | `messages:read` |
| `message.failed` | A message did not go out. | `messages:read` |
| `channel.connected` | A hosted sign-up finished. | `channels:read` |
| `channel.status_changed` | A number is switched on, paused, fails or is removed. | `channels:read` |
| `channel.history_synced` | A chunk of the past chats of a number came in. | `channels:read` |
| `template.status_changed` | Meta approves, rejects or pauses a template. | `channels:read` |

## Message events

`data.object` is the message object of [Conversations](https://docs.impellabs.tech/partners/conversations.md). A message that went out also has `status`
and `channel.status`. `message.failed` adds `error` with `message` and `code`.

```json theme={null}
{
  "id": "9b3c1d5f-0000-4000-8000-000000000000",
  "object": "message",
  "role": "assistant",
  "type": "text",
  "text": "Your visit is at 3 pm.",
  "conversation": "5d2f7a3e-0000-4000-8000-000000000000",
  "status": "delivered",
  "channel": { "name": "whatsapp", "to": "+15550100101", "status": "delivered" }
}
```

A send that has no conversation, such as a broadcast, has `id` set to `null`.

## Channel events

`channel.status_changed` carries the number object, with `channel` set to `whatsapp`, `connection` (the state of the
connection) and `removed`. `channel.connected` carries `phone_number_id`, `waba_id`, `display_phone_number`,
`verified_name`, `activated` and `coexistence`. `channel.history_synced` is described in
[Syncing](https://docs.impellabs.tech/partners/channels/whatsapp/syncing.md).

## Template events

```json theme={null}
{
  "object": "template",
  "name": "appointment_reminder",
  "language": "en_US",
  "status": "APPROVED",
  "category": "UTILITY",
  "rejected_reason": "",
  "waba_id": "200000000000001"
}
```

See [Templates](https://docs.impellabs.tech/partners/templates.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.