whatsapp.echo_message.created

Use whatsapp.echo_message.created to handle this event at your webhook endpoint.

Triggers

Occurs when an outbound echo message is recorded for a Public REST API Agent. Subscribe to whatsapp.echo_message.created when you configure your webhook endpoint. This event is limited to Agents onboarded through the Public REST API. Use whatsappMessage.id or wamid to correlate later status updates. Message content depends on type.

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.echo_message.created",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "recipientUserId": "<RECIPIENT_USER_ID>",
    "type": "<TYPE>",
    "text": {
      "body": "<BODY>"
    },
    "status": "<STATUS>",
    "createTime": "<CREATE_TIME>",
    "sendTime": "<SEND_TIME>"
  }
}

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.echo_message.created`.
`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
`whatsappMessage`	object	Yes	Event-specific `whatsappMessage` 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.

whatsappMessage

Parameter	Type	Required	Description
`id`	string	Yes	YCloud message ID. Use it to correlate created and updated echo events.
`wamid`	string	No	The original message ID on WhatsApp’s platform, when available.
`wabaId`	string	No	WhatsApp Business Account ID from the source callback, when available.
`from`	string	No	Business sender number in E.164 format, when available.
`to`	string	No	Recipient number in E.164 format when the callback identifies the customer by phone number.
`recipientUserId`	string	No	Recipient WhatsApp Business-scoped user ID (BSUID), when supplied by the callback.
`parentRecipientUserId`	string	No	Recipient parent WhatsApp Business-scoped user ID, when supplied by the callback.
`type`	string	No	Message type copied from a supported provider callback. Current values include text, interactive, image, video, audio, document, sticker, location, contacts, and reaction. Clients should tolerate future values.
`text`	object	No	WhatsApp Message Text Object.
`image`	object	No	Media metadata copied from a Meta Business Agent echo callback.
`video`	object	No	Media metadata copied from a Meta Business Agent echo callback.
`audio`	object	No	Media metadata copied from a Meta Business Agent echo callback.
`document`	object	No	Media metadata copied from a Meta Business Agent echo callback.
`sticker`	object	No	Media metadata copied from a Meta Business Agent echo callback.
`location`	object	No	Use for `location` messages.
`interactive`	object	No	Use for `interactive` messages.
`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.
`context`	object	No	Used to mention a specific message you are replying to. The reply can be any message type.
`status`	string	No	WhatsApp message status. One of `accepted`, `failed`, `sent`, `delivered`, `read`. `accepted`: The messaging request is accepted by our system. `failed`: A message sent by your business failed to send. `sent`: A message sent by your business is in transit within WhatsApp’s systems. `delivered`: A message sent by your business was delivered to the user’s device. `read`: A message sent by your business was read by the user.
`errorCode`	string	No	Source error code when status is failed and the provider supplied one.
`errorMessage`	string	No	Source error title when status is failed and the provider supplied one.
`createTime`	string (date-time)	No	Source echo time for a created event, formatted in RFC 3339.
`updateTime`	string (date-time)	No	Source status time for an updated event, formatted in RFC 3339.
`sendTime`	string (date-time)	No	Source echo time on created events, or source status time when the current event reports sent.
`deliverTime`	string (date-time)	No	Source status time when the current event reports delivered.
`readTime`	string (date-time)	No	Source status time when the current event reports read.

whatsappMessage.text

Parameter	Type	Required	Description
`body`	string	Yes	Required for text messages. The text of the text message which can contain URLs which begin with http:// or https:// and formatting. See available formatting options here. If you include URLs in your text and want to include a preview box in text messages (preview_url: true), make sure the URL starts with http:// or https:// — https:// URLs are preferred. You must include a hostname, since IP addresses will not be matched. Maximum length: 4096 characters. Maximum length: `4096`.
`preview_url`	boolean	No	By default, WhatsApp recognizes URLs and makes them clickable, but you can also include a preview box with more information about the link. Set this field to true if you want to include a URL preview box. The majority of the time, the receiver will see a URL they can click on when you send an URL, set preview_url to true, and provide a body object with a http or https link. URL previews are only rendered after one of the following has happened: The business has sent a message template to the user. The user initiates a conversation with a “click to chat” link. The user adds the business phone number to their address book and initiates a conversation. Default: `false`.

whatsappMessage.image

Parameter	Type	Required	Description
`id`	string	No	Provider media ID, when supplied by the callback.
`link`	string	No	Provider media URL, when supplied by the callback.
`caption`	string	No	Media caption, when supplied by the callback.
`filename`	string	No	Original filename, when supplied by the callback.
`mime_type`	string	No	Provider MIME type copied from the callback.

whatsappMessage.video

Parameter	Type	Required	Description
`id`	string	No	Provider media ID, when supplied by the callback.
`link`	string	No	Provider media URL, when supplied by the callback.
`caption`	string	No	Media caption, when supplied by the callback.
`filename`	string	No	Original filename, when supplied by the callback.
`mime_type`	string	No	Provider MIME type copied from the callback.

whatsappMessage.audio

Parameter	Type	Required	Description
`id`	string	No	Provider media ID, when supplied by the callback.
`link`	string	No	Provider media URL, when supplied by the callback.
`caption`	string	No	Media caption, when supplied by the callback.
`filename`	string	No	Original filename, when supplied by the callback.
`mime_type`	string	No	Provider MIME type copied from the callback.

whatsappMessage.document

Parameter	Type	Required	Description
`id`	string	No	Provider media ID, when supplied by the callback.
`link`	string	No	Provider media URL, when supplied by the callback.
`caption`	string	No	Media caption, when supplied by the callback.
`filename`	string	No	Original filename, when supplied by the callback.
`mime_type`	string	No	Provider MIME type copied from the callback.

whatsappMessage.sticker

Parameter	Type	Required	Description
`id`	string	No	Provider media ID, when supplied by the callback.
`link`	string	No	Provider media URL, when supplied by the callback.
`caption`	string	No	Media caption, when supplied by the callback.
`filename`	string	No	Original filename, when supplied by the callback.
`mime_type`	string	No	Provider MIME type copied from the callback.

whatsappMessage.location

Parameter	Type	Required	Description
`latitude`	number (double)	Yes	Latitude of the location.
`longitude`	number (double)	Yes	Longitude of the location.
`name`	string	No	Name of the location.
`address`	string	No	Address of the location. Only displayed if `name` is present.

whatsappMessage.interactive

Parameter	Type	Required	Description
`type`	string	No	Required. The type of interactive message you want to send. `button`: Use for Reply Buttons. `list`: Use for List Messages. `cta_url`: Use for Call-To-Action (CTA) URL Button Messages. `product`: Use for Single Product Messages. `product_list`: Use for Multi-Product Messages. `catalog_message`: Use for Catalog Messages. `location_request_message`: Use for Location Request Messages. `order_details`: Use for Order Details Messages. `order_status`: Use for Order Status Messages. `voice_call`: Use for Voice Call Messages. `flow`: Use for Flow Messages.
`action`	object	No	Required. Action you want the user to perform after reading the `interactive` message.
`body`	object	No	Optional for type `product`. Required for other message types.
`header`	object	No	Required for type `product_list`. Optional for other types.
`footer`	object	No	Optional. An object with the footer of the message.

whatsappMessage.interactive.action

Parameter	Type	Required	Description
`buttons`	object[]	No	Required for Reply Buttons. You can have up to 3 buttons.
`button`	string	No	Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. Maximum length: `20`.
`catalog_id`	string	No	Required for Single Product Messages and Multi-Product Messages. Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via the Meta Commerce Manager.
`product_retailer_id`	string	No	Required for Single Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog.
`sections`	object[]	No	Required for List Messages and Multi-Product Messages. Array of section objects. Minimum of 1, maximum of 10.
`name`	string	No	Action name. Required for Call-To-Action (CTA) buttons. `cta_url`: Use for Call-To-Action (CTA) URL buttons. `catalog_message`: Use for Catalog Messages. `send_location`: Use for Location Request buttons. `flow`: Use for Flow buttons. `review_and_pay`: Use for Order Details buttons. `review_order`: Use for Order Status buttons. `voice_call`: Use for Voice Call buttons.
`parameters`	object	No	Action parameters. Required for Call-To-Action (CTA) buttons.

whatsappMessage.interactive.action.buttons[]

Parameter	Type	Required	Description
`type`	string	No	Only supported type is `reply` (for Reply Button).
`reply`	object	No	Object fields are listed below.

whatsappMessage.interactive.action.buttons[].reply

Parameter	Type	Required	Description
`title`	string	No	Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. Maximum length: `20`.
`id`	string	No	Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. You cannot have leading or trailing spaces when setting the ID. Maximum length: `256`.

whatsappMessage.interactive.action.sections[]

Parameter	Type	Required	Description
`title`	string	No	Required if the message has more than one section. Title of the section. Maximum length: 24 characters. Maximum length: `24`.
`rows`	object[]	No	Contains a list of rows. You can have a total of 10 rows across your sections. Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional.
`product_items`	object[]	No	Required for Multi-Product Messages. Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.

whatsappMessage.interactive.action.sections[].rows[]

Parameter	Type	Required	Description
`id`	string	No	Unique row ID. Maximum length: 200 characters. Maximum length: `200`.
`title`	string	No	Row title content. Maximum length: 24 characters. Maximum length: `24`.
`description`	string	No	Row description content. Maximum length: 72 characters. Maximum length: `72`.

whatsappMessage.interactive.action.sections[].product_items[]

Parameter	Type	Required	Description
`product_retailer_id`	string	No	Required for Multi-Product Messages. Unique identifier of the product in a catalog.

whatsappMessage.interactive.action.parameters

Parameter	Type	Required	Description
`display_text`	string	No	Text of the CTA URL button. Maximum length: 20 bytes. Maximum length: `20`.
`url`	string	No	URL of the CTA URL button.
`thumbnail_product_retailer_id`	string	No	Item SKU number. Labeled as Content ID in the Commerce Manager. The thumbnail of this item will be used as the message’s header image.
`flow_message_version`	string	No	Use for `flow` buttons. Value must be “3”.
`flow_token`	string	No	Use for `flow` buttons. Flow token that is generated by the business to serve as an identifier. Defaults to `unused`.
`flow_id`	string	No	Conditionally required for `flow` buttons. Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter.
`flow_name`	string	No	Conditionally required for `flow` buttons. The name of the Flow that you created. Cannot be used with the `flow_id` parameter. Changing the Flow name will require updating this parameter to match the new name.
`flow_cta`	string	No	Required for `flow` buttons. Text on the CTA button. For example: “Open flow!”. Maximum length: 20 characters. Maximum length: `20`.
`flow_action`	string	No	Use for `flow` buttons. Either `navigate` or `data_exchange`. Defaults to `navigate`.
`flow_action_payload`	object	No	Required if `flow_action` is `navigate`. Should be omitted otherwise.
`reference_id`	string	No	Required for `review_and_pay` buttons. Unique identifier for the order provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The `reference_id` must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, “BM345A-12”) to ensure reference_id uniqueness.
`type`	string	No	Required for `review_and_pay` buttons. The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`.
`beneficiaries`	object[]	No	Required for `review_and_pay` buttons. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. Beneficiary information isn’t shown to users but is needed for legal and compliance reasons.
`currency`	string	No	Required for `review_and_pay` buttons. The currency for this order. Currently the only supported value is `INR`.
`total_amount`	object	No	Required for `review_and_pay` buttons. The total amount for this order.
`order`	object	No	Required for `review_and_pay` or `review_order` buttons. For `review_and_pay` buttons, provides order `status`, `items`, `subtotal`, `tax`, etc. For `review_order` buttons, provides only order `status` and `description`.
`payment_settings`	object[]	No	Required for `review_and_pay` buttons. Payment settings for the order.

whatsappMessage.interactive.action.parameters.flow_action_payload

Parameter	Type	Required	Description
`screen`	string	No	The ID of the screen displayed first. It needs to be an entry screen.
`data`	object	No	Optional input data for the first screen of the Flow. If provided, this must be a non-empty object.

whatsappMessage.interactive.action.parameters.beneficiaries[]

Parameter	Type	Required	Description
`name`	string	Yes	Name of the individual or business receiving the physical goods. Cannot exceed 200 characters. Maximum length: `200`.
`address_line1`	string	Yes	Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters. Maximum length: `100`.
`address_line2`	string	No	Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters. Maximum length: `100`.
`city`	string	Yes	Name of the city.
`state`	string	Yes	Name of the state.
`country`	string	Yes	Name of the country. Currently the only supported value is `India`.
`postal_code`	string	Yes	6-digit zipcode of shipping address. Minimum length: `6`. Maximum length: `6`.

whatsappMessage.interactive.action.parameters.total_amount

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order

Parameter	Type	Required	Description
`status`	string	No	Only supported value in the `order_details` message is `pending`. In an `order_status` message, `status` can be: `pending`, `processing`, `partially_shipped`, `shipped`, `completed`, or `canceled`.
`type`	string	No	Only supported value is `quick_pay`. When this field is passed in we hide the “Review and Pay” button and only show the “Pay Now” button in the order details bubble.
`catalog_id`	string	No	Unique identifier of the Facebook catalog being used by the business. If you do not provide this field, you must provide the following fields inside the items object: `country_of_origin`, `importer_name`, and `importer_address`.
`items`	object[]	No	Array of items in the order.
`subtotal`	object	No	The value must be equal to sum of `order.amount.value` * `order.amount.quantity`.
`tax`	object	No	The tax information for this order.
`shipping`	object	No	The shipping cost of the order.
`discount`	object	No	The discount amount for this order.
`expiration`	object	No	Expiration for this order.
`description`	string	No	Optional. Text for sharing status related information. Could be useful while sending cancellation. Max character limit is 120 characters. Maximum length: `120`.

whatsappMessage.interactive.action.parameters.order.items[]

Parameter	Type	Required	Description
`retailer_id`	string	No	Content ID for an item in the order from your catalog.
`name`	string	Yes	The item’s name to be displayed to the user. Cannot exceed 60 characters. Maximum length: `60`.
`image`	object	No	Custom image for the item to be displayed to the user.
`amount`	object	Yes	The price per item.
`sale_amount`	object	No	The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount.
`quantity`	integer (int32)	Yes	The number of items in the order.
`country_of_origin`	string	No	Required if `catalog_id` is not present. The country of origin of the product.
`importer_name`	string	No	Required if `catalog_id` is not present. Name of the importer company.
`importer_address`	string	No	Required if `catalog_id` is not present. Address of importer company.

whatsappMessage.interactive.action.parameters.order.items[].image

Parameter	Type	Required	Description
`id`	string	No	Use this when media is uploaded to WhatsApp servers. Provide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence.
`link`	string	No	Use this when sending media directly from your server. The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Note: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL. Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence and `link` will be ignored.
`caption`	string	No	Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages.
`filename`	string	No	Describes the filename for the specific document. Use only with `document` media.

whatsappMessage.interactive.action.parameters.order.items[].amount

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order.items[].sale_amount

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order.subtotal

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order.tax

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order.shipping

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order.discount

Parameter	Type	Required	Description
`offset`	integer (int32)	Yes	Must be `100` for `INR`.
`value`	integer (int32)	Yes	Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234.
`description`	string	No	Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. Maximum length: `60`.
`discount_program_name`	string	No	Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. Maximum length: `60`.

whatsappMessage.interactive.action.parameters.order.expiration

Parameter	Type	Required	Description
`timestamp`	string	Yes	A string of UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds.
`description`	string	No	Text explanation for expiration. Maximum length: `120`.

whatsappMessage.interactive.action.parameters.payment_settings[]

Parameter	Type	Required	Description
`type`	string	Yes	Must be set to `payment_gateway`.
`payment_gateway`	object	Yes	An object that describes payment account information.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway

Parameter	Type	Required	Description
`type`	string	Yes	Payment type. Must set this to `billdesk`, `razorpay`, `payu`, or `zaakpay`, if you have linked your BillDesk, Razorpay, PayU, or Zaakpay payment gateway to accept payments.
`configuration_name`	string	Yes	The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters. This value must match with a payment configuration set up on the WhatsApp Business Manager. Maximum length: `60`.
`billdesk`	object	No	Additional info for BillDesk. User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 120.
`payu`	object	No	Additional info for PayU. User-defined fields (udf) are used to store any information corresponding to a particular order. Each UDF field has a maximum character limit of 255.
`razorpay`	object	No	Additional info for Razorpay.
`zaakpay`	object	No	Additional info for Zaakpay. User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 180.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.billdesk

Parameter	Type	Required	Description
`additional_info1`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.
`additional_info2`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.
`additional_info3`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.
`additional_info4`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.
`additional_info5`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.
`additional_info6`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.
`additional_info7`	string	No	User-defined information about this order for BillDesk. Maximum length: `120` characters.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.payu

Parameter	Type	Required	Description
`udf1`	string	No	User-defined information about this order for PayU. Maximum length: `255` characters.
`udf2`	string	No	User-defined information about this order for PayU. Maximum length: `255` characters.
`udf3`	string	No	User-defined information about this order for PayU. Maximum length: `255` characters.
`udf4`	string	No	User-defined information about this order for PayU. Maximum length: `255` characters.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.razorpay

Parameter	Type	Required	Description
`receipt`	string	No	Receipt number that corresponds to this order, set for your internal reference. Maximum length of 40 characters supported with minimum length greater than 0 characters.
`notes`	object	No	The object can be key value pairs with maximum 15 keys and each value limits to 256 characters.

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.zaakpay

Parameter	Type	Required	Description
`extra1`	string	No	User-defined information about this order for Zaakpay. Maximum length: `180` characters.
`extra2`	string	No	User-defined information about this order for Zaakpay. Maximum length: `180` characters.

whatsappMessage.interactive.body

Parameter	Type	Required	Description
`text`	string	No	The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. Maximum length: `1024`.

whatsappMessage.interactive.header

Parameter	Type	Required	Description
`type`	string	No	Required. The header type you would like to use. `text`: Used for List Messages, Reply Buttons, and Multi-Product Messages. `video`: Used for Reply Buttons. `image`: Used for Reply Buttons. `document`: Used for Reply Buttons.
`text`	string	No	Text for the header. Formatting allows emojis, but not markdown. Maximum length: `60`.
`image`	object	No	Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also Supported Media Types.
`video`	object	No	Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also Supported Media Types.
`document`	object	No	Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also Supported Media Types.

whatsappMessage.interactive.header.image

Parameter	Type	Required	Description
`id`	string	No	Use this when media is uploaded to WhatsApp servers. Provide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence.
`link`	string	No	Use this when sending media directly from your server. The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Note: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL. Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence and `link` will be ignored.
`caption`	string	No	Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages.
`filename`	string	No	Describes the filename for the specific document. Use only with `document` media.

whatsappMessage.interactive.header.video

Parameter	Type	Required	Description
`id`	string	No	Use this when media is uploaded to WhatsApp servers. Provide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence.
`link`	string	No	Use this when sending media directly from your server. The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Note: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL. Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence and `link` will be ignored.
`caption`	string	No	Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages.
`filename`	string	No	Describes the filename for the specific document. Use only with `document` media.

whatsappMessage.interactive.header.document

Parameter	Type	Required	Description
`id`	string	No	Use this when media is uploaded to WhatsApp servers. Provide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence.
`link`	string	No	Use this when sending media directly from your server. The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Note: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL. Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence and `link` will be ignored.
`caption`	string	No	Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages.
`filename`	string	No	Describes the filename for the specific document. Use only with `document` media.

whatsappMessage.interactive.footer

Parameter	Type	Required	Description
`text`	string	No	The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters. Maximum length: `60`.

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

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

whatsappMessage.contacts[].emails[]

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

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

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

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

whatsappMessage.contacts[].urls[]

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

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

whatsappMessage.context

Parameter	Type	Required	Description
`message_id`	string	No	Specifies the `wamid` of the message your are replying to. `wamid` is the original message ID on WhatsApp’s platform.

Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

Outbound text echo

Store the text from whatsappMessage.text.body. id and wamid link subsequent status events.

{
  "id": "evt_example_echo_text",
  "type": "whatsapp.echo_message.created",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "type": "text",
    "text": {
      "body": "Hello! How can I help you?"
    },
    "status": "sent",
    "createTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

Outbound image echo

Message content varies by type. Treat media IDs as provider references, not public download URLs.

{
  "id": "evt_example_echo_image",
  "type": "whatsapp.echo_message.created",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:00.000Z",
  "whatsappMessage": {
    "id": "IMAGE_MESSAGE_ID",
    "wamid": "wamid.IMAGE_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "type": "image",
    "image": {
      "id": "MEDIA_ID",
      "mime_type": "image/jpeg"
    },
    "status": "sent",
    "createTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

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.echo_message.created

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappMessage

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappMessage

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappMessage

Example