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

# messages.received event

> Fired when a message is received.

## `messages.received` event

Fired when a message is received.

> [!NOTE]
>
> Besides messages received from contacts (`fromMe: false`), this event also
> fires for messages sent by **your own number from another device
> or phone**, with `fromMe: true`. Messages sent through the D-API API trigger the
> [`messages.sent`](https://docs.d-api.cloud/en/whatsapp/webhooks/messages-sent) event, **not**
> `messages.received`.

### Payload

**event** `string` *required*

Always `"messages.received"`

**sessionId** `string` *required*

ID of the session that received the message

**timestamp** `string` *required*

ISO 8601 timestamp of receipt

**traceId** `string` *required*

Unique ID for tracing

**data** `object` *required*

**data fields**

**id** `string` *required*

Unique message ID

**type** `string` *required*

`text` | `image` | `video` | `audio` | `document` | `sticker` | `contact` | `location` | `reaction` | `edited_message` | `poll_update` | `list_response` | `template_button_reply` | `list` | `carousel` | `nativeflow`

**message** `string` *required*

Text content of the message

**timestamp** `number` *required*

Unix timestamp in milliseconds

**fromMe** `boolean` *required*

Whether the message was sent by you

**isMetaAI** `boolean` *required*

`true` when the message was written by the Meta AI agent of the contact's
business account (WhatsApp Business Meta AI) rather than by a person.
Always present: `false` in every other case, including history messages,
messages sent by the session and Official API connections, which have no
such signal. Also delivered over RabbitMQ.

**is\_group** `boolean` *required*

Whether it is a group message

**group\_name** `string` *required*

Group name (empty if not a group)

**from\_name** `string` *required*

Sender name

**media\_url** `string | null` *required*

S3 file URL (for media messages)

**from** `object` *required*

**from fields**

**jid** `string` *required*

WhatsApp ID (e.g. `5511999999999@s.whatsapp.net`)

**lid** `string` *required*

WhatsApp internal ID

**name** `string` *required*

Contact name

**to** `object` *required*

**to fields**

**jid** `string` *required*

Recipient's WhatsApp ID

**name** `string` *required*

Recipient name

**media\_data** `object`

Present in media messages (image, video, audio, document, sticker)

**media\_data fields**

**url** `string` *required*

Original WhatsApp URL (temporary)

**file\_length** `number` *required*

Size in bytes

**mimetype** `string` *required*

File MIME type

**width** `number`

Width (image/video/sticker)

**height** `number`

Height (image/video/sticker)

**caption** `string`

Caption (image/video/document)

**duration** `number`

Duration in seconds (audio/video)

**is\_ptt** `boolean`

Push-to-talk / voice message (audio)

**filename** `string`

File name (document)

**is\_animated** `boolean`

Whether it is an animated sticker (sticker)

**data** `object`

Type-specific data for contact, location, reaction, and poll\_update

**ContactData (type=contact)**

**contact\_name** `string` *required*

Contact name

**contact\_phone** `string` *required*

Contact phone number

**display\_name** `string` *required*

Display name

**vcard** `string` *required*

Full vCard

**LocationData (type=location)**

**degrees\_latitude** `number` *required*

Latitude

**degrees\_longitude** `number` *required*

Longitude

**name** `string` *required*

Place name

**address** `string` *required*

Address

**thumbnail** `string` *required*

Base64 image

**ReactionData (type=reaction)**

**original\_message\_id** `string` *required*

Original message ID

**reaction\_text** `string` *required*

Reaction emoji

**reaction\_timestamp** `number` *required*

Reaction timestamp

**target\_participant** `string` *required*

Target participant (in groups)

**EditedMessageData (type=edited\_message)**

**original\_message\_id** `string` *required*

ID of the message that was edited. Use this field — not `data.id`, which is
the ID of the edit event — to find the message in your database.

**edited\_text** `string` *required*

New message content. It is the same value that arrives in `data.message`.

**edit\_timestamp** `number` *required*

Unix timestamp in milliseconds of when the edit was made

**decryption\_failed** `boolean`

Present and `true` when the new content could not be decrypted —
this happens when the edited message predates the session's connection.
In that case `edited_text` comes empty.

**protocol\_type** `number`

Present only in edits coming from history sync
(always `14`). Real-time edits do not include this field.

**original\_message\_key** `object`

Raw reference to the original message, present only in edits
coming from history. Prefer `original_message_id`, which is always present.

**PollUpdateData (type=poll\_update)**

**poll\_creation\_message\_key** `object` *required*

Reference to the original poll

**vote** `object` *required*

Encrypted vote data

**ListResponseData (type=list\_response)**

**selected\_row\_id** `string` *required*

ID of the selected option

**selected\_title** `string` *required*

Title of the selected option

**description** `string`

Description of the selected option

**list\_type** `number` *required*

List type

**original\_list** `object`

**Fields**

**title** `string`

List title

**options** `string[]`

Available options

**TemplateButtonReplyData (type=template\_button\_reply)**

**selected\_id** `string` *required*

ID of the selected button

**selected\_display\_text** `string` *required*

Text of the selected button

**selected\_index** `number` *required*

Button index (0-based)

**quoted\_message\_id** `string` *required*

ID of the message containing the buttons

**ListData (type=list)**

**title** `string` *required*

List title

**description** `string`

Message description/body

**button\_text** `string` *required*

Text of the button that opens the list

**footer\_text** `string`

Footer text

**list\_type** `number` *required*

List type

**sections** `array` *required*

**Section**

**title** `string`

Section title

**rows** `array`

**Row**

**row\_id** `string`

Option ID

**title** `string`

Option title

**description** `string`

Option description

**CarouselData (type=carousel)**

**type** `string` *required*

Always `"carousel"`

**cards** `array` *required*

**Card**

**header\_title** `string`

Card title

**body** `string`

Card body

**NativeFlowData (type=nativeflow)**

**type** `string` *required*

Always `"nativeflow"`

**header\_title** `string`

Header title

**header\_subtitle** `string`

Header subtitle

**header\_has\_media\_attachment** `boolean`

Whether it has attached media

**body** `string`

Message body

**footer** `string`

Footer text

**buttons** `array` *required*

**Button**

**name** `string`

`quick_reply` | `cta_url`

**params\_json** `string`

JSON with the button parameters

**context\_info** `object`

Present in replies and CTWA messages

**context\_info fields**

**stanza\_id** `string`

ID of the quoted message

**quoted\_message\_id** `string`

ID of the quoted message

**quoted\_message** `object`

**Fields**

**body** `string`

Content of the quoted message

**type** `string`

Type of the quoted message

**participant** `string`

Author of the quoted message

**entry\_point\_conversion\_app** `string`

CTWA source app (e.g. `facebook`)

**entry\_point\_conversion\_source** `string`

CTWA source (e.g. `ctwa_ad`)

**external\_ad\_reply** `object`

Ad data (see ExternalAdReply)

**external\_ad\_reply** `object`

CTWA ad data (duplicated at the root of data)

**external\_ad\_reply fields**

**body** `string` *required*

Ad text

**title** `string` *required*

Ad title

**ctwa\_clid** `string` *required*

Click ID for attribution

**source\_id** `string` *required*

Ad ID

**source\_type** `string` *required*

Type (e.g. `ad`)

**source\_url** `string` *required*

Ad URL

**media\_type** `number | string` *required*

Media type. On the unofficial API it is numeric (`1` = image, `2` = video);
on Official API (Cloud API) connections it comes as `"image"` / `"video"`,
exactly as Meta sends it in `referral.media_type`.

**media\_url** `string` *required*

Ad media URL

**thumbnail\_url** `string` *required*

Thumbnail URL

***

## Examples by type

> [accordion] text
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T22:51:32.601Z",
>   "traceId": "c17dee440402792623e3ad6d925cb000",
>   "data": {
>     "id": "AC9831DDA691236BA3CE4909A187B703",
>     "type": "text",
>     "message": "Olá!",
>     "timestamp": 1769295092000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "163896103039140@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] image
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:08:46.618Z",
>   "traceId": "c303a70535496ac2ef475d1454e5091d",
>   "data": {
>     "id": "3EB0F61B5D1F94FAFCD306",
>     "type": "image",
>     "message": "",
>     "timestamp": 1769296125000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_data": {
>       "url": "https://mmg.whatsapp.net/...",
>       "width": 1179,
>       "height": 1127,
>       "caption": "",
>       "file_length": 108529,
>       "mimetype": "image/jpeg"
>     },
>     "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB0F61B5D1F94FAFCD306.jpg",
>     "body": ""
>   }
> }
> ```

> [accordion] video
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:09:25.997Z",
>   "traceId": "696a8af1fffc77be1da98883fbf47a18",
>   "data": {
>     "id": "3EB0611DADDC69F4FCE999",
>     "type": "video",
>     "message": "",
>     "timestamp": 1769296161000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_data": {
>       "url": "https://mmg.whatsapp.net/...",
>       "width": 2160,
>       "height": 3840,
>       "caption": "",
>       "duration": 9,
>       "file_length": 15033300,
>       "mimetype": "video/mp4"
>     },
>     "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/video/3EB0611DADDC69F4FCE999.mp4",
>     "body": ""
>   }
> }
> ```

> [accordion] audio
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:07:23.963Z",
>   "traceId": "57b56b9da28101ef39a2bbacb02bf79e",
>   "data": {
>     "id": "3EB04F2EA624ED5AE5E994",
>     "type": "audio",
>     "message": "Audio message",
>     "timestamp": 1769296042000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_data": {
>       "url": "https://mmg.whatsapp.net/...",
>       "is_ptt": true,
>       "duration": 1,
>       "file_length": 3228,
>       "mimetype": "audio/ogg; codecs=opus"
>     },
>     "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/audio/3EB04F2EA624ED5AE5E994.ogg"
>   }
> }
> ```

> [accordion] document
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T22:52:36.560Z",
>   "traceId": "f52c470bc7e83b615fe02f7ae6de99a4",
>   "data": {
>     "id": "AC4E4E0D20923933E79133FED55E86FA",
>     "type": "document",
>     "message": "",
>     "timestamp": 1769295155000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "163896103039140@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_data": {
>       "url": "https://mmg.whatsapp.net/...",
>       "caption": "",
>       "filename": "contrato.pdf",
>       "file_length": 561909,
>       "mimetype": "application/pdf"
>     },
>     "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/application/AC4E4E0D20923933E79133FED55E86FA.pdf",
>     "body": ""
>   }
> }
> ```

> [accordion] sticker
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:25:41.529Z",
>   "traceId": "0cc5f31ce4eeba9d93b69c644047d132",
>   "data": {
>     "id": "3EB07121F4AA1FECE1EB77",
>     "type": "sticker",
>     "message": "Sticker",
>     "timestamp": 1769297140000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_data": {
>       "url": "https://mmg.whatsapp.net/...",
>       "width": 0,
>       "height": 0,
>       "file_length": 31670,
>       "mimetype": "image/webp",
>       "is_animated": false
>     },
>     "media_url": "https://s3.us-east-005.backblazeb2.com/d-api-media/my-session/image/3EB07121F4AA1FECE1EB77.webp"
>   }
> }
> ```

> [accordion] contact
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:07:52.683Z",
>   "traceId": "5e2ce9f64316e43de9f9be26bc883cc6",
>   "data": {
>     "id": "3EB0E400D2D23FCC5F62",
>     "type": "contact",
>     "message": "Contact: João Silva",
>     "timestamp": 1769296072000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "contact_name": "João Silva",
>       "contact_phone": "5511988887777",
>       "display_name": "João Silva",
>       "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Silva;João;;;\nFN:João Silva\nTEL;type=CELL;waid=5511988887777:+55 11 98888-7777\nEND:VCARD"
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] location
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:14:40.667Z",
>   "traceId": "9acf700c9a579d390acfaabcd47d813a",
>   "data": {
>     "id": "2A3245D5D360B969BC24",
>     "type": "location",
>     "message": "Location: -23.550520, -46.633308",
>     "timestamp": 1769296480000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "degrees_latitude": -23.550520,
>       "degrees_longitude": -46.633308,
>       "name": "",
>       "address": "",
>       "thumbnail": "/9j/4AAQSkZJRgABAQAA..."
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] reaction
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:22:59.675Z",
>   "traceId": "902f8bc16e32af74bca7b23c1696377f",
>   "data": {
>     "id": "3EB0798CB87F57E7E8FDEE",
>     "type": "reaction",
>     "message": "👍",
>     "timestamp": 1769296979000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "original_message_id": "2A3245D5D360B969BC24",
>       "reaction_text": "👍",
>       "reaction_timestamp": 1769296978000,
>       "target_participant": ""
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] edited\_message
>
> When someone edits a message that was already sent, WhatsApp does not update the original
> message: it sends a new event. That is why the edit arrives as a regular
> `messages.received`, with `type: "edited_message"`.
>
> `data.id` is the ID **of the edit event**. The message that was edited is in
> `data.data.original_message_id` — use it to update the record in your
> database.
>
> Media caption edits (image, video, document) also arrive here,
> with the new caption in `message`.
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:24:11.204Z",
>   "traceId": "5c1f7b90a4d2ee318f6b0c47d9a1e2f3",
>   "data": {
>     "id": "3EB0C7A91F4D2E88B103AA",
>     "type": "edited_message",
>     "message": "Reunião às 15h (corrigido)",
>     "timestamp": 1769297051000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "edited_text": "Reunião às 15h (corrigido)",
>       "original_message_id": "2A3245D5D360B969BC24",
>       "edit_timestamp": 1769297051000
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] Reply (quoted message)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:24:49.030Z",
>   "traceId": "9cece6b5f07ce817f862c4d5c973081f",
>   "data": {
>     "id": "3EB0957D85886312C6D1AF",
>     "type": "text",
>     "message": "Sim, confirmo!",
>     "timestamp": 1769297088000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "78700997521528@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "context_info": {
>       "participant": "145453781897334@lid",
>       "stanza_id": "3EB056EB4B9E27BA4AA356",
>       "quoted_message_id": "3EB056EB4B9E27BA4AA356",
>       "quoted_message": {
>         "body": "Você confirma o pedido?",
>         "type": "text"
>       }
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] CTWA (Click to WhatsApp Ads)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T21:58:50.581Z",
>   "traceId": "c6dd8822b3949cd97d9247775ee779c2",
>   "data": {
>     "id": "AC73BAB4948202189805FABAF691A878",
>     "type": "text",
>     "message": "Olá, vi o anúncio e gostaria de mais informações.",
>     "timestamp": 1769255953000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "67237780156470@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "context_info": {
>       "entry_point_conversion_app": "facebook",
>       "entry_point_conversion_source": "ctwa_ad",
>       "external_ad_reply": {
>         "body": "Texto do anúncio que o usuário viu",
>         "ctwa_clid": "AffEzn5xEXlKpHmH8uQxUUPR7EIGYRQAt9mGNf6MOUkcOk-Da-5Uej76qNm7vWqEG-zW5otYD_SJ2uGg7nwmeOIGMccQhfsFSryba4VJ6YzxfwYBc0oQwe3f59tjool8tKcmhTx-Ag",
>         "media_type": 2,
>         "media_url": "https://www.facebook.com/reel/863712683259771/",
>         "render_larger_thumbnail": true,
>         "show_ad_attribution": true,
>         "source_id": "120237659567410455",
>         "source_type": "ad",
>         "source_url": "https://fb.me/6LTWcWnZ8",
>         "thumbnail_url": "https://scontent.xx.fbcdn.net/...",
>         "title": "Título do anúncio"
>       }
>     },
>     "external_ad_reply": {
>       "body": "Texto do anúncio que o usuário viu",
>       "ctwa_clid": "AffEzn5xEXlKpHmH8uQxUUPR7EIGYRQAt9mGNf6MOUkcOk-Da-5Uej76qNm7vWqEG-zW5otYD_SJ2uGg7nwmeOIGMccQhfsFSryba4VJ6YzxfwYBc0oQwe3f59tjool8tKcmhTx-Ag",
>       "media_type": 2,
>       "media_url": "https://www.facebook.com/reel/863712683259771/",
>       "render_larger_thumbnail": true,
>       "show_ad_attribution": true,
>       "source_id": "120237659567410455",
>       "source_type": "ad",
>       "source_url": "https://fb.me/6LTWcWnZ8",
>       "thumbnail_url": "https://scontent.xx.fbcdn.net/...",
>       "title": "Título do anúncio"
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] list\_response
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-25T17:13:05.199Z",
>   "traceId": "c636ed01bbc3b58174997b7379841e31",
>   "data": {
>     "id": "3EB00E07AFE6175651FCE9",
>     "type": "list_response",
>     "message": "Sim",
>     "timestamp": 1769361184000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "context_info": {
>       "participant": "5551920018823@s.whatsapp.net",
>       "quoted_message": {
>         "body": "",
>         "type": "unsupported"
>       },
>       "quoted_message_id": "3EB0180F79608C5E1ACEE7",
>       "stanza_id": "3EB0180F79608C5E1ACEE7"
>     },
>     "data": {
>       "selected_row_id": "t1",
>       "selected_title": "Sim",
>       "description": "aham",
>       "list_type": 1,
>       "original_list": {
>         "title": "Teste",
>         "options": ["Sim"]
>       }
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] template\_button\_reply
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-25T17:11:35.713Z",
>   "traceId": "f60da86820a5e9a776df323b339ce92b",
>   "data": {
>     "id": "3EB00B49BF1006ED22FFE2",
>     "type": "template_button_reply",
>     "message": "Confirmar",
>     "timestamp": 1769361095000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "quoted_message_id": "3EB0319B37B762E820E8AC",
>       "selected_display_text": "Confirmar",
>       "selected_id": "btn_confirm",
>       "selected_index": 0
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] list
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-25T20:15:06.493Z",
>   "traceId": "5458c3c3605f3d5dee7076349890912d",
>   "data": {
>     "id": "3EB0B74CA34A5FC973F4C2",
>     "type": "list",
>     "message": "mensagem aqui",
>     "timestamp": 1769372106000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "224901986312214@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "title": "Teste",
>       "description": "mensagem aqui",
>       "button_text": "Abrir",
>       "footer_text": "",
>       "list_type": 1,
>       "sections": [
>         {
>           "title": "Teste",
>           "rows": [
>             {
>               "row_id": "t1",
>               "title": "Sim",
>               "description": "aham"
>             }
>           ]
>         }
>       ]
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] carousel
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-25T20:15:09.153Z",
>   "traceId": "44663f6360711dc8e6788b6772c2efa9",
>   "data": {
>     "id": "3EB024449A497D01E1DB93",
>     "type": "carousel",
>     "message": "",
>     "timestamp": 1769372108000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "224901986312214@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "type": "carousel",
>       "cards": [
>         {
>           "header_title": "",
>           "body": "Teste"
>         }
>       ]
>     },
>     "media_url": null,
>     "body": ""
>   }
> }
> ```

> [accordion] nativeflow (quick\_reply)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-25T20:15:12.493Z",
>   "traceId": "e53bbcc4cf1b479082617887d8424343",
>   "data": {
>     "id": "3EB0C41EA80CCF889B8E52",
>     "type": "nativeflow",
>     "message": "Corpo da mensagem",
>     "timestamp": 1769372112000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "224901986312214@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "type": "nativeflow",
>       "header_title": "Título",
>       "header_subtitle": "",
>       "header_has_media_attachment": false,
>       "body": "Corpo da mensagem",
>       "footer": "Rodapé",
>       "buttons": [
>         {
>           "name": "quick_reply",
>           "params_json": "{\"display_text\":\"Confirmar\",\"id\":\"btn_confirm\"}"
>         }
>       ]
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] nativeflow (cta\_url)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-25T20:15:10.945Z",
>   "traceId": "02858caf7cd7f62f347f10f2c1ad13bf",
>   "data": {
>     "id": "3EB04C63B7280B8146BC50",
>     "type": "nativeflow",
>     "message": "Corpo da mensagem",
>     "timestamp": 1769372110000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "lid": "224901986312214@lid",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "data": {
>       "type": "nativeflow",
>       "header_title": "Título",
>       "header_subtitle": "",
>       "header_has_media_attachment": false,
>       "body": "Corpo da mensagem",
>       "footer": "Rodapé",
>       "buttons": [
>         {
>           "name": "cta_url",
>           "params_json": "{\"display_text\":\"Abrir site\",\"url\":\"https://exemplo.com\",\"merchant_url\":\"https://exemplo.com\"}"
>         }
>       ]
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] Message sent from your own phone (fromMe: true)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T22:55:00.000Z",
>   "traceId": "c17dee440402792623e3ad6d925cb222",
>   "data": {
>     "id": "3EB0A1B2C3D4E5F60718",
>     "type": "text",
>     "message": "Já estou a caminho!",
>     "timestamp": 1769295300000,
>     "fromMe": true,
>     "isMetaAI": false,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "from_name": "Minha Empresa",
>     "to": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "name": "João"
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] Group message (is\_group: true)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-01-24T23:30:10.120Z",
>   "traceId": "b91f0a2d6c4e5f7081923a4b5c6d7e8f",
>   "data": {
>     "id": "3EB0D2E3F4A5B6C70819",
>     "type": "text",
>     "message": "Bom dia, pessoal!",
>     "timestamp": 1769297410000,
>     "fromMe": false,
>     "isMetaAI": false,
>     "is_group": true,
>     "group_name": "Equipe de Vendas",
>     "participant": "5511999999999@s.whatsapp.net",
>     "from": {
>       "jid": "5511999999999@s.whatsapp.net",
>       "name": "João"
>     },
>     "from_name": "João",
>     "to": {
>       "jid": "120363012345678901@g.us",
>       "name": "Equipe de Vendas"
>     },
>     "media_url": null
>   }
> }
> ```

> [accordion] Message written by the contact's Meta AI (isMetaAI: true)
>
> ```json theme={null}
> {
>   "event": "messages.received",
>   "sessionId": "my-session",
>   "timestamp": "2026-11-05T14:20:05.310Z",
>   "traceId": "4f2a9c1e7b3d5a6c8e0f1a2b3c4d5e6f",
>   "data": {
>     "id": "3EB0CE65A1B2C3D4E5F6",
>     "type": "text",
>     "message": "Hi! I'm Loja Exemplo's virtual assistant. We're open Monday to Friday, 9 am to 6 pm.",
>     "timestamp": 1793974805000,
>     "fromMe": false,
>     "isMetaAI": true,
>     "is_group": false,
>     "group_name": "",
>     "from": {
>       "jid": "5511988887777@s.whatsapp.net",
>       "lid": "163896103039141@lid",
>       "name": "Loja Exemplo"
>     },
>     "from_name": "Loja Exemplo",
>     "to": {
>       "jid": "558005915338@s.whatsapp.net",
>       "name": "Minha Empresa"
>     },
>     "media_url": null
>   }
> }
> ```

***

## Identifying types

| Condition | Type |
| - | - |
| `data.type === "text"` | Text message |
| `data.type === "image"` | Image |
| `data.type === "video"` | Video |
| `data.type === "audio"` | Audio/PTT |
| `data.type === "document"` | Document |
| `data.type === "sticker"` | Sticker |
| `data.type === "contact"` | Contact |
| `data.type === "location"` | Location |
| `data.type === "reaction"` | Reaction |
| `data.type === "poll_update"` | Poll update |
| `data.type === "list_response"` | Interactive list reply |
| `data.type === "template_button_reply"` | Button click |
| `data.type === "list"` | Interactive list message |
| `data.type === "carousel"` | Card carousel |
| `data.type === "nativeflow"` | Message with buttons (quick\_reply/cta\_url) |
| `data.context_info?.quoted_message` | Is a reply |
| `data.context_info?.entry_point_conversion_source === "ctwa_ad"` | Came from an ad |
| `data.isMetaAI === true` | Written by the contact's Meta AI |

***

## Media URLs

Media files are automatically saved to S3 and made available in `data.media_url`.

| Type | Extension | Example |
| - | - | - |
| image | .jpg, .png | `https://s3.../image/{id}.jpg` |
| video | .mp4 | `https://s3.../video/{id}.mp4` |
| audio | .ogg | `https://s3.../audio/{id}.ogg` |
| document | .pdf, .docx | `https://s3.../application/{id}.pdf` |
| sticker | .webp | `https://s3.../image/{id}.webp` |


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