← Files YCloud Developer KitARCHIVED FILE
skills/ycloud-whatsapp-messages/references/openapi.md
78.2 KB · Oct 5, 2026 · 18:33 UTC
<!-- Generated by scripts/build_openapi_skill_references.py; do not edit. -->
# OpenAPI contract: WhatsApp messages
## Provenance
- Source: `ycloud-api-v2.yaml` (pinned release snapshot).
- Source SHA-256: `8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81`
- OpenAPI version: `3.0.0`
- API info.version: `v2`
- This derived reference does not replace the upstream API Owner's canonical source.
- Generated deterministically from normalized JSON; do not edit this file by hand.
## Scope and handoff
- `sendDirectly` is synchronous submission to WhatsApp; `send` queues an asynchronous submission. HTTP acceptance is not final delivery. Use the retrieve operation and/or a separately confirmed webhook contract for later state; do not invent retry or delivery guarantees. Sending an existing template belongs here, while template lifecycle changes hand off to Templates.
- Operation coverage: `3`
## Operations
### `POST /whatsapp/messages/sendDirectly` — `whatsapp_message-send-directly`
- Summary: Send a message directly
- Description:
> Sends an outbound WhatsApp message directly.
>
> The message is submitted to the WhatsApp Business API synchronously. Typically used for sending OTP and instant messages.
>
> The response body field `error.whatsappApiError` is included if we tried to request the WhatsApp Business API and got an error response.
- Parameters: none
- Request body: required
- `application/json`: `#/components/schemas/WhatsappMessageSendRequest`
- `$ref`: `#/components/schemas/WhatsappMessageSendRequest`
- Responses:
- `200`: The request is successfully accepted.
- `application/json`: `#/components/schemas/WhatsappMessage`
- `$ref`: `#/components/schemas/WhatsappMessage`
### `POST /whatsapp/messages` — `whatsapp_message-send`
- Summary: Enqueue a message
- Description:
> Enqueues an outbound WhatsApp message for sending.
>
> Queued messages will be submitted to the WhatsApp Business API asynchronously.
>
> For WhatsApp `template` messages, the referenced template must be in `APPROVED` status. `ARCHIVED` templates cannot be sent.
- Parameters: none
- Request body: required
- `application/json`: `#/components/schemas/WhatsappMessageSendRequest`
- `$ref`: `#/components/schemas/WhatsappMessageSendRequest`
- Responses:
- `200`: The request is successfully accepted.
- `application/json`: `#/components/schemas/WhatsappMessage`
- `$ref`: `#/components/schemas/WhatsappMessage`
### `GET /whatsapp/messages/{id}` — `whatsapp_message-retrieve`
- Summary: Retrieve a message
- Description:
> Retrieves a WhatsApp message you've previously sent.
- Parameters:
- `id` (path, required): `string`
> ID of the object.
- Constraints: example="627c8640675de8fc689ab9d9"
- Request body: none
- Responses:
- `200`: Successfully retrieved the object.
- `application/json`: `#/components/schemas/WhatsappMessage`
- `$ref`: `#/components/schemas/WhatsappMessage`
- `404`: The requested resource does not exist.
- `application/json`: `#/components/schemas/ErrorResponse`
- `$ref`: `#/components/schemas/ErrorResponse`
## Referenced schema and parameter shapes
### `id-in_path`
- Reference: `#/components/parameters/id-in_path`
- Parameter name: `id`
- Location: `path`
- Required: `true`
- Description:
> ID of the object.
- Schema: `string`
- Constraints: example="627c8640675de8fc689ab9d9"
### `Error`
- Reference: `#/components/schemas/Error`
- Shape: `object`
- Required properties: `status`, `code`
- Properties:
- `code`: `string` (required)
- Description:
> One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
- Constraints: example="NOT_FOUND"
- `docUrl`: `string`
- Description:
> A URL to more information about the error.
- Constraints: example=""
- `message`: `string`
- Description:
> A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
- Constraints: example="The requested resource does not exist."
- `requestId`: `string`
- Description:
> Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
- Constraints: example="req_1KjtKI80IKoaJNa6n6p"
- `status`: `integer (int32)` (required)
- Description:
> HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
- Constraints: pattern="[45]\\d{2}"; example=404
- `target`: `string`
- Description:
> The target of the error.
- Constraints: example=""
- `whatsappApiError`: `#/components/schemas/WhatsappApiError`
- Description:
> The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
>
> Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.
### `ErrorResponse`
- Reference: `#/components/schemas/ErrorResponse`
- Shape: `object`
- Required properties: `error`
- Properties:
- `error`: `#/components/schemas/Error` (required)
### `WhatsappApiError`
- Reference: `#/components/schemas/WhatsappApiError`
- Shape: `object`
- Description:
> The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
- Required properties: `message`, `code`
- Properties:
- `code`: `string` (required)
- Description:
> An error code.
- Constraints: example=200002
- `error_data`: `object`
- Description:
> Additional data about the error. A string or map.
> - For template APIs, this field is a string describing the reason for the error.
> - For message APIs, this field is a map with property `details` describing the reason for the error.
- `error_subcode`: `string`
- Description:
> Additional code about the error.
- Constraints: example=2388109
- `error_user_msg`: `string`
- Description:
> The message to display to the user. The language of the message is based on the locale of the API request.
- Constraints: example="This message template cannot be created."
- `error_user_title`: `string`
- Description:
> The title of the dialog, if shown. The language of the message is based on the locale of the API request.
- Constraints: example="Message Cannot Be Submitted"
- `fbtrace_id`: `string`
- Description:
> Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging.
- Constraints: example="AVGjJ7ia2zJkrHG"
- `is_transient`: `boolean`
- Description:
> Whether the error is transient.
- Constraints: example=false
- `message`: `string` (required)
- Description:
> A human-readable description of the error.
- Constraints: example="HSM Template creation failed"
- `type`: `string`
- Description:
> Error type.
- Constraints: example="OAuthException"
### `WhatsappConversation`
- Reference: `#/components/schemas/WhatsappConversation`
- Shape: `object`
- Description:
> WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business.
> See also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing).
- Properties:
- `expireTime`: `string (date-time)`
- Description:
> Date when the conversation expires, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `id`: `string`
- Description:
> Unique ID for the object.
- `originType`: `#/components/schemas/WhatsappConversationOriginType`
- `type`: `#/components/schemas/WhatsappConversationType`
### `WhatsappConversationOriginType`
- Reference: `#/components/schemas/WhatsappConversationOriginType`
- Shape: `string`
- Description:
> Indicates [conversation category](https://developers.facebook.com/docs/whatsapp/pricing#conversation-categories). This can also be referred to as a conversation entry point.
> - `referral_conversion`: Indicates a [free entry point conversation](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations).
> - `authentication`: Indicates the conversation was opened by a business sending template categorized as `AUTHENTICATION` to the customer. This applies any time it has been more than 24 hours since the last customer message.
> - `marketing`: Indicates the conversation was opened by a business sending template categorized as `MARKETING` to the customer. This applies any time it has been more than 24 hours since the last customer message.
> - `utility`: Indicates the conversation was opened by a business sending template categorized as `UTILITY` to the customer. This applies any time it has been more than 24 hours since the last customer message.
> - `service`: Indicates that the conversation opened by a business replying to a customer within a [customer service window](https://developers.facebook.com/docs/whatsapp/pricing#customer-service-windows).
- Constraints: enum=["referral_conversion", "authentication", "marketing", "utility", "service"]
### `WhatsappConversationType`
- Reference: `#/components/schemas/WhatsappConversationType`
- Shape: `string`
- Description:
> Conversation type. There is a charge when the first business message of this conversation is delivered, initiating the 24-hour conversation session. As such, the conversation type can be `null` before the first message is delivered.
> - `FREE_ENTRY`: Conversations originating from a [free entry point](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations).
> - `FREE_TIER`: Conversations within the monthly [free tier](https://developers.facebook.com/docs/whatsapp/pricing#free-tier-conversations).
> - `REGULAR`: Any conversations that did not originate from a [free entry point](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations) or are above the monthly [free tier](https://developers.facebook.com/docs/whatsapp/pricing#free-tier-conversations) allotment.
- Constraints: enum=["FREE_ENTRY", "FREE_TIER", "REGULAR"]
### `WhatsappMessage`
- Reference: `#/components/schemas/WhatsappMessage`
- Shape: `object`
- Description:
> WhatsApp outbound message object.
- Required properties: `id`, `wabaId`, `from`
- Properties:
- `audio`: `#/components/schemas/WhatsappMessageMedia`
- `bizType`: `string`
- Description:
> This can be either empty or one of `whatsapp`, or `verify`. Defaults to `whatsapp`.
> - `whatsapp`: Indicates that the message is sent via the **WhatsApp** product.
> - `verify`: Indicates that the message is sent via the **Verify** product.
- Constraints: example="whatsapp"
- `contacts`: `array`
- Items: `#/components/schemas/WhatsappMessageContact`
- `context`: `#/components/schemas/WhatsappMessageContext`
- `conversation`: `#/components/schemas/WhatsappConversation`
- Description:
> WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business.
> This field is present after the message status changes to `sent`.
> See also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing).
- `createTime`: `string (date-time)`
- Description:
> The time at which this message is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `currency`: `string`
- Description:
> Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).
- Constraints: example="USD"
- `customerProfile`: `#/components/schemas/WhatsappProfile`
- Description:
> The recipient's profile information, including WhatsApp username when available.
- `deliverTime`: `string (date-time)`
- Description:
> The time at which this message `status` changed to `delivered`, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `document`: `#/components/schemas/WhatsappMessageMedia`
- `errorCode`: `string`
- Description:
> Error code when the message status is `failed`.
- Constraints: example="INTERNAL_SERVER_ERROR"
- `errorMessage`: `string`
- Description:
> Error message when the message status is `failed`.
- `externalId`: `string`
- Description:
> A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
- `from`: `string` (required)
- Description:
> The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `id`: `string` (required)
- Description:
> Unique ID of the message.
- `image`: `#/components/schemas/WhatsappMessageMedia`
- `interactive`: `#/components/schemas/WhatsappMessageInteractive`
- `location`: `#/components/schemas/WhatsappMessageLocation`
- `parentRecipientUserId`: `string`
- Description:
> The recipient's parent WhatsApp Business-scoped user ID.
- Constraints: example="US.ENT.1234"
- `pricingCategory`: `#/components/schemas/WhatsappPricingCategory`
- Description:
> The pricing category of the message.
> **Note: It's only an estimated pricing category when the `status` is `accepted` or `sent`. It becomes final after the message is delivered, i.e., the `status` is `delivered` or `read`.**
- `pricingModel`: `#/components/schemas/WhatsappPricingModel`
- Description:
> The pricing model of the message.
> - `PMP`: Per-message pricing applies.
> - `CBP`: Conversation-based pricing applies.
- `pricingType`: `#/components/schemas/WhatsappPricingType`
- Description:
> The pricing type of the message. This field is only available in PMP (Per-Message Pricing) mode.
> - `regular`: Indicates the message is billable.
> - `free_customer_service`: Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.
> - `free_entry_point`: Indicates the message is free because it is part of a free-entry point conversation.
- `reaction`: `#/components/schemas/WhatsappMessageReaction`
- `readTime`: `string (date-time)`
- Description:
> The time at which this message `status` changed to `read`, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `recipient`: `string`
- Description:
> The recipient value submitted in the request when a BSUID or parent BSUID was used.
- Constraints: example="US.1234"
- `recipientUserId`: `string`
- Description:
> The recipient's WhatsApp Business-scoped user ID (BSUID).
- Constraints: example="US.1234"
- `regionCode`: `string`
- Description:
> The [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the recipient phone number.
- Constraints: example="US"
- `sendTime`: `string (date-time)`
- Description:
> The time at which this message `status` changed to `sent`, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `status`: `#/components/schemas/WhatsappMessageStatus`
- `sticker`: `#/components/schemas/WhatsappMessageMedia`
- `template`: `#/components/schemas/WhatsappMessageTemplate`
- `text`: `#/components/schemas/WhatsappMessageText`
- `to`: `string`
- Description:
> The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `toParentUserId`: `string`
- Description:
> Alias of `parentRecipientUserId` kept for compatibility.
- Constraints: example="US.ENT.1234"
- `toUserId`: `string`
- Description:
> Alias of `recipientUserId` kept for compatibility.
- Constraints: example="US.1234"
- `totalPrice`: `number (double)`
- Description:
> Total price of this message.
> **Note: It's only an estimated price when the `status` is `accepted` or `sent`. It becomes the final price after the message is delivered, i.e., the `status` is `delivered` or `read`.**
- Constraints: example=0.05
- `type`: `#/components/schemas/WhatsappMessageType`
- `updateTime`: `string (date-time)`
- Description:
> The time at which this message is updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
- Constraints: example="2022-06-01T12:00:00.000Z"
- `verificationId`: `string`
- Description:
> The verification ID. Included only when `bizType` is `verify`.
- Constraints: example="VERIFICATION-ID"
- `video`: `#/components/schemas/WhatsappMessageMedia`
- `wabaId`: `string` (required)
- Description:
> WhatsApp Business Account ID.
- Constraints: example="whatsapp-business-account-id"
- `wamid`: `string`
- Description:
> The original message ID on WhatsApp's platform.
- Constraints: example="wamid.BgNODYxN..."
- `whatsappApiError`: `#/components/schemas/WhatsappApiError`
### `WhatsappMessageContact`
- Reference: `#/components/schemas/WhatsappMessageContact`
- Shape: `object`
- Description:
> When the message type filed is set to `contacts`, this object is included in the message object.
- Required properties: `name`
- Properties:
- `addresses`: `array`
- Items: `#/components/schemas/WhatsappMessageContactAddress`
- `birthday`: `string`
- Description:
> `YYYY-MM-DD` formatted string.
- Constraints: example="2022-09-27"
- `emails`: `array`
- Items: `#/components/schemas/WhatsappMessageContactEmail`
- `name`: `#/components/schemas/WhatsappMessageContactName` (required)
- `org`: `#/components/schemas/WhatsappMessageContactOrg`
- `phones`: `array`
- Description:
> Contact phone number(s) formatted as a phone object.
- Items: `#/components/schemas/WhatsappMessageContactPhone`
- `urls`: `array`
- Description:
> Contact URL(s) formatted as a urls object.
- Items: `#/components/schemas/WhatsappMessageContactUrl`
### `WhatsappMessageContactAddress`
- Reference: `#/components/schemas/WhatsappMessageContactAddress`
- Shape: `object`
- Description:
> Full contact address(es) formatted as an addresses object.
- Properties:
- `city`: `string`
- Description:
> City name.
- `country`: `string`
- Description:
> Full country name.
- `country_code`: `string`
- Description:
> Two-letter country abbreviation.
- `state`: `string`
- Description:
> State abbreviation.
- `street`: `string`
- Description:
> Street number and name.
- `type`: `string`
- Description:
> Standard values are `HOME` and `WORK`.
- Constraints: example="WORK"
- `zip`: `string`
- Description:
> ZIP code.
### `WhatsappMessageContactEmail`
- Reference: `#/components/schemas/WhatsappMessageContactEmail`
- Shape: `object`
- Description:
> Contact email address(es) formatted as an emails object.
- Properties:
- `email`: `string`
- Description:
> Email address.
- `type`: `string`
- Description:
> Standard values are `HOME` and `WORK`.
- Constraints: example="WORK"
### `WhatsappMessageContactName`
- Reference: `#/components/schemas/WhatsappMessageContactName`
- Shape: `object`
- Description:
> Full contact name formatted as a name object.
- Required properties: `formatted_name`
- Properties:
- `first_name`: `string`
- Description:
> First name.
- `formatted_name`: `string` (required)
- Description:
> Full name, as it normally appears.
- `last_name`: `string`
- Description:
> Last name.
- `middle_name`: `string`
- Description:
> Middle name.
- `prefix`: `string`
- Description:
> Name prefix.
- `suffix`: `string`
- Description:
> Name suffix.
### `WhatsappMessageContactOrg`
- Reference: `#/components/schemas/WhatsappMessageContactOrg`
- Shape: `object`
- Description:
> Contact organization information formatted as an org object.
- Properties:
- `company`: `string`
- Description:
> Name of the contact's company.
- `department`: `string`
- Description:
> Name of the contact's department.
- `title`: `string`
- Description:
> Contact's business title.
### `WhatsappMessageContactPhone`
- Reference: `#/components/schemas/WhatsappMessageContactPhone`
- Shape: `object`
- Properties:
- `phone`: `string`
- Description:
> Automatically populated with the `wa_id` value as a formatted phone number.
- `type`: `string`
- Description:
> Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`.
- `wa_id`: `string`
- Description:
> WhatsApp ID.
### `WhatsappMessageContactUrl`
- Reference: `#/components/schemas/WhatsappMessageContactUrl`
- Shape: `object`
- Properties:
- `type`: `string`
- Description:
> Standard values are `HOME` and `WORK`.
- `url`: `string`
- Description:
> URL.
### `WhatsappMessageContext`
- Reference: `#/components/schemas/WhatsappMessageContext`
- Shape: `object`
- Description:
> Used to mention a specific message you are replying to. The reply can be any message type.
- Properties:
- `message_id`: `string`
- Description:
> Specifies the `wamid` of the message your are replying to. `wamid` is the original message ID on WhatsApp's platform.
- Constraints: example="wamid.BgNODYxN..."
### `WhatsappMessageInteractive`
- Reference: `#/components/schemas/WhatsappMessageInteractive`
- Shape: `object`
- Description:
> Use for `interactive` messages.
- Properties:
- `action`: `#/components/schemas/WhatsappMessageInteractiveAction`
- `body`: `#/components/schemas/WhatsappMessageInteractiveBody`
- `footer`: `#/components/schemas/WhatsappMessageInteractiveFooter`
- `header`: `#/components/schemas/WhatsappMessageInteractiveHeader`
- `type`: `string`
- Description:
> **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.
> - `carousel`: Use for media carousel message.
- Constraints: enum=["button", "list", "cta_url", "product", "product_list", "catalog_message", "location_request_message", "order_details", "order_status", "voice_call", "flow", "carousel"]
### `WhatsappMessageInteractiveAction`
- Reference: `#/components/schemas/WhatsappMessageInteractiveAction`
- Shape: `object`
- Description:
> **Required.**
> Action you want the user to perform after reading the `interactive` message.
- Properties:
- `button`: `string`
- Description:
> 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.
- Constraints: maxLength=20
- `buttons`: `array`
- Description:
> Required for Reply Buttons. You can have up to 3 buttons.
- Constraints: maxItems=3
- Items: `#/components/schemas/WhatsappMessageInteractiveActionButton`
- `cards`: `array`
- Description:
> Required for Carousel Messages.
> Array of card objects. Minimum of 2, maximum of 10.
- Constraints: maxItems=10
- Items: `#/components/schemas/WhatsappMessageInteractiveActionCard`
- `catalog_id`: `string`
- Description:
> 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).
- `name`: `string`
- Description:
> Action name.
> Required for Call-To-Action (CTA) buttons.
> - `cta_url`: Use for Call-To-Action (CTA) URL buttons.
> - `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.
- Constraints: enum=["cta_url", "send_location", "flow", "review_and_pay", "review_order", "voice_call"]
- `parameters`: `#/components/schemas/WhatsappMessageInteractiveActionParameters`
- `product_retailer_id`: `string`
- Description:
> Required for Single Product Messages and Multi-Product Messages.
> Unique identifier of the product in a catalog.
- `sections`: `array`
- Description:
> Required for List Messages and Multi-Product Messages.
> Array of section objects. Minimum of 1, maximum of 10.
- Constraints: minItems=1; maxItems=10
- Items: `#/components/schemas/WhatsappMessageInteractiveActionSection`
### `WhatsappMessageInteractiveActionButton`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionButton`
- Shape: `object`
- Description:
> A button object in `interactive` messages.
- Properties:
- `reply`: `object`
- `type`: `string`
- Description:
> Only supported type is `reply` (for Reply Button).
- Constraints: enum=["reply"]
### `WhatsappMessageInteractiveActionCard`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionCard`
- Shape: `object`
- Description:
> A card object in `interactive` messages. All cards must have the same structure.
- Properties:
- `action`: `#/components/schemas/WhatsappMessageInteractiveActionCardAction`
- `body`: `#/components/schemas/WhatsappMessageInteractiveActionCardBody`
- `card_index`: `number`
- Description:
> Card index. Unique index for each card (0-9).
- `header`: `#/components/schemas/WhatsappMessageInteractiveActionCardHeader`
- `type`: `string`
- Description:
> Must be "cta_url".
### `WhatsappMessageInteractiveActionCardAction`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionCardAction`
- Shape: `object`
- Description:
> A button object in `interactive` messages.
> Cards must include either one URL button, or one or more quick-reply buttons. Button types and numbers must match across all cards (for example, if you define a card with 2 quick-reply buttons, all cards must define exactly 2 quick-reply buttons).
- Properties:
- `buttons`: `array`
- Description:
> Required when card action is quick reply button.
- Items: `#/components/schemas/WhatsappMessageInteractiveActionCardActionButton`
- `name`: `string`
- Description:
> Required when card action is url button. Must be "cta_url".
- `parameters`: `#/components/schemas/WhatsappMessageInteractiveActionCardActionParameters`
### `WhatsappMessageInteractiveActionCardActionButton`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionCardActionButton`
- Shape: `object`
- Properties:
- `quick_reply`: `object`
- `type`: `string`
- Description:
> Must be "quick_reply".
### `WhatsappMessageInteractiveActionCardActionParameters`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionCardActionParameters`
- Shape: `object`
- Description:
> Required when card action is url button. Only support `display_text` and `url`. Button display text Max 20 chars.
- Properties:
- `display_text`: `string`
- Description:
> Text of the CTA URL button.
> Maximum length: 20 bytes.
- Constraints: maxLength=20; example="See Docs"
- `url`: `string`
- Description:
> URL of the CTA URL button.
- Constraints: example="https://developers.facebook.com/docs/whatsapp"
### `WhatsappMessageInteractiveActionCardBody`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionCardBody`
- Shape: `object`
- Description:
> Optional for card.
- Properties:
- `text`: `string`
- Description:
> Max 160 chars, and up to 2 line breaks.
- Constraints: maxLength=160
### `WhatsappMessageInteractiveActionCardHeader`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionCardHeader`
- Shape: `object`
- Properties:
- `image`: `#/components/schemas/WhatsappMessageMedia`
- `type`: `string`
- Description:
> **Required.**
> The header type you would like to use.
> - `video`: Used for Reply Buttons.
> - `image`: Used for Reply Buttons.
- Constraints: enum=["image", "video"]
- `video`: `#/components/schemas/WhatsappMessageMedia`
### `WhatsappMessageInteractiveActionParameters`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionParameters`
- Shape: `object`
- Description:
> Action parameters.
> Required for Call-To-Action (CTA) buttons.
- Properties:
- `beneficiaries`: `array`
- Description:
> 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.
- Items: `#/components/schemas/WhatsappMessageOrderBeneficiary`
- `currency`: `string`
- Description:
> Required for `review_and_pay` buttons.
> The currency for this order.
> Currently the only supported value is `INR`.
- `display_text`: `string`
- Description:
> Text of the CTA URL button.
> Maximum length: 20 bytes.
- Constraints: maxLength=20; example="See Docs"
- `flow_action`: `string`
- Description:
> Use for `flow` buttons.
> Either `navigate` or `data_exchange`. Defaults to `navigate`.
- Constraints: example="navigate"
- `flow_action_payload`: `object`
- Description:
> Required if `flow_action` is `navigate`. Should be omitted otherwise.
- `flow_cta`: `string`
- Description:
> Required for `flow` buttons.
> Text on the CTA button. For example: "Open flow!". Maximum length: 20 characters.
- Constraints: maxLength=20; example="Open flow!"
- `flow_id`: `string`
- Description:
> Conditionally required for `flow` buttons. Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter.
- `flow_message_version`: `string`
- Description:
> Use for `flow` buttons.
> Value must be "3".
- `flow_name`: `string`
- Description:
> 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_token`: `string`
- Description:
> Use for `flow` buttons.
> Flow token that is generated by the business to serve as an identifier. Defaults to `unused`.
- `order`: `#/components/schemas/WhatsappMessageOrderInfo`
- Description:
> 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`: `array`
- Description:
> Required for `review_and_pay` buttons.
> Payment settings for the order.
- Items: `#/components/schemas/WhatsappMessageOrderPaymentSetting`
- `reference_id`: `string`
- Description:
> 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.
- `thumbnail_product_retailer_id`: `string`
- Description:
> 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.
- `total_amount`: `#/components/schemas/WhatsappMessageOrderAmount`
- Description:
> Required for `review_and_pay` buttons.
> The total amount for this order.
- `type`: `string`
- Description:
> 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`.
- `url`: `string`
- Description:
> URL of the CTA URL button.
- Constraints: example="https://developers.facebook.com/docs/whatsapp"
### `WhatsappMessageInteractiveActionSection`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionSection`
- Shape: `object`
- Description:
> WhatsApp Message Interactive Section Object.
- Properties:
- `product_items`: `array`
- Description:
> 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.
- Constraints: minItems=1; maxItems=30
- Items: `#/components/schemas/WhatsappMessageInteractiveActionSectionProductItem`
- `rows`: `array`
- Description:
> 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.
- Constraints: maxItems=10
- Items: `#/components/schemas/WhatsappMessageInteractiveActionSectionRow`
- `title`: `string`
- Description:
> **Required if the message has more than one section.**
> Title of the section. Maximum length: 24 characters.
- Constraints: maxLength=24
### `WhatsappMessageInteractiveActionSectionProductItem`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionSectionProductItem`
- Shape: `object`
- Properties:
- `product_retailer_id`: `string`
- Description:
> Required for Multi-Product Messages.
> Unique identifier of the product in a catalog.
### `WhatsappMessageInteractiveActionSectionRow`
- Reference: `#/components/schemas/WhatsappMessageInteractiveActionSectionRow`
- Shape: `object`
- Properties:
- `description`: `string`
- Description:
> Row description content. Maximum length: 72 characters.
- Constraints: maxLength=72
- `id`: `string`
- Description:
> Unique row ID. Maximum length: 200 characters.
- Constraints: maxLength=200
- `title`: `string`
- Description:
> Row title content. Maximum length: 24 characters.
- Constraints: maxLength=24
### `WhatsappMessageInteractiveBody`
- Reference: `#/components/schemas/WhatsappMessageInteractiveBody`
- Shape: `object`
- Description:
> Optional for type `product`. Required for other message types.
- Properties:
- `text`: `string`
- Description:
> The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.
- Constraints: maxLength=1024
### `WhatsappMessageInteractiveFooter`
- Reference: `#/components/schemas/WhatsappMessageInteractiveFooter`
- Shape: `object`
- Description:
> Optional. An object with the footer of the message.
- Properties:
- `text`: `string`
- Description:
> The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters.
- Constraints: maxLength=60
### `WhatsappMessageInteractiveHeader`
- Reference: `#/components/schemas/WhatsappMessageInteractiveHeader`
- Shape: `object`
- Description:
> Required for type `product_list`. Optional for other types.
- Properties:
- `document`: `#/components/schemas/WhatsappMessageMedia`
- `image`: `#/components/schemas/WhatsappMessageMedia`
- `text`: `string`
- Description:
> Text for the header. Formatting allows emojis, but not markdown.
- Constraints: maxLength=60
- `type`: `string`
- Description:
> **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.
- Constraints: enum=["text", "image", "video", "document"]
- `video`: `#/components/schemas/WhatsappMessageMedia`
### `WhatsappMessageLocation`
- Reference: `#/components/schemas/WhatsappMessageLocation`
- Shape: `object`
- Description:
> Use for `location` messages.
- Required properties: `latitude`, `longitude`
- Properties:
- `address`: `string`
- Description:
> Address of the location. Only displayed if `name` is present.
- `latitude`: `number (double)` (required)
- Description:
> Latitude of the location.
- `longitude`: `number (double)` (required)
- Description:
> Longitude of the location.
- `name`: `string`
- Description:
> Name of the location.
### `WhatsappMessageMedia`
- Reference: `#/components/schemas/WhatsappMessageMedia`
- Shape: `object`
- Description:
> 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).
>
> **Note**: Either `id` or `link` must be provided, but not both. These parameters are mutually exclusive.
>
> Reference: [WhatsApp Cloud API Media Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object)
- Properties:
- `caption`: `string`
- Description:
> Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages.
- `filename`: `string`
- Description:
> Describes the filename for the specific document. Use only with `document` media.
- `id`: `string`
- Description:
> **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`
- Description:
> **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.
### `WhatsappMessageOrderAmount`
- Reference: `#/components/schemas/WhatsappMessageOrderAmount`
- Shape: `object`
- Description:
> Represents the amount of an order.
- Required properties: `offset`, `value`
- Properties:
- `description`: `string`
- Description:
> Use only for `tax`, `shipping`, or `discount`.
> Description of the amount. Max character limit is 60 characters.
- Constraints: maxLength=60
- `discount_program_name`: `string`
- Description:
> 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.
- Constraints: maxLength=60
- `offset`: `integer (int32)` (required)
- Description:
> Must be `100` for `INR`.
- Constraints: example=100
- `value`: `integer (int32)` (required)
- Description:
> Positive integer representing the amount value multiplied by offset.
> For example, ₹12.34 has value 1234.
- Constraints: example=1234
### `WhatsappMessageOrderBeneficiary`
- Reference: `#/components/schemas/WhatsappMessageOrderBeneficiary`
- Shape: `object`
- Description:
> 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.
- Required properties: `name`, `address_line1`, `city`, `state`, `country`, `postal_code`
- Properties:
- `address_line1`: `string` (required)
- Description:
> Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters.
- Constraints: maxLength=100
- `address_line2`: `string`
- Description:
> Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters.
- Constraints: maxLength=100
- `city`: `string` (required)
- Description:
> Name of the city.
- `country`: `string` (required)
- Description:
> Name of the country.
> Currently the only supported value is `India`.
- `name`: `string` (required)
- Description:
> Name of the individual or business receiving the physical goods. Cannot exceed 200 characters.
- Constraints: maxLength=200
- `postal_code`: `string` (required)
- Description:
> 6-digit zipcode of shipping address.
- Constraints: minLength=6; maxLength=6
- `state`: `string` (required)
- Description:
> Name of the state.
### `WhatsappMessageOrderDetails`
- Reference: `#/components/schemas/WhatsappMessageOrderDetails`
- Shape: `object`
- Description:
> Contains the order details when sending a template message with a `order_details` button.
- Required properties: `currency`, `order`, `reference_id`, `total_amount`, `type`, `payment_settings`
- Properties:
- `currency`: `string` (required)
- Description:
> The currency for this order.
> Currently the only supported value is `INR`.
- `order`: `#/components/schemas/WhatsappMessageOrderInfo` (required)
- Description:
> Provides order `status`, `items`, `subtotal`, `tax`, etc.
- `payment_settings`: `array` (required)
- Description:
> Payment settings for the order.
- Items: `#/components/schemas/WhatsappMessageOrderPaymentSetting`
- `reference_id`: `string` (required)
- Description:
> 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.
- `total_amount`: `#/components/schemas/WhatsappMessageOrderAmount` (required)
- Description:
> The total amount of the order.
- `type`: `string` (required)
- Description:
> The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`.
### `WhatsappMessageOrderExpiration`
- Reference: `#/components/schemas/WhatsappMessageOrderExpiration`
- Shape: `object`
- Description:
> Expiration for this order.
- Required properties: `timestamp`
- Properties:
- `description`: `string`
- Description:
> Text explanation for expiration.
- Constraints: maxLength=120
- `timestamp`: `string` (required)
- Description:
> A string of UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds.
- Constraints: example="1727438564"
### `WhatsappMessageOrderInfo`
- Reference: `#/components/schemas/WhatsappMessageOrderInfo`
- Shape: `object`
- Description:
> Order info.
- Properties:
- `catalog_id`: `string`
- Description:
> 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`.
- `description`: `string`
- Description:
> **Optional.**
> Text for sharing status related information. Could be useful while sending cancellation. Max character limit is 120 characters.
- Constraints: maxLength=120
- `discount`: `#/components/schemas/WhatsappMessageOrderAmount`
- Description:
> The discount amount for this order.
- `expiration`: `#/components/schemas/WhatsappMessageOrderExpiration`
- `items`: `array`
- Description:
> Array of items in the order.
- Items: `#/components/schemas/WhatsappMessageOrderItem`
- `shipping`: `#/components/schemas/WhatsappMessageOrderAmount`
- Description:
> The shipping cost of the order.
- `status`: `#/components/schemas/WhatsappMessageOrderStatusEnum`
- `subtotal`: `#/components/schemas/WhatsappMessageOrderAmount`
- Description:
> The value **must be equal** to sum of `order.amount.value` * `order.amount.quantity`.
- `tax`: `#/components/schemas/WhatsappMessageOrderAmount`
- Description:
> The tax information for this order.
- `type`: `string`
- Description:
> 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.
### `WhatsappMessageOrderItem`
- Reference: `#/components/schemas/WhatsappMessageOrderItem`
- Shape: `object`
- Required properties: `name`, `amount`, `quantity`
- Properties:
- `amount`: `#/components/schemas/WhatsappMessageOrderAmount` (required)
- Description:
> The price per item.
- `country_of_origin`: `string`
- Description:
> Required if `catalog_id` is not present.
> The country of origin of the product.
- `image`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> Custom image for the item to be displayed to the user.
- `importer_address`: `string`
- Description:
> Required if `catalog_id` is not present.
> Address of importer company.
- `importer_name`: `string`
- Description:
> Required if `catalog_id` is not present.
> Name of the importer company.
- `name`: `string` (required)
- Description:
> The item's name to be displayed to the user. Cannot exceed 60 characters.
- Constraints: maxLength=60
- `quantity`: `integer (int32)` (required)
- Description:
> The number of items in the order.
- `retailer_id`: `string`
- Description:
> Content ID for an item in the order from your catalog.
- `sale_amount`: `#/components/schemas/WhatsappMessageOrderAmount`
- Description:
> The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount.
### `WhatsappMessageOrderPaymentGateway`
- Reference: `#/components/schemas/WhatsappMessageOrderPaymentGateway`
- Shape: `object`
- Description:
> An object that describes payment account information.
- Required properties: `type`, `configuration_name`
- Properties:
- `billdesk`: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk`
- `configuration_name`: `string` (required)
- Description:
> 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.
- Constraints: maxLength=60
- `payu`: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayPayu`
- `razorpay`: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay`
- `type`: `string` (required)
- Description:
> 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.
- Constraints: enum=["billdesk", "razorpay", "payu", "zaakpay"]
- `zaakpay`: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay`
### `WhatsappMessageOrderPaymentSetting`
- Reference: `#/components/schemas/WhatsappMessageOrderPaymentSetting`
- Shape: `object`
- Description:
> Payment settings for the order.
- Required properties: `type`, `payment_gateway`
- Properties:
- `payment_gateway`: `#/components/schemas/WhatsappMessageOrderPaymentGateway` (required)
- `type`: `string` (required)
- Description:
> Must be set to `payment_gateway`.
- Constraints: example="payment_gateway"
### `WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk`
- Reference: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk`
- Shape: `object`
- Description:
> 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.
- Properties:
- `additional_info1`: `string`
- `additional_info2`: `string`
- `additional_info3`: `string`
- `additional_info4`: `string`
- `additional_info5`: `string`
- `additional_info6`: `string`
- `additional_info7`: `string`
### `WhatsappMessageOrderPaymentSettingPaymentGatewayPayu`
- Reference: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayPayu`
- Shape: `object`
- Description:
> 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.
- Properties:
- `udf1`: `string`
- `udf2`: `string`
- `udf3`: `string`
- `udf4`: `string`
### `WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay`
- Reference: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay`
- Shape: `object`
- Description:
> Additional info for Razorpay.
- Properties:
- `notes`: `object`
- Description:
> The object can be key value pairs with maximum 15 keys and each value limits to 256 characters.
- Constraints: additionalProperties={"type": "string"}
- `receipt`: `string`
- Description:
> 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.
### `WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay`
- Reference: `#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay`
- Shape: `object`
- Description:
> 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.
- Properties:
- `extra1`: `string`
- `extra2`: `string`
### `WhatsappMessageOrderStatus`
- Reference: `#/components/schemas/WhatsappMessageOrderStatus`
- Shape: `object`
- Properties:
- `order`: `#/components/schemas/WhatsappMessageOrderInfo`
- Description:
> Provides only `status` and `description` of this order for `order_status` messages.
- `reference_id`: `string`
- Description:
> Unique identifier for the order provided by the business.
### `WhatsappMessageOrderStatusEnum`
- Reference: `#/components/schemas/WhatsappMessageOrderStatusEnum`
- Shape: `string`
- Description:
> 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`.
- Constraints: enum=["pending", "processing", "partially_shipped", "shipped", "completed", "canceled"]
### `WhatsappMessageReaction`
- Reference: `#/components/schemas/WhatsappMessageReaction`
- Shape: `object`
- Description:
> When a user reacts to messages with an emoji, the message type is set to `reaction`, and this field is included.
- Required properties: `message_id`
- Properties:
- `emoji`: `string`
- Description:
> **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.
- `message_id`: `string` (required)
- Description:
> Specifies the `wamid` of the message received that contained the reaction.
- Constraints: example="wamid.BgNODYxN..."
### `WhatsappMessageSendRequest`
- Reference: `#/components/schemas/WhatsappMessageSendRequest`
- Shape: `object`
- Description:
> Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.
- Required properties: `from`, `type`
- Properties:
- `audio`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> Required when `type` is `audio`.
- `category`: `string`
- Description:
> **Optional.**
> Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`.
>
> Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates.
>
> Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages.
- Constraints: enum=["utility", "authentication"]; example="utility"
- `contacts`: `array`
- Description:
> Required when `type` is `contacts`.
- Items: `#/components/schemas/WhatsappMessageContact`
- `context`: `#/components/schemas/WhatsappMessageContext`
- `customerProfile`: `#/components/schemas/WhatsappProfile`
- Description:
> The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios.
- `document`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> Required when `type` is `document`.
- `externalId`: `string`
- Description:
> A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
- `filterBlocked`: `boolean`
- Description:
> **Optional.**
> If set to `true`, the message will not be sent to users in your block list. Defaults to `false`.
>
> Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`.
>
> Not applicable to `POST /v2/whatsapp/messages/sendDirectly`.
- `filterUnsubscribed`: `boolean`
- Description:
> **Optional.**
> If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`.
>
> Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`.
>
> Not applicable to `POST /v2/whatsapp/messages/sendDirectly`.
- `from`: `string` (required)
- Description:
> The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
- Constraints: example="+16315551111"
- `image`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> Required when `type` is `image`.
- `interactive`: `#/components/schemas/WhatsappMessageInteractive`
- Description:
> Required when `type` is `interactive`.
- `location`: `#/components/schemas/WhatsappMessageLocation`
- Description:
> Required when `type` is `location`.
- `reaction`: `#/components/schemas/WhatsappMessageReaction`
- Description:
> Required when `type` is `reaction`.
- `recipient`: `string`
- Description:
> The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided.
- Constraints: example="US.1234"
- `sticker`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> Required when `type` is sticker.
- `template`: `#/components/schemas/WhatsappMessageTemplate`
- Description:
> Required when `type` is `template`.
- `text`: `#/components/schemas/WhatsappMessageText`
- Description:
> Required when `type` is `text`.
- `to`: `string`
- Description:
> The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided.
- Constraints: example="+16315551111"
- `ttlSeconds`: `integer`
- Description:
> **Optional.**
> Message time-to-live in seconds for Direct Send `utility` or `authentication` messages.
>
> The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used.
- Constraints: minimum=30; maximum=43200; example=600
- `type`: `#/components/schemas/WhatsappMessageType` (required)
- `useDirectSend`: `boolean`
- Description:
> **Optional.**
> Whether to send the message through Direct Send. Defaults to `false`.
>
> Set this to `true` to send the message through Direct Send when the sender WABA is enabled for Direct Send.
>
> For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are:
>
> - Text messages
> - Interactive Call-to-Action URL button messages
> - Interactive reply button messages
- Constraints: default=false
- `video`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> Required when `type` is `video`.
### `WhatsappMessageStatus`
- Reference: `#/components/schemas/WhatsappMessageStatus`
- Shape: `string`
- Description:
> 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.
- Constraints: enum=["accepted", "failed", "sent", "delivered", "read"]
### `WhatsappMessageTemplate`
- Reference: `#/components/schemas/WhatsappMessageTemplate`
- Shape: `object`
- Description:
> Use for sending a WhatsApp `template` message.
- Required properties: `name`, `language`
- Properties:
- `components`: `array`
- Description:
> **Required when the specified template contains variables or media.**
> Array of component objects containing the parameters of the message.
- Items: `#/components/schemas/WhatsappMessageTemplateComponent`
- `language`: `object` (required)
- Description:
> Contains a language object. Specifies the language the template may be rendered in.
- `name`: `string` (required)
- Description:
> Name of the template.
- Constraints: example="sample_whatsapp_template"
### `WhatsappMessageTemplateComponent`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponent`
- Shape: `object`
- Description:
> Component object containing the parameters of the message.
- Required properties: `type`
- Properties:
- `cards`: `array`
- Description:
> Use for `carousel` components. Provides card components containing the parameters of the message.
- Items: `#/components/schemas/WhatsappMessageTemplateComponentCard`
- `index`: `integer (int32)`
- Description:
> **Required when `type` = `button`. Not used for the other types.**
> Indicates order in which button should appear, if the template uses multiple buttons.
> Buttons are zero-indexed, so setting value to 0 will cause the button to appear first, and another button with an index of 1 will appear next, etc.
- Constraints: minimum=0; maximum=9
- `parameters`: `array`
- Description:
> **Required when `type` = `button`, or there are variables in the corresponding template component, or the template `HEADER` format is media (`IMAGE`, `VIDEO`, or `DOCUMENT`).**
> Array of parameter objects with the content of the message.
- Items: `#/components/schemas/WhatsappMessageTemplateComponentParameter`
- `sub_type`: `string`
- Description:
> **Required when type is `button`.**
> Type of button.
> - `quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message.
> - `url`: Refers to a previously created url button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.
> - `copy_code`: Refers to a previously created copy code button that allows the customer to copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user.
> - `catalog`: Refers to a previously created catalog button that allows the customer to view your product catalog.
> - `mpm`: Refers to a previously created MPM (multi-product message) button that allows the customer to browser products and sections.
> - `flow`: Refers to a previously created flow button that allows the customer to interact with a [flow](https://developers.facebook.com/docs/whatsapp/flows).
> - `order_details`: Refers to a previously created order details button that allows the customer to view the details of an order.
- Constraints: enum=["quick_reply", "url", "copy_code", "catalog", "mpm", "flow", "order_details"]
- `type`: `string` (required)
- Description:
> Component type.
- Constraints: enum=["header", "body", "button", "limited_time_offer", "carousel", "order_status"]
### `WhatsappMessageTemplateComponentCard`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentCard`
- Shape: `object`
- Description:
> Card component containing the parameters of the message.
- Properties:
- `card_index`: `integer (int32)`
- Description:
> **Required.**
> Zero-indexed order in which card appears within the card carousel. 0 indicates first card, 1 indicates second card, etc.
- Constraints: minimum=0; maximum=9
- `components`: `array`
- Description:
> Card component.
- Items: `#/components/schemas/WhatsappMessageTemplateComponentCardComponent`
### `WhatsappMessageTemplateComponentCardComponent`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentCardComponent`
- Shape: `object`
- Description:
> Card component object containing the parameters of the message.
- Required properties: `type`
- Properties:
- `index`: `integer (int32)`
- Description:
> **Required when `type` = `button`. Not used for the other types.**
> Indicates order in which button should appear, if the template uses multiple buttons.
> Buttons are zero-indexed, so setting value to 0 will cause the button to appear first, and another button with an index of 1 will appear next, etc.
- Constraints: minimum=0; maximum=9
- `parameters`: `array`
- Description:
> **Required when `type` = `button`, or there are variables in the corresponding template component, or the card component `HEADER` format is media (`IMAGE`, `VIDEO`).**
> Array of parameter objects with the content of the message.
- Items: `#/components/schemas/WhatsappMessageTemplateComponentParameter`
- `sub_type`: `string`
- Description:
> **Required when type is `button`.**
> Type of button.
> - `quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message.
> - `url`: Refers to a previously created url button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.
- Constraints: enum=["quick_reply", "url"]
- `type`: `string` (required)
- Description:
> Component type.
- Constraints: enum=["header", "body", "button"]
### `WhatsappMessageTemplateComponentParameter`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentParameter`
- Shape: `object`
- Properties:
- `action`: `#/components/schemas/WhatsappMessageTemplateComponentParameterAction`
- `coupon_code`: `string`
- Description:
> **Required when `type` = `coupon_code`.**
> The coupon code to be copied when the customer taps the button.
- `document`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> **Required when the template `HEADER` format is `DOCUMENT`.**
- `gif`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> **Required when the template `HEADER` format is `GIF`.**
- `group_id`: `string`
- Description:
> **Required when `type` = `group_id`.**
> WhatsApp group ID used by group invite link templates.
- Constraints: example="120363345678901234@g.us"
- `image`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> **Required when the template `HEADER` format is `IMAGE`.**
- `limited_time_offer`: `#/components/schemas/WhatsappMessageTemplateComponentParameterLimitedTimeOffer`
- `location`: `#/components/schemas/WhatsappMessageLocation`
- Description:
> **Required when `type` = `location`.**
- `order_status`: `#/components/schemas/WhatsappMessageOrderStatus`
- `payload`: `string`
- Description:
> Required for `quick_reply` buttons.
> Developer-defined payload that is returned when the button is clicked in addition to the display text on the button.
- `text`: `string`
- Description:
> **Required when `type` = `text`.**
> The message's text. For the header component, the character limit is 60 characters. For the body component, the character limit is 1024 characters.
> For url buttons, it indicates the developer-provided suffix that is appended to the predefined prefix URL in the template.
- `type`: `string`
- Description:
> **Required.**
> Component parameter type.
> - `text`: Used when the template component type is `BODY`, or the `HEADER` component format is `TEXT`.
> - `image`: Used when the template `HEADER` component is `IMAGE`.
> - `gif`: Used when the template `HEADER` component is `GIF`.
> - `video`: Used when the template `HEADER` component is `VIDEO`.
> - `document`: Used when the template `HEADER` component is `DOCUMENT`.
> - `payload`: Used when the template component button type is `QUICK_REPLY`.
> - `coupon_code`: Used when the template component button type is `COPY_CODE`.
> - `limited_time_offer`: Used when the template component type is `LIMITED_TIME_OFFER`.
> - `action`: Used when the template component button type is `CATALOG`, `MPM`, `FLOW`, or `ORDER_DETAILS`.
> - `order_status`: Used when the template subcategory is `ORDER_STATUS`.
> - `location`: Used when the template `HEADER` component is `LOCATION`.
> - `group_id`: Used by WhatsApp group invite link templates.
- Constraints: enum=["text", "image", "gif", "video", "document", "payload", "coupon_code", "limited_time_offer", "action", "order_status", "location", "group_id"]
- `video`: `#/components/schemas/WhatsappMessageMedia`
- Description:
> **Required when the template `HEADER` format is `VIDEO`.**
### `WhatsappMessageTemplateComponentParameterAction`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentParameterAction`
- Shape: `object`
- Description:
> Required if template uses catalog or MPM (multi-product message) buttons.
- Properties:
- `flow_action_data`: `object`
- Description:
> Use for `FLOW` buttons.
> JSON object with the data payload for the first screen.
- Constraints: additionalProperties={"type": "object"}
- `flow_token`: `string`
- Description:
> Use for `FLOW` buttons.
> Flow token that is generated by the business to serve as an identifier. Defaults to `unused`.
- `order_details`: `#/components/schemas/WhatsappMessageOrderDetails`
- Description:
> Required for `order_details` buttons.
- `sections`: `array`
- Description:
> Use for MPM templates.
> Product sections. You can define up to 10 sections.
- Constraints: maxItems=10
- Items: `#/components/schemas/WhatsappMessageTemplateComponentParameterActionSection`
- `thumbnail_product_retailer_id`: `string`
- Description:
> **Optional.**
> Use for catalog and MPM template messages.
> 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.
> If the `parameters` object is omitted, the product image of the first item in your catalog will be used.
- Constraints: example="2lc20305pt"
### `WhatsappMessageTemplateComponentParameterActionSection`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentParameterActionSection`
- Shape: `object`
- Properties:
- `product_items`: `array`
- Description:
> Array of product SKU numbers. There is a minimum of 1 product per section and a maximum of 30 products across all sections.
- Constraints: minItems=1; maxItems=30
- Items: `#/components/schemas/WhatsappMessageTemplateComponentParameterActionSectionProductItem`
- `title`: `string`
- Description:
> Section title text.
> Maximum 24 characters. Markdown is not supported.
- Constraints: maxLength=24
### `WhatsappMessageTemplateComponentParameterActionSectionProductItem`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentParameterActionSectionProductItem`
- Shape: `object`
- Properties:
- `product_retailer_id`: `string`
- Description:
> SKU number of the item you want to appear in the section.
> SKU numbers are labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce).
### `WhatsappMessageTemplateComponentParameterLimitedTimeOffer`
- Reference: `#/components/schemas/WhatsappMessageTemplateComponentParameterLimitedTimeOffer`
- Shape: `object`
- Description:
> Required if template uses offer expiration details.
- Properties:
- `expiration_time_ms`: `integer (int64)`
- Description:
> **Required.**
> Offer code expiration time as a UNIX timestamp in milliseconds.
- Constraints: example="1698562800000"
### `WhatsappMessageText`
- Reference: `#/components/schemas/WhatsappMessageText`
- Shape: `object`
- Description:
> WhatsApp Message Text Object.
- Required properties: `body`
- Properties:
- `body`: `string` (required)
- Description:
> 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.
- Constraints: maxLength=4096
- `preview_url`: `boolean`
- Description:
> 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`.
### `WhatsappMessageType`
- Reference: `#/components/schemas/WhatsappMessageType`
- Shape: `string`
- Description:
> WhatsApp outbound message type.
> See also [WhatsApp messages](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages).
- Constraints: enum=["template", "text", "image", "audio", "video", "document", "sticker", "location", "interactive", "contacts", "reaction"]
### `WhatsappPricingCategory`
- Reference: `#/components/schemas/WhatsappPricingCategory`
- Shape: `string`
- Description:
> WhatsApp pricing category.
> - `referral_conversion`: Indicates a [free entry point conversation](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations).
> - `authentication`: Indicates the conversation was billed at authentication rate.
> - `authentication_international`: Indicates the conversation was conversation was billed at the [authentication-international rate](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates).
> - `marketing`: Indicates the conversation was billed at authentication rate.
> - `marketing_lite`: Indicates the conversation was billed at marketing-lite rate.
> - `utility`: Indicates the conversation was billed at utility rate.
> - `service`: Indicates the conversation was billed at service rate.
>
> See also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing).
- Constraints: enum=["referral_conversion", "authentication", "authentication_international", "marketing", "marketing_lite", "utility", "service"]
### `WhatsappPricingModel`
- Reference: `#/components/schemas/WhatsappPricingModel`
- Shape: `string`
- Description:
> WhatsApp pricing model.
> - `PMP`: Per-message pricing applies.
> - `CBP`: Conversation-based pricing applies.
- Constraints: enum=["PMP", "CBP"]
### `WhatsappPricingType`
- Reference: `#/components/schemas/WhatsappPricingType`
- Shape: `string`
- Description:
> WhatsApp pricing type. This field is only available in PMP (Per-Message Pricing) mode.
> - `regular`: Indicates the message is billable.
> - `free_customer_service`: Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.
> - `free_entry_point`: Indicates the message is free because it is part of a free-entry point conversation.
- Constraints: enum=["regular", "free_customer_service", "free_entry_point"]
### `WhatsappProfile`
- Reference: `#/components/schemas/WhatsappProfile`
- Shape: `object`
- Description:
> Represents the profile of a WhatsApp account.
- Properties:
- `name`: `string`
- Description:
> Name of the WhatsApp account.
- Constraints: example="John"
- `username`: `string`
- Description:
> WhatsApp username.
- Constraints: example="john_doe"
## Codegen interpretation and unknowns
- `operationId` identifies the OpenAPI operation; it is not an SDK method name.
- `allOf` is wire-level schema composition. Response adapters must merge inherited and local properties; generated model inheritance/flattening is only a codegen shape, not additional API behavior.
- `x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are generator hints, not business rules.
- Description-only constraints (including conditional fields, precedence, and endpoint-specific behavior) remain verbatim above.
- This OpenAPI snapshot does not confirm cross-cutting error, retry/`Retry-After`, rate-limit, idempotency, delivery, or webhook-signature behavior. Consult the reviewed `runtime.md`; if neither source confirms a fact, do not fill it in.
SHA-256: 730ab367e417a546032d20b099095e13e49a498800c319537014f82a5073b259