WhatsApp Mobile-Originated Events

Event Notification Service (ENS) supports several event notification types and their corresponding payloads for WhatsApp messages.

Mobile-Originated Event Attributes

Attribute	Type	Description
`eventCategoryType`	String	A string that represents the type of event that occurred.
`eid`	String	The Enterprise ID associated with the account that produced the event.
`mid`	String	The Business Units ID of the account that produced the event.
`senderType`	String	The type of sender. The only supported value is `WhatsApp`.
`messageType`	String	The type of message.
`channelId`	String	The ID of the channel that sent the message.
`messageId`	String	A unique message ID that’s generated by WhatsApp.
`timestampUTC`	Number	The date and time when the event occurred, represented as a UTC Unix timestamp.
`mobileNumber`	String	The subscriber’s mobile number.
`contactId`	String	The subscriber’s contact ID.
`messageBody`	Object	The body of the message. The maximum size of the message is 5,120 characters.

Mobile-Originated Event Text Payload Example

When you receive a message from a customer to your WhatsApp account, you receive a text event. This sample shows an example of a text event.

1[
2  {
3    "eventCategoryType": "EngagementEvents.OttMobileOriginated",
4    "eid": 1982,
5    "mid": 2507,
6    "senderType": "WhatsApp",
7    "messageType": "text",
8    "channelId": "9988776655",
9    "messageId": "db5bcd7c-4e47-46f5-9e35-26eb3e56bce0",
10    "mobileNumber": "112233445566",
11    "contactId": "test_ck_123",
12    "messageBody": {
13      "text": {
14        "body": "Coffee is a cherry"
15      }
16    },
17    "timestampUTC": 1710240312
18  }
19]

Mobile-Originated Event Rich Media Payload Examples

The payload includes metadata about the media type but not the media itself. For example, if the media is a document, the payload provides details such as the file name, MIME type, and other relevant attributes.

To download the media, use the Download rich media inbound messages API.

For information about supported media types, size limitations, and usage details, see WhatsApp Cloud API Documentation: Media.

Document Payload Example

1[
2  {
3    "senderType": "WhatsApp",
4    "messageType": "document",
5    "channelId": "9988776655",
6    "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggOUVBQzMwQzJBNDNGN0QzQkZBNkEzODE0QUI1MDc0Q0EA",
7    "mobileNumber": "112233445566",
8    "contactId": "77601386",
9    "messageBody": {
10      "document": {
11        "filename": "My_Brochure.pdf",
12        "mime_type": "application/pdf",
13        "id": "1089682512601880"
14      }
15    },
16    "eventCategoryType": "EngagementEvents.OttMobileOriginated",
17    "eid": 530000050,
18    "mid": 530000050,
19    "timestampUTC": 1730196900000
20  }
21]

Image Payload Example

1[
2  {
3    "senderType": "WhatsApp",
4    "messageType": "image",
5    "channelId": "9988776655",
6    "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggMzNDNUNEQkRENDQ5RjFDRjNBNkMwOEVDRTY0MkNGQUEA",
7    "mobileNumber": "112233445566",
8    "contactId": "77601386",
9    "messageBody": {
10      "image": {
11        "caption": "CAPTION",
12        "id": "853002090326945",
13        "mime_type": "image/jpeg"
14      }
15    },
16    "eventCategoryType": "EngagementEvents.OttMobileOriginated",
17    "eid": 530000050,
18    "mid": 530000050,
19    "timestampUTC": 1730197082000
20  }
21]

Video Payload Example

1[
2  {
3    "senderType": "WhatsApp",
4    "messageType": "video",
5    "channelId": "9988776655",
6    "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggRkYzMjkzOEY4QzBEREE1RTZCMUU2RTYzRjE5M0U1NzkA",
7    "mobileNumber": "112233445566",
8    "contactId": "77601386",
9    "messageBody": {
10      "video": {
11        "caption": "CAPTION",
12        "id": "1961433010935917",
13        "mime_type": "video/mp4"
14      }
15    },
16    "eventCategoryType": "EngagementEvents.OttMobileOriginated",
17    "eid": 530000050,
18    "mid": 530000050,
19    "timestampUTC": 1730197197000
20  }
21]

Audio Payload Example

1[
2  {
3    "senderType": "WhatsApp",
4    "messageType": "audio",
5    "channelId": "9988776655",
6    "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggNDFBNDUwMUE5NjdDRkEwQUYxMUM5NTgzNjI0MjA0MjgA",
7    "mobileNumber": "112233445566",
8    "contactId": "77601386",
9    "messageBody": {
10      "audio": {
11        "id": "1234196991167350",
12        "mime_type": "audio/ogg; codecs=opus"
13      }
14    },
15    "eventCategoryType": "EngagementEvents.OttMobileOriginated",
16    "eid": 530000050,
17    "mid": 530000050,
18    "timestampUTC": 1730196907000
19  }
20]

Interactive Payload Examples

Interactive messages in WhatsApp include messages with WhatsApp Flows, lists, and quick reply buttons.

WhatsApp Flows

This example shows the payload that’s sent to ENS when a customer submits a flow in a WhatsApp message.

1{
2  "senderType": "WhatsApp",
3  "messageType": "interactive",
4  "channelId": "9988776655",
5  "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggNDFBNDUwMUE5NjdDRkEwQUYxMUM5NTgzNjI0Mexample",
6  "mobileNumber": "4255550042",
7  "contactId": "99887766",
8  "messageBody": {
9    "interactive": {
10      "nfm_reply": {
11        "body": "Sent",
12        "name": "flow",
13        "response_json": "{\"screen_0_Email_2\": \"gpatel@example.com\", \"flow_token\": \"unused\", \"screen_0_LastName_1\": \"Patel\", \"screen_0_FirstName_0\": \"Gorav\"}"
14      },
15      "type": "nfm_reply"
16    }
17  },
18  "eventCategoryType": "EngagementEvents.OttMobileOriginated",
19  "eid": 987654,
20  "mid": 987654,
21  "timestampUTC": 1741118180000
22}

Lists

This example shows the payload that’s sent to ENS when a customer selects a list item in a WhatsApp message.

1{
2  "senderType": "WhatsApp",
3  "messageType": "interactive",
4  "channelId": "9988776655",
5  "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggNDFBNDUwMUE5NjdDRkEwQUYxMUM5NTgzNjI0Mexample",
6  "mobileNumber": "4255550042",
7  "contactId": "99887766",
8  "messageBody": {
9    "interactive": {
10      "list_reply": {
11        "id": "upgrade_account",
12        "title": "Upgrade my account"
13      },
14      "type": "list_reply"
15    }
16  },
17  "eventCategoryType": "EngagementEvents.OttMobileOriginated",
18  "eid": 987654,
19  "mid": 987654,
20  "timestampUTC": 1741118180000
21}

Quick Reply Buttons

This example shows the payload that’s sent to ENS when a customer clicks a quick reply button in a WhatsApp message.

1{
2  "senderType": "WhatsApp",
3  "messageType": "interactive",
4  "channelId": "9988776655",
5  "messageId": "wamid.HBgMOTE3ODM4NTA5NzgzFQIAEhggNDFBNDUwMUE5NjdDRkEwQUYxMUM5NTgzNjI0Mexample",
6  "mobileNumber": "4255550042",
7  "contactId": "99887766",
8  "messageBody": {
9    "interactive": {
10      "button_reply": {
11        "id": "repeat-order",
12        "title": "Re-order an item"
13      },
14      "type": "button_reply"
15    }
16  },
17  "eventCategoryType": "EngagementEvents.OttMobileOriginated",
18  "eid": 987654,
19  "mid": 987654,
20  "timestampUTC": 1741118180000
21}