whatsapp.inbound_message.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. 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.

{
  "id": "<ID>",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappInboundMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "to": "<TO>",
    "sendTime": "<SEND_TIME>",
    "type": "<TYPE>",
    "system": {
      "type": "<TYPE>",
      "previous_user_id": "<PREVIOUS_USER_ID>",
      "previous_parent_user_id": "<PREVIOUS_PARENT_USER_ID>"
    }
  }
}

Parameters

Validate the YCloud-Signature HTTP header before you process the JSON body. See signature validation.

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. 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 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 format.
`sendTime`	string (date-time)	No	The time at which this message is sent, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.
`type`	string	No	WhatsApp inbound message type. See also WhatsApp webhook 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 or a Facebook Page call-to-action buttons, 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.

whatsappInboundMessage.customerProfile

Parameter	Type	Required	Description
`name`	string	No	Name of the WhatsApp account.
`username`	string	No	WhatsApp username.

whatsappInboundMessage.text

Parameter	Type	Required	Description
`body`	string	No	Message text.

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.

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.

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.

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.

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.

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.

whatsappInboundMessage.interactive.button_reply

Parameter	Type	Required	Description
`id`	string	No	Unique ID of the clicked button.
`title`	string	No	Title of a button.

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.

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.

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)

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.

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.

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.

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`.

whatsappInboundMessage.contacts[].emails[]

Parameter	Type	Required	Description
`email`	string	No	Email address.
`type`	string	No	Standard values are `HOME` and `WORK`.

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.

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.

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.

whatsappInboundMessage.contacts[].urls[]

Parameter	Type	Required	Description
`url`	string	No	URL.
`type`	string	No	Standard values are `HOME` and `WORK`.

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.

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.

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.

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.

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.`.

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.

whatsappInboundMessage.context.referred_product

Parameter	Type	Required	Description
`catalog_id`	string	No	The catalog ID.
`product_retailer_id`	string	No	The product SKU identifier.

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.

User changed BSUID without exposing a phone number

{
  "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"
    }
  }
}

User changed number with previous BSUIDs

{
  "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"
    }
  }
}

Inbound unsupported message

{
  "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"
  }
}

Inbound Text message

{
  "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..."
    }
  }
}

Inbound Text message triggered by click to WhatsApp Ads

{
  "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"
    }
  }
}

Inbound Image message

{
  "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"
    }
  }
}

Inbound Video message

{
  "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"
    }
  }
}

Inbound Audio message

{
  "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"
    }
  }
}

Inbound Document message

{
  "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"
    }
  }
}

Inbound Sticker message

{
  "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"
    }
  }
}

Inbound Location message

{
  "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"
    }
  }
}

Inbound Contacts message

{
  "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": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "recipient@example.com",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<CONTACT_FORMATTED_NAME>",
          "first_name": "<CONTACT_FIRST_NAME>",
          "last_name": "<CONTACT_LAST_NAME>",
          "middle_name": "<CONTACT_MIDDLE_NAME>",
          "suffix": "<CONTACT_SUFFIX>",
          "prefix": "<CONTACT_PREFIX>"
        },
        "org": {
          "company": "<CONTACT_ORG_COMPANY>",
          "department": "<CONTACT_ORG_DEPARTMENT>",
          "title": "<CONTACT_ORG_TITLE>"
        },
        "phones": [
          {
            "phone": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

Inbound Reaction message

{
  "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": "👍"
    }
  }
}

Inbound Template Button message

{
  "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..."
    }
  }
}

Inbound Interactive List Reply message

{
  "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": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Inbound Interactive Button Reply message

{
  "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": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Inbound Interactive Flow Response message

{
  "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\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

Inbound Order message

{
  "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"
    }
  }
}

Inbound Product Inquiry message

{
  "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"
      }
    }
  }
}

Inbound Request Welcome message

{
  "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/1.1 200 OK

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

whatsapp.inbound_message.received

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappInboundMessage

Nested object parameters

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappInboundMessage

Nested object parameters

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappInboundMessage

Example