> ## 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.echo_message.updated

> Occurs when an outbound echo status is received for a Public REST API Agent; late lower-ranked statuses can also be delivered.

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

## Triggers

Occurs when an outbound echo status is received for a Public REST API Agent; late lower-ranked statuses can also be delivered.

Subscribe to `whatsapp.echo_message.updated` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

This event is limited to Agents onboarded through the Public REST API. Updated echoes omit message content and `type`. Late lower-ranked statuses can arrive after `read`; record them without downgrading your stored message status.

## 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": "<ID>",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "recipientUserId": "<RECIPIENT_USER_ID>",
    "status": "<STATUS>",
    "updateTime": "<UPDATE_TIME>",
    "deliverTime": "<DELIVER_TIME>"
  }
}
```

## 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.echo_message.updated`. |
| `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 |
| - | - | - | - |
| `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`.<ul><li>`accepted`: The messaging request is accepted by our system.</li><li>`failed`: A message sent by your business failed to send.</li><li>`sent`: A message sent by your business is in transit within WhatsApp's systems.</li><li>`delivered`: A message sent by your business was delivered to the user's device.</li><li>`read`: A message sent by your business was read by the user.</li></ul> |
| `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. |

> [accordion] 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:<ul><li>The business has sent a message template to the user.</li><li>The user initiates a conversation with a "click to chat" link.</li><li>The user adds the business phone number to their address book and initiates a conversation. Default: `false`.</li></ul> |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] whatsappMessage.interactive
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `type` | string | No | **Required.** The type of interactive message you want to send.<ul><li>`button`: Use for Reply Buttons.</li><li>`list`: Use for List Messages.</li><li>`cta_url`: Use for Call-To-Action (CTA) URL Button Messages.</li><li>`product`: Use for Single Product Messages.</li><li>`product_list`: Use for Multi-Product Messages.</li><li>`catalog_message`: Use for Catalog Messages.</li><li>`location_request_message`: Use for Location Request Messages.</li><li>`order_details`: Use for Order Details Messages.</li><li>`order_status`: Use for Order Status Messages.</li><li>`voice_call`: Use for Voice Call Messages.</li><li>`flow`: Use for Flow Messages.</li></ul> |
> | `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. |

> [accordion] 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](https://business.facebook.com/commerce). |
> | `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.<ul><li>`cta_url`: Use for Call-To-Action (CTA) URL buttons.</li><li>`catalog_message`: Use for Catalog Messages.</li><li>`send_location`: Use for Location Request buttons.</li><li>`flow`: Use for Flow buttons.</li><li>`review_and_pay`: Use for Order Details buttons.</li><li>`review_order`: Use for Order Status buttons.</li><li>`voice_call`: Use for Voice Call buttons.</li></ul> |
> | `parameters` | object | No | Action parameters. Required for Call-To-Action (CTA) buttons. |

> [accordion] 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. |

> [accordion] 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`. |

> [accordion] 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. |

> [accordion] 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`. |

> [accordion] 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. |

> [accordion] 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](https://business.facebook.com/commerce). 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. |

> [accordion] 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. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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. |

> [accordion] 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#/](https://docs.ycloud.com/reference/whatsapp_media-upload#/)]\([https://docs.ycloud.com/reference/whatsapp\_media-upload#/)).Note](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. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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`. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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`. |

> [accordion] whatsappMessage.interactive.header
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `type` | string | No | **Required.** The header type you would like to use.<ul><li>`text`: Used for List Messages, Reply Buttons, and Multi-Product Messages.</li><li>`video`: Used for Reply Buttons.</li><li>`image`: Used for Reply Buttons.</li><li>`document`: Used for Reply Buttons.</li></ul> |
> | `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](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |
> | `video` | object | No | Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |
> | `document` | object | No | Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |

> [accordion] 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#/](https://docs.ycloud.com/reference/whatsapp_media-upload#/)]\([https://docs.ycloud.com/reference/whatsapp\_media-upload#/)).Note](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. |

> [accordion] 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#/](https://docs.ycloud.com/reference/whatsapp_media-upload#/)]\([https://docs.ycloud.com/reference/whatsapp\_media-upload#/)).Note](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. |

> [accordion] 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#/](https://docs.ycloud.com/reference/whatsapp_media-upload#/)]\([https://docs.ycloud.com/reference/whatsapp\_media-upload#/)).Note](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. |

> [accordion] 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`. |

> [accordion] 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. |

> [accordion] 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`. |

> [accordion] whatsappMessage.contacts\[].emails\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `email` | string | No | Email address. |
> | `type` | string | No | Standard values are `HOME` and `WORK`. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] 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. |

> [accordion] whatsappMessage.contacts\[].urls\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `url` | string | No | URL. |
> | `type` | string | No | Standard values are `HOME` and `WORK`. |

> [accordion] 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. |

> [accordion] 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.

> [accordion] Echo message delivered
>
> Correlate with the created event by id or wamid. Updated events omit message content and type.
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_example_echo_delivered",
>   "type": "whatsapp.echo_message.updated",
>   "apiVersion": "v2",
>   "createTime": "2026-09-09T02:00:03.000Z",
>   "whatsappMessage": {
>     "id": "MESSAGE_ID",
>     "wamid": "wamid.EXAMPLE",
>     "wabaId": "WABA_ID",
>     "from": "+12025550124",
>     "to": "+12025550123",
>     "recipientUserId": "GB.898232076600896",
>     "status": "delivered",
>     "updateTime": "2026-09-09T02:00:01.000Z",
>     "deliverTime": "2026-09-09T02:00:01.000Z"
>   }
> }
> ```

> [accordion] Echo message read
>
> Correlate with the created event by id or wamid. Updated events omit message content and type.
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_example_echo_read",
>   "type": "whatsapp.echo_message.updated",
>   "apiVersion": "v2",
>   "createTime": "2026-09-09T02:00:03.000Z",
>   "whatsappMessage": {
>     "id": "MESSAGE_ID",
>     "wamid": "wamid.EXAMPLE",
>     "wabaId": "WABA_ID",
>     "from": "+12025550124",
>     "to": "+12025550123",
>     "recipientUserId": "GB.898232076600896",
>     "status": "read",
>     "updateTime": "2026-09-09T02:00:02.000Z",
>     "readTime": "2026-09-09T02:00:02.000Z"
>   }
> }
> ```

> [accordion] Late sent status after read
>
> A lower-ranked source status can arrive after read. Record the event without downgrading your current message status.
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_example_echo_sent",
>   "type": "whatsapp.echo_message.updated",
>   "apiVersion": "v2",
>   "createTime": "2026-09-09T02:00:03.000Z",
>   "whatsappMessage": {
>     "id": "MESSAGE_ID",
>     "wamid": "wamid.EXAMPLE",
>     "wabaId": "WABA_ID",
>     "from": "+12025550124",
>     "to": "+12025550123",
>     "recipientUserId": "GB.898232076600896",
>     "status": "sent",
>     "updateTime": "2026-09-09T02:00:00.000Z",
>     "sendTime": "2026-09-09T02:00:00.000Z"
>   }
> }
> ```

> [accordion] Failed echo message
>
> This is a separate failed message, not a transition from read. Failed updates include source error details when available.
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_example_echo_failed",
>   "type": "whatsapp.echo_message.updated",
>   "apiVersion": "v2",
>   "createTime": "2026-09-09T02:00:03.000Z",
>   "whatsappMessage": {
>     "id": "FAILED_MESSAGE_ID",
>     "wamid": "wamid.FAILED_EXAMPLE",
>     "wabaId": "WABA_ID",
>     "from": "+12025550124",
>     "to": "+12025550123",
>     "recipientUserId": "GB.898232076600896",
>     "status": "failed",
>     "errorCode": "131000",
>     "errorMessage": "Provider failure",
>     "updateTime": "2026-09-09T02:00:03.000Z"
>   }
> }
> ```

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-echo-message-updated).


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