> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # whatsapp.inbound_message.received > Occurs when a WhatsApp inbound message is received. Use `whatsapp.inbound_message.received` to handle this event at your webhook endpoint. ## Triggers Occurs when a WhatsApp inbound message is received. Subscribe to `whatsapp.inbound_message.received` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md). Use the message `type` to select its content object. Media, interactive replies, location, contacts, and system notifications have different fields. The examples below show these variants. ## Syntax YCloud sends an HTTP `POST` request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under **Parameters**. Optional fields and other variants are described below. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "", "type": "whatsapp.inbound_message.received", "apiVersion": "", "createTime": "", "whatsappInboundMessage": { "id": "", "wamid": "", "wabaId": "", "to": "", "sendTime": "", "type": "", "system": { "type": "", "previous_user_id": "", "previous_parent_user_id": "" } } } ``` ## Parameters Validate the `YCloud-Signature` HTTP header before you process the JSON body. See [signature validation](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md). ### Event envelope | Parameter | Type | Required | Description | | - | - | - | - | | `id` | string | Yes | Unique ID for the event. Minimum length: `6`. Maximum length: `128`. | | `type` | string | Yes | Always `whatsapp.inbound_message.received`. | | `apiVersion` | string | Yes | The API version used to render this event. | | `createTime` | string (date-time) | Yes | The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. | ### Event payload | Parameter | Type | Required | Description | | - | - | - | - | | `whatsappInboundMessage` | object | No | Event-specific `whatsappInboundMessage` payload. | The four common envelope fields are required. Payload fields depend on the event variant. In each object table, **Required** applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required. #### whatsappInboundMessage | Parameter | Type | Required | Description | | - | - | - | - | | `id` | string | Yes | Unique ID for the object. | | `wamid` | string | No | The original message ID on WhatsApp's platform. | | `wabaId` | string | No | WhatsApp Business Account ID. | | `from` | string | No | The customer's phone number who sent the message to the business, formatted in [E.164](https://en.wikipedia.org/wiki/E.164) format. | | `fromUserId` | string | No | The customer's WhatsApp Business-scoped user ID (BSUID). | | `fromParentUserId` | string | No | The customer's parent WhatsApp Business-scoped user ID. | | `customerProfile` | object | No | The customer's profile information. | | `to` | string | No | The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. | | `sendTime` | string (date-time) | No | The time at which this message is sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. | | `type` | string | No | WhatsApp inbound message type. See also [WhatsApp webhook messages object](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object).Values: `text`, `image`, `video`, `audio`, `document`, `sticker`, `contacts`, `location`, `interactive`, `button`, `reaction`, `request_welcome`, `order`, `system`, `unsupported`. | | `text` | object | No | When the notification describes a text message, the text object provides the body of the text message. | | `image` | object | No | When a message with media (`image` \| `document` \| `audio` \| `video` \| `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. | | `video` | object | No | When a message with media (`image` \| `document` \| `audio` \| `video` \| `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. | | `audio` | object | No | When a message with media (`image` \| `document` \| `audio` \| `video` \| `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. | | `document` | object | No | When a message with media (`image` \| `document` \| `audio` \| `video` \| `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. | | `sticker` | object | No | When a message with media (`image` \| `document` \| `audio` \| `video` \| `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. | | `interactive` | object | No | When a customer has interacted with your message, this object is included in the message object. | | `location` | object | No | When you receive a notification of a user's static location, the location object provides the details of the location. | | `button` | object | No | When the message type field is set to `button`, this object is included in the message object. | | `contacts` | object\[] | No | Array items are described below. | | `reaction` | object | No | When a user reacts to messages with an emoji, the message type is set to `reaction`, and this field is included. | | `order` | object | No | When a customer places an order, the message type is set to `order`, and this field is included. | | `system` | object | No | When the message type is set to `system`, this field is included. This object describes a user phone number change, a BSUID change, or a possible identity change on WhatsApp. | | `errors` | object\[] | No | Array items are described below. | | `context` | object | No | Message context. | | `referral` | object | No | When a user messages businesses using call-to-actions buttons on [Ads that Click to WhatsApp](https://www.facebook.com/business/help/447934475640650) or a [Facebook Page call-to-action buttons](https://www.facebook.com/help/977869848936797), this field is included as an attachment. | | `groupId` | string | No | WhatsApp group ID. This field is included when the inbound message is sent in a WhatsApp group. | ##### Nested object parameters Expand a field to view its nested parameters. > [accordion] whatsappInboundMessage.customerProfile > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `name` | string | No | Name of the WhatsApp account. | > | `username` | string | No | WhatsApp username. | > [accordion] whatsappInboundMessage.text > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `body` | string | No | Message text. | > [accordion] whatsappInboundMessage.image > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | ID of the media. Can be used to delete the media if stored locally on the client. | > | `link` | string | No | The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. | > | `caption` | string | No | The provided caption for the media. Only present if specified. | > | `filename` | string | No | Filename on the sender's device. This will only be present in `document` media messages. | > | `metadata` | object | No | Metadata pertaining to `sticker` media. | > | `mime_type` | string | No | Mime type of the media. | > | `sha256` | string | No | Checksum. | > [accordion] whatsappInboundMessage.video > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | ID of the media. Can be used to delete the media if stored locally on the client. | > | `link` | string | No | The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. | > | `caption` | string | No | The provided caption for the media. Only present if specified. | > | `filename` | string | No | Filename on the sender's device. This will only be present in `document` media messages. | > | `metadata` | object | No | Metadata pertaining to `sticker` media. | > | `mime_type` | string | No | Mime type of the media. | > | `sha256` | string | No | Checksum. | > [accordion] whatsappInboundMessage.audio > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | ID of the media. Can be used to delete the media if stored locally on the client. | > | `link` | string | No | The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. | > | `caption` | string | No | The provided caption for the media. Only present if specified. | > | `filename` | string | No | Filename on the sender's device. This will only be present in `document` media messages. | > | `metadata` | object | No | Metadata pertaining to `sticker` media. | > | `mime_type` | string | No | Mime type of the media. | > | `sha256` | string | No | Checksum. | > [accordion] whatsappInboundMessage.document > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | ID of the media. Can be used to delete the media if stored locally on the client. | > | `link` | string | No | The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. | > | `caption` | string | No | The provided caption for the media. Only present if specified. | > | `filename` | string | No | Filename on the sender's device. This will only be present in `document` media messages. | > | `metadata` | object | No | Metadata pertaining to `sticker` media. | > | `mime_type` | string | No | Mime type of the media. | > | `sha256` | string | No | Checksum. | > [accordion] whatsappInboundMessage.sticker > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | ID of the media. Can be used to delete the media if stored locally on the client. | > | `link` | string | No | The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. | > | `caption` | string | No | The provided caption for the media. Only present if specified. | > | `filename` | string | No | Filename on the sender's device. This will only be present in `document` media messages. | > | `metadata` | object | No | Metadata pertaining to `sticker` media. | > | `mime_type` | string | No | Mime type of the media. | > | `sha256` | string | No | Checksum. | > [accordion] whatsappInboundMessage.interactive > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `type` | string | No | The type of interactive message received.
  • `button_reply`: Sent when a customer clicks a button.
  • `list_reply`: Sent when a customer selects an item from a list.
  • `nfm_reply`: Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging).
  • `call_permission_reply`: Sent when a customer responds to a call permission request.
| > | `button_reply` | object | No | Sent when a customer clicks a button. Returned when `type` is `button_reply`. | > | `list_reply` | object | No | Sent when a customer selects an item from a list. Returned when `type` is `list_reply`. | > | `nfm_reply` | object | No | Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging). Returned when `type` is `nfm_reply`. | > | `call_permission_reply` | object | No | Sent when a customer responds to a call permission request. Returned when `type` is `call_permission_reply`. This occurs when WhatsApp prompts users to grant callback permissions after they call your business. | > [accordion] whatsappInboundMessage.interactive.button\_reply > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | Unique ID of the clicked button. | > | `title` | string | No | Title of a button. | > [accordion] whatsappInboundMessage.interactive.list\_reply > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `id` | string | No | Unique ID of the selected list item. | > | `title` | string | No | Title of the selected list item. | > | `description` | string | No | Description of the selected row. | > [accordion] whatsappInboundMessage.interactive.nfm\_reply > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `name` | string | No | The name of the flow or form being replied to. | > | `response_json` | string | No | JSON string containing the user's responses to the flow. Contains form field values and flow token. | > | `body` | string | No | The body content of the flow reply message. | > [accordion] whatsappInboundMessage.interactive.call\_permission\_reply > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `response` | string | No | The customer's response to the call permission request.
  • `accept`: User granted permission for business to call back
  • `reject`: User rejected permission for business to call back
| > | `expiration_timestamp` | integer (int64) | No | The timestamp (in seconds) when the call permission expires. Only present when response is "accept" and is\_permanent is false. | > | `is_permanent` | boolean | No | Whether the permission is permanent or temporary.
  • `true`: Permanent authorization (no expiration)
  • `false`: Temporary authorization (expires at expiration\_timestamp)
| > [accordion] whatsappInboundMessage.location > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `latitude` | number (double) | No | Latitude of location being sent. | > | `longitude` | number (double) | No | Longitude of location being sent. | > | `address` | string | No | Address of the location. | > | `name` | string | No | Name of the location. | > | `url` | string | No | URL for the website where the user downloaded the location information. | > [accordion] whatsappInboundMessage.button > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `payload` | string | No | The payload for a button set up by the business that a customer clicked as part of an interactive message. | > | `text` | string | No | Button text. | > [accordion] whatsappInboundMessage.contacts\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `addresses` | object\[] | No | Array items are described below. | > | `birthday` | string | No | `YYYY-MM-DD` formatted string. | > | `emails` | object\[] | No | Array items are described below. | > | `name` | object | Yes | Full contact name formatted as a name object. | > | `org` | object | No | Contact organization information formatted as an org object. | > | `phones` | object\[] | No | Contact phone number(s) formatted as a phone object. | > | `urls` | object\[] | No | Contact URL(s) formatted as a urls object. | > | `vcard` | string | No | Optional vCard supplied with the shared contact payload. | > | `origin` | string | No | Set to `contact_request` when the user shared the contact in response to a request-contact-info message. | > [accordion] whatsappInboundMessage.contacts\[].addresses\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `street` | string | No | Street number and name. | > | `city` | string | No | City name. | > | `state` | string | No | State abbreviation. | > | `zip` | string | No | ZIP code. | > | `country` | string | No | Full country name. | > | `country_code` | string | No | Two-letter country abbreviation. | > | `type` | string | No | Standard values are `HOME` and `WORK`. | > [accordion] whatsappInboundMessage.contacts\[].emails\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `email` | string | No | Email address. | > | `type` | string | No | Standard values are `HOME` and `WORK`. | > [accordion] whatsappInboundMessage.contacts\[].name > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `formatted_name` | string | Yes | Full name, as it normally appears. | > | `first_name` | string | No | First name. | > | `last_name` | string | No | Last name. | > | `middle_name` | string | No | Middle name. | > | `suffix` | string | No | Name suffix. | > | `prefix` | string | No | Name prefix. | > [accordion] whatsappInboundMessage.contacts\[].org > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `company` | string | No | Name of the contact's company. | > | `department` | string | No | Name of the contact's department. | > | `title` | string | No | Contact's business title. | > [accordion] whatsappInboundMessage.contacts\[].phones\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `phone` | string | No | Automatically populated with the `wa_id` value as a formatted phone number. | > | `type` | string | No | Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`. | > | `wa_id` | string | No | WhatsApp ID. | > [accordion] whatsappInboundMessage.contacts\[].urls\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `url` | string | No | URL. | > | `type` | string | No | Standard values are `HOME` and `WORK`. | > [accordion] whatsappInboundMessage.reaction > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `message_id` | string | Yes | Specifies the `wamid` of the message received that contained the reaction. | > | `emoji` | string | No | **Required** when you send a `reaction` message. Set it to `""` if you want to remove the emoji. **Optional** when you received a message from a user. This field is included when a user reacts to messages with an emoji. Otherwise, it indicates a user removed the emoji. | > [accordion] whatsappInboundMessage.order > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `catalog_id` | string | No | The catalog ID. | > | `product_items` | object\[] | No | Array items are described below. | > | `text` | string | No | Text message sent along with the order. | > [accordion] whatsappInboundMessage.order.product\_items\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `product_retailer_id` | string | No | The product SKU identifier. | > | `quantity` | integer (int32) | No | Number of item. | > | `item_price` | number (double) | No | Unitary price of item. | > | `currency` | string | No | Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). | > [accordion] whatsappInboundMessage.system > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `body` | string | No | Describes the system message event. Supported use cases are:
  • Phone number update: for when a user changes from an old number to a new number.
  • Identity update: for when a user identity has changed.
| > | `wa_id` | string | No | Phone number supplied by Meta, without the leading `+`. It can be unchanged or omitted for a BSUID change. | > | `user_id` | string | No | New business-scoped user ID supplied by Meta for a phone number or BSUID change. This field preserves the original snake\_case name. | > | `parent_user_id` | string | No | New Parent BSUID for a phone number or BSUID change, only when enabled and supplied by Meta. This field preserves the original snake\_case name. | > | `previous_user_id` | string | No | Previous business-scoped user ID supplied by Meta. | > | `previous_parent_user_id` | string | No | Previous Parent BSUID, only when enabled and supplied by Meta. | > | `type` | string | No | Supported types are:
  • `user_changed_user_id`: notification that a user changed their BSUID. The phone number can remain unchanged.
  • `user_changed_number`: for a user changed number notification.
  • `user_identity_changed`: for user identity changed notification.
| > | `user` | string | No | \*\*Added to Webhooks for identity updates.\*\*The new WhatsApp user ID of the customer. | > | `new_wa_id` | string | No | \*\*Added to Webhooks for phone number updates.\*\*New WhatsApp ID of the customer. | > [accordion] whatsappInboundMessage.errors\[] > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `code` | string | No | The error code. | > | `title` | string | No | The error title. | > | `message` | string | No | The error message. | > | `error_data` | object | No | An error data object with the following properties:
  • `details`: A string describing the reason for the error. Example: `Message type is currently not supported.`.
| > [accordion] whatsappInboundMessage.context > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `forwarded` | boolean | No | \*\*Added to Webhooks if message was forwarded.\*\*Set to `true` if the received message has been forwarded. | > | `frequently_forwarded` | boolean | No | \*\*Added to Webhooks if message has been frequently forwarded.\*\*Set to `true` if the received message has been forwarded more than five times. | > | `from` | string | No | \*\*Added to Webhooks if message is an inbound reply to a sent message.\*\*The WhatsApp ID (a phone number without the '+' prefix) of the sender of the sent message. | > | `id` | string | No | \*\*Optional.\*\*The `wamid` for the sent message for an inbound reply. `wamid` is the original message ID on WhatsApp’s platform. | > | `referred_product` | object | No | \*\*Required for Product Inquiry Messages.\*\*Specifies the product the user is requesting information about. See also [Sell Products & Services](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services). | > [accordion] whatsappInboundMessage.context.referred\_product > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `catalog_id` | string | No | The catalog ID. | > | `product_retailer_id` | string | No | The product SKU identifier. | > [accordion] whatsappInboundMessage.referral > > | Parameter | Type | Required | Description | > | - | - | - | - | > | `source_url` | string | No | Specifies the URL that leads to the ad or post clicked by the user. Opening this URL takes you to the ad viewed by your user. | > | `source_type` | string | No | Specifies the type of the ad's source. Supported values are "ad" or "post". | > | `source_id` | string | No | Specifies the Meta ID for an ad or post. | > | `headline` | string | No | Specifies the headline used in the ad or post that generated the message. | > | `body` | string | No | The description, or body, from the ad or post that generated the message. | > | `media_type` | string | No | Media present in the ad or post the user clicked. Supported values are "image" or "video". | > | `image_url` | string | No | \*\*Added if media\_type is "image".\*\*Contains a URL to the raw image. | > | `video_url` | string | No | \*\*Added if media\_type is "video".\*\*Contains a URL to the video. | > | `thumbnail_url` | string | No | \*\*Added if media\_type is "video".\*\*Contains a URL to the thumbnail image of the clicked video. | > | `ctwa_clid` | string | No | Click ID generated by Meta for ads that click to WhatsApp. | ## Example The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative. > [accordion] User changed BSUID without exposing a phone number > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_system_user_id_changed_123", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2026-10-10T08:00:00.000Z", > "whatsappInboundMessage": { > "id": "msg_system_user_id_changed_123", > "wamid": "wamid.EXAMPLE_USER_ID_CHANGED", > "wabaId": "whatsapp-business-account-id", > "to": "+12025550123", > "sendTime": "2026-10-10T08:00:00.000Z", > "type": "system", > "system": { > "type": "user_changed_user_id", > "previous_user_id": "US.13491208655302741918", > "previous_parent_user_id": "US.ENT.11815799212886844830" > } > } > } > ``` > [accordion] User changed number with previous BSUIDs > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_system_number_changed_123", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2026-10-10T08:00:00.000Z", > "whatsappInboundMessage": { > "id": "msg_system_number_changed_123", > "wamid": "wamid.EXAMPLE_NUMBER_CHANGED", > "wabaId": "whatsapp-business-account-id", > "from": "+12025550124", > "to": "+12025550123", > "sendTime": "2026-10-10T08:00:00.000Z", > "type": "system", > "system": { > "type": "user_changed_number", > "previous_user_id": "US.13491208655302741918", > "previous_parent_user_id": "US.ENT.11815799212886844830", > "new_wa_id": "16315553333" > } > } > } > ``` > [accordion] Inbound unsupported message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f8709b741c165b4342a714", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "errors": [ > { > "code": "131051", > "title": "Message type unknown", > "message": "Message type unknown", > "error_data": { > "details": "Message type is currently not supported." > } > } > ], > "type": "unsupported" > } > } > ``` > [accordion] Inbound Text message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eEkn26qar3nOB8md", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f872f6741c165b4342a751", > "wamid": "wamid.HBgNODi...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "text", > "text": { > "body": "OK" > }, > "context": { > "from": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] Inbound Text message triggered by click to WhatsApp Ads > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eEkn26qar3nOB8md", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f872f6741c165b4342a751", > "wamid": "wamid.HBgNODi...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "text", > "text": { > "body": "OK" > }, > "referral": { > "source_url": "https://fb.me/xxx", > "source_type": "ad", > "source_id": "MEDIA-ID", > "headline": "Chat with us", > "media_type": "image", > "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg", > "ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd" > } > } > } > ``` > [accordion] Inbound Image message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eEkv5wsCJItpaH01", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f87878509703399f3fd3d0", > "wamid": "wamid.HBgNODi...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "image", > "image": { > "link": "https://example.com/sample", > "caption": "Go for a walk.", > "id": "592623615738103", > "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=", > "mime_type": "image/jpeg" > } > } > } > ``` > [accordion] Inbound Video message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eEkwhYtqMPmYdsN3", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f87991741c165b4342a797", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "video", > "video": { > "link": "https://example.com/sample", > "caption": "Go for a walk.", > "id": "919306472440541", > "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=", > "mime_type": "video/mp4" > } > } > } > ``` > [accordion] Inbound Audio message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eEl1TDAcquZUxzLn", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f87cd3509703399f3fd3f2", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "audio", > "audio": { > "link": "https://example.com/sample", > "id": "712063723747110", > "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=", > "mime_type": "audio/mpeg" > } > } > } > ``` > [accordion] Inbound Document message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eEkz3y7V6TCqgkbK", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f87b2e741c165b4342a79b", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "document", > "document": { > "link": "https://example.com/sample", > "caption": "PDF example", > "filename": "sample.pdf", > "id": "948915536111569", > "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=", > "mime_type": "application/pdf" > } > } > } > ``` > [accordion] Inbound Sticker message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63fc1678741c165b4342b38e", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "sticker", > "sticker": { > "link": "https://example.com/sample", > "id": "729118992174848", > "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=", > "mime_type": "image/webp" > } > } > } > ``` > [accordion] Inbound Location message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63fc18ae509703399f3fe000", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "location", > "location": { > "latitude": 1.40435, > "longitude": 103.79304, > "name": "Singapore Zoo", > "address": "80 Mandai Lake Road Singapore 72", > "url": "https://example.com/sample" > } > } > } > ``` > [accordion] Inbound Contacts message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "contacts", > "contacts": [ > { > "addresses": [ > { > "street": "", > "city": "", > "state": "", > "zip": "", > "country": "", > "country_code": "", > "type": "HOME" > } > ], > "birthday": "2001-01-01", > "emails": [ > { > "email": "recipient@example.com", > "type": "WORK" > } > ], > "name": { > "formatted_name": "", > "first_name": "", > "last_name": "", > "middle_name": "", > "suffix": "", > "prefix": "" > }, > "org": { > "company": "", > "department": "", > "title": "" > }, > "phones": [ > { > "phone": "+447901614024", > "wa_id": "447901614024", > "type": "WORK" > } > ], > "urls": [ > { > "url": "", > "type": "WORK" > } > ] > } > ] > } > } > ``` > [accordion] Inbound Reaction message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "reaction", > "reaction": { > "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==", > "emoji": "👍" > } > } > } > ``` > [accordion] Inbound Template Button message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "button", > "button": { > "payload": "more_about_marketing_friday", > "text": "Learn more" > }, > "context": { > "from": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] Inbound Interactive List Reply message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f73942741c165b43429f86", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "interactive", > "interactive": { > "type": "list_reply", > "list_reply": { > "id": "", > "title": "", > "description": "" > } > }, > "context": { > "from": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] Inbound Interactive Button Reply message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "interactive", > "interactive": { > "type": "button_reply", > "button_reply": { > "id": "", > "title": "" > } > }, > "context": { > "from": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] Inbound Interactive Flow Response message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "interactive", > "interactive": { > "type": "nfm_reply", > "nfm_reply": { > "name": "flow", > "body": "Sent", > "response_json": "{\"flow_token\": \"\", \"optional_param1\": \"\", \"optional_param2\": \"\"}" > } > }, > "context": { > "from": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] Inbound Order message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "order", > "order": { > "catalog_id": "the-catalog_id", > "product_items": [ > { > "product_retailer_id": "the-product-SKU-identifier", > "quantity": 2, > "item_price": 12.5, > "currency": "price-currency" > } > ], > "text": "text-message-sent-along-with-the-order" > }, > "context": { > "from": "+12025550124", > "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o" > } > } > } > ``` > [accordion] Inbound Product Inquiry message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "text", > "text": { > "body": "Can I get this in another color?" > }, > "context": { > "referred_product": { > "catalog_id": "catalog-ID", > "product_retailer_id": "product-ID" > } > } > } > } > ``` > [accordion] Inbound Request Welcome message > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_eF6mVJUj5OWfKXMD", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2023-02-22T12:00:00.000Z", > "whatsappInboundMessage": { > "id": "63f71fb8741c165b434292fb", > "wamid": "wamid.HBgNOD...", > "wabaId": "WABA-ID", > "from": "CUSTOMER-PHONE-NUMBER", > "fromUserId": "US.13491208655302741918", > "fromParentUserId": "US.ENT.11815799212886844830", > "customerProfile": { > "name": "Joe", > "username": "@JoeJoe" > }, > "to": "BUSINESS-PHONE-NUMBER", > "sendTime": "2023-02-22T12:00:00.000Z", > "type": "request_welcome" > } > } > ``` After verifying the signature and durably accepting the event, return a `2xx` response. Process slow work asynchronously. ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.