> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Events
> Receive real-time events from FlowIQ when messages are sent, delivered, read, or received — on both WhatsApp and Web.
FlowIQ sends a `POST` request to your registered webhook URL whenever an event occurs. Each payload includes an `event_type` field so you can route events accordingly.
Subscribers registered as type `all` receive every event. Those registered for a specific type (e.g. `message_received`) only receive that one.
***
## Platforms
Webhooks are supported for both **WhatsApp** and **Web** conversations. When registering a webhook in the FlowIQ dashboard, select the platform you want to listen to. Each platform fires its own set of events described below.
***
## WhatsApp Events
### `message_received`
Fired when a user sends you a WhatsApp message.
```json theme={null}
{
"event_type": "message_received",
"whatsapp_id": "27834321234",
"organization_id": "uuid",
"timestamp": "2026-03-07T00:00:00.000Z",
"whatsapp_message_id": "wamid.xxx",
"message_type": "text | image | video | audio | document | location | button | interactive | sticker | contacts | reaction",
"message": "Hello there",
"media_type": null,
"media_url": null,
"file_name": null,
"contact_id": "uuid",
"reply_context_id": null,
"location_data": null,
"reaction": null,
"reacted_to_message_id": null
}
```
* `whatsapp_id` is the contact's phone number with country code (e.g. `27834321234`)
* `media_type` / `media_url` / `file_name` are populated for image, video, audio, and document messages
* `location_data` is `{ latitude, longitude, name, address }` for location messages
* `reply_context_id` is the `wamid` of the message being replied to
* `reaction` / `reacted_to_message_id` are only present when `message_type` is `reaction` — `reaction` is the emoji (e.g. `👍`) and `reacted_to_message_id` is the `wamid` of the message that was reacted to
***
### `message_sent` (WhatsApp)
Fired when Meta confirms your outbound message was sent (lightweight receipt).
```json theme={null}
{
"event_type": "message_sent",
"whatsapp_id": "27834321234",
"whatsapp_message_id": "wamid.xxx",
"organization_id": "uuid",
"status": "sent",
"timestamp": "2026-03-07T00:00:00.000Z"
}
```
***
### `sent_message`
Also fired on `sent` — but with the full message record so you have the message content.
```json theme={null}
{
"event_type": "sent_message",
"whatsapp_id": "27834321234",
"id": "uuid",
"organization_id": "uuid",
"message": "Hi, here is your order update!",
"sender_type": "bot-whatsapp",
"created_at": "2026-03-07T00:00:00.000Z",
"contact_id": "uuid",
"message_status": "sent",
"media_type": null,
"media_url": null,
"media_file_name": null,
"member_id": null,
"whatsapp_message_id": "wamid.xxx",
"reply_context_id": null,
"broadcast_id": null,
"sent_receipt_received": true,
"delivered_receipt_received": false,
"read_receipt_received": false,
"timestamp": "2026-03-07T00:00:00.000Z"
}
```
***
### `message_delivered`
```json theme={null}
{
"event_type": "message_delivered",
"whatsapp_id": "27834321234",
"whatsapp_message_id": "wamid.xxx",
"organization_id": "uuid",
"status": "delivered",
"timestamp": "2026-03-07T00:00:00.000Z"
}
```
***
### `message_read`
```json theme={null}
{
"event_type": "message_read",
"whatsapp_id": "27834321234",
"whatsapp_message_id": "wamid.xxx",
"organization_id": "uuid",
"status": "read",
"timestamp": "2026-03-07T00:00:00.000Z"
}
```
***
### `message_failed`
Fired for `failed`, `undelivered`, and `warning` statuses.
```json theme={null}
{
"event_type": "message_failed",
"whatsapp_id": "27834321234",
"whatsapp_message_id": "wamid.xxx",
"organization_id": "uuid",
"status": "failed | undelivered | warning",
"timestamp": "2026-03-07T00:00:00.000Z"
}
```
***
## Web Events
Web webhooks fire for conversations that happen through the FlowIQ web chat widget. Register them by selecting **Web** as the platform when adding a webhook in the FlowIQ dashboard.
### `message_received`
Fired when a web visitor sends a message (`sender_type: "user-web"`).
```json theme={null}
{
"event_type": "message_received",
"organization_id": "uuid",
"contact_id": "uuid",
"message_id": "uuid",
"message": "Hello there",
"sender_type": "user-web",
"platform": "web",
"timestamp": "2026-03-07T00:00:00.000Z",
"media_type": null,
"media_url": null,
"media_file_name": null,
"more_data": null
}
```
***
### `sent_message`
Fired when a human agent or AI bot sends a web message (`sender_type: "human-web"` or `"bot-web"`).
```json theme={null}
{
"event_type": "sent_message",
"organization_id": "uuid",
"contact_id": "uuid",
"message_id": "uuid",
"message": "Hi, how can I help you?",
"sender_type": "bot-web",
"platform": "web",
"timestamp": "2026-03-07T00:00:00.000Z",
"media_type": null,
"media_url": null,
"media_file_name": null,
"more_data": null
}
```
* `sender_type` will be `"human-web"` for messages sent by a support agent, or `"bot-web"` for AI-generated replies.
* `media_type` / `media_url` / `media_file_name` are populated when the message contains a file or image.
* `more_data` contains any additional structured data attached to the message.
***