> ## 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. # Submit a Direct Send message sample > Submits one representative message sample to Meta and returns its detected category. We recommend submitting 3–4 samples that cover your utility use cases, one per request. This request does not send a message to a recipient. Utility Direct Send is in public beta. You do not need to join an allowlist or apply for access. Use an API key for the YCloud account that manages the specified WhatsApp Business Account. Samples support text, an interactive CTA URL button, or interactive reply buttons. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send) for limits, sending examples, and template conversion. ## OpenAPI ````yaml /openapi/endpoints/ycloud-api-v2.yaml post /whatsapp/messages/{wabaId}/messageSamples openapi: 3.0.0 info: description: >- The [YCloud](https://ycloud.com) API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API is designed to have predictable, resource-oriented URLs, return [JSON](https://www.json.org) responses, and use standard HTTP response codes and verbs. version: v2 title: YCloud API termsOfService: https://ycloud.com/terms-service contact: email: service@ycloud.com servers: - url: https://api.ycloud.com/v2 description: Base URL security: - api_key: [] tags: - name: Balance - name: Contacts - name: Custom Events - name: Emails - name: SMS - name: Unsubscribers - name: Verify - name: Voices - name: Webhook Endpoints - name: WhatsApp Business Accounts - name: WhatsApp Inbound Messages - name: WhatsApp Media - name: WhatsApp Messages - name: WhatsApp Blocked Users - name: WhatsApp Groups - name: WhatsApp Calling - name: WhatsApp Phone Numbers - name: WhatsApp Templates - name: WhatsApp Flows - name: Meta Business Agent - name: WhatsApp Group Messages externalDocs: description: Homepage url: https://ycloud.com paths: /whatsapp/messages/{wabaId}/messageSamples: post: tags: - WhatsApp Messages summary: Submit a Direct Send message sample description: >- Submits one representative message sample to Meta and returns its detected category. We recommend submitting 3–4 samples that cover your utility use cases, one per request. This request does not send a message to a recipient. Utility Direct Send is in public beta. You do not need to join an allowlist or apply for access. Use an API key for the YCloud account that manages the specified WhatsApp Business Account. Samples support text, an interactive CTA URL button, or interactive reply buttons. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send) for limits, sending examples, and template conversion. operationId: whatsapp_message-submit-sample parameters: - $ref: '#/components/parameters/wabaId-in_path' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageSamplesRequest' examples: text: summary: Text sample value: type: text text: body: Your order ORDER-123 is ready for pickup. cta_url: summary: CTA URL button sample value: type: interactive interactive: type: cta_url header: type: text text: Order update body: text: >- Your order ORDER-123 has shipped. Track its delivery below. footer: text: Thank you for your order. action: name: cta_url parameters: display_text: Track order url: https://example.com/orders/ORDER-123 reply_buttons: summary: Reply button sample value: type: interactive interactive: type: button body: text: Your appointment is tomorrow at 10 AM. Please confirm. action: buttons: - type: reply reply: id: confirm_appointment title: Confirm responses: '200': description: >- The sample was processed. Check its detected category before sending utility content. content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageSamplesResponse' example: success: true category: UTILITY '400': description: >- Invalid sample or an error returned by Meta. Meta errors include `error.whatsappApiError`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The WhatsApp Business Account is not managed by your YCloud account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: wabaId-in_path: name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: whatsapp-business-account-id schemas: WhatsappMessageSamplesRequest: description: >- One representative Utility Direct Send sample. Supply the object matching `type`. Do not include `from`, `to`, or `category`. Text and interactive bodies support up to 1024 characters. Samples use text headers, with up to 60 characters in the header or footer. oneOf: - title: Text sample type: object required: - type - text properties: type: type: string enum: - text text: type: object required: - body properties: body: type: string minLength: 1 maxLength: 1024 description: >- Representative utility message content. URL previews are not supported. - title: Interactive sample type: object required: - type - interactive properties: type: type: string enum: - interactive interactive: description: >- Use one CTA URL button or up to three reply buttons. Button labels support up to 20 characters. allOf: - $ref: '#/components/schemas/WhatsappMessageInteractive' - type: object required: - body properties: type: type: string enum: - cta_url - button header: type: object required: - type - text properties: type: type: string enum: - text text: type: string maxLength: 60 WhatsappMessageSamplesResponse: type: object properties: success: type: boolean description: Whether Meta successfully processed the sample. example: true category: type: string description: >- The category Meta detected for the sample. Use utility content for Utility Direct Send. enum: - UTILITY - MARKETING - AUTHENTICATION example: UTILITY ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' description: >- Contains the error code and human-readable message for the API error. WhatsappMessageInteractive: type: object description: Use for `interactive` messages. required: - type - action properties: type: 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. - `request_contact_info`: Ask the WhatsApp user to share their contact information. - `flow`: Use for Flow Messages. - `carousel`: Use for media carousel message. enum: - button - list - cta_url - product - product_list - catalog_message - location_request_message - order_details - order_status - voice_call - request_contact_info - flow - carousel action: $ref: '#/components/schemas/WhatsappMessageInteractiveAction' body: $ref: '#/components/schemas/WhatsappMessageInteractiveBody' header: $ref: '#/components/schemas/WhatsappMessageInteractiveHeader' footer: $ref: '#/components/schemas/WhatsappMessageInteractiveFooter' allOf: - not: allOf: - properties: type: enum: - button - properties: action: not: required: - buttons - not: allOf: - properties: type: enum: - list - properties: action: not: allOf: - required: - button - sections - properties: sections: items: required: - rows - not: allOf: - properties: type: enum: - cta_url - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - cta_url parameters: required: - display_text - url - not: allOf: - properties: type: enum: - product - properties: action: not: required: - catalog_id - product_retailer_id - not: allOf: - properties: type: enum: - product_list - properties: action: not: allOf: - required: - catalog_id - sections - properties: sections: items: required: - product_items - not: allOf: - properties: type: enum: - catalog_message - properties: action: not: allOf: - required: - name - properties: name: enum: - catalog_message - not: allOf: - properties: type: enum: - location_request_message - properties: action: not: allOf: - required: - name - properties: name: enum: - send_location - not: allOf: - properties: type: enum: - flow - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - flow parameters: required: - flow_message_version - flow_cta not: allOf: - not: required: - flow_id - not: required: - flow_name - not: allOf: - properties: type: enum: - order_details - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - review_and_pay parameters: required: - reference_id - type - currency - total_amount - order - payment_settings allOf: - not: allOf: - properties: type: enum: - physical-goods - not: required: - beneficiaries - not: allOf: - properties: type: enum: - order_status - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - review_order parameters: required: - reference_id - order - not: allOf: - properties: type: enum: - voice_call - properties: action: not: allOf: - required: - name - properties: name: enum: - voice_call - not: allOf: - properties: type: enum: - request_contact_info - properties: action: not: allOf: - required: - name - properties: name: enum: - request_contact_info - not: allOf: - properties: type: enum: - carousel - properties: action: not: required: - cards - not: allOf: - properties: type: enum: - button - list - cta_url - product_list - catalog_message - location_request_message - order_details - order_status - voice_call - request_contact_info - flow - carousel - properties: body: not: required: - text - not: allOf: - properties: type: enum: - product_list - properties: header: not: allOf: - required: - type - text - properties: type: enum: - text Error: type: object required: - status - code properties: status: type: integer format: int32 pattern: '[45]\d{2}' 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. example: 404 code: type: string 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. example: NOT_FOUND message: type: 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. example: The requested resource does not exist. target: type: string description: The target of the error. example: '' docUrl: type: string description: A URL to more information about the error. example: '' requestId: type: 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. example: req_1KjtKI80IKoaJNa6n6p whatsappApiError: $ref: '#/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. metaBusinessAgentApiError: $ref: '#/components/schemas/MetaBusinessAgentApiError' description: >- Sanitized upstream details returned when a Meta Business Agent request fails. WhatsappMessageInteractiveAction: type: object description: >- **Required.** Action you want the user to perform after reading the `interactive` message. properties: buttons: type: array description: Required for Reply Buttons. You can have up to 3 buttons. minItems: 1 maxItems: 3 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionButton' button: type: 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. maxLength: 20 catalog_id: type: 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). product_retailer_id: type: string description: |- Required for Single Product Messages. Unique identifier of the product in a catalog. sections: type: array description: |- Required for List Messages and Multi-Product Messages. Array of section objects. Minimum of 1, maximum of 10. minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSection' name: type: string description: >- Action name. Required for Call-To-Action (CTA) buttons. - `cta_url`: Use for Call-To-Action (CTA) URL buttons. - `catalog_message`: Use for Catalog Messages. - `send_location`: Use for Location Request buttons. - `flow`: Use for Flow buttons. - `review_and_pay`: Use for Order Details buttons. - `review_order`: Use for Order Status buttons. - `voice_call`: Use for Voice Call buttons. - `request_contact_info`: Use for Request Contact Information buttons. enum: - cta_url - catalog_message - send_location - flow - review_and_pay - review_order - voice_call - request_contact_info parameters: $ref: '#/components/schemas/WhatsappMessageInteractiveActionParameters' cards: type: array description: |- Required for Carousel Messages. Array of card objects. Minimum of 2, maximum of 10. minItems: 2 maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCard' not: allOf: - not: required: - buttons - not: required: - button - sections - not: required: - catalog_id - product_retailer_id - not: required: - catalog_id - sections - not: required: - name - not: required: - cards WhatsappMessageInteractiveBody: type: object description: Optional for type `product`. Required for other message types. required: - text properties: text: type: string description: >- The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. maxLength: 1024 WhatsappMessageInteractiveHeader: type: object description: Required for type `product_list`. Optional for other types. required: - type properties: type: description: >- The media type for the interactive message header. Determines which media field should be populated (text, image, video, or document). type: string enum: - text - image - video - document text: type: string description: Text for the header. Formatting allows emojis, but not markdown. maxLength: 60 image: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' video: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' document: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' allOf: - not: allOf: - properties: type: enum: - text - not: required: - text - not: allOf: - properties: type: enum: - image - not: required: - image - not: allOf: - properties: type: enum: - video - not: required: - video - not: allOf: - properties: type: enum: - document - not: required: - document WhatsappMessageInteractiveFooter: type: object description: Optional. An object with the footer of the message. required: - text properties: text: type: string description: >- The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters. maxLength: 60 WhatsappApiError: type: 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: - message - code properties: message: type: string description: A human-readable description of the error. example: HSM Template creation failed code: type: string description: An error code. example: 200002 type: type: string description: Error type. example: OAuthException is_transient: type: boolean description: Whether the error is transient. example: false error_subcode: type: string description: Additional code about the error. example: 2388109 error_user_msg: type: string description: >- The message to display to the user. The language of the message is based on the locale of the API request. example: This message template cannot be created. error_user_title: type: string description: >- The title of the dialog, if shown. The language of the message is based on the locale of the API request. example: Message Cannot Be Submitted fbtrace_id: type: 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. example: AVGjJ7ia2zJkrHG error_data: 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. oneOf: - type: string - type: object additionalProperties: true MetaBusinessAgentApiError: type: object description: Sanitized details from a failed Meta Business Agent upstream request. properties: title: type: string detail: type: string type: type: string status: type: integer format: int32 requestId: type: string WhatsappMessageInteractiveActionButton: type: object description: A button object in `interactive` messages. required: - type - reply properties: type: description: >- The button type. Only `reply` is supported for interactive reply buttons. type: string enum: - reply reply: type: object required: - id - title properties: title: type: string description: >- 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. maxLength: 20 id: type: string description: >- 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. maxLength: 256 WhatsappMessageInteractiveActionSection: type: object description: WhatsApp Message Interactive Section Object. properties: title: type: string description: |- **Required if the message has more than one section.** Title of the section. Maximum length: 24 characters. maxLength: 24 rows: type: 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. maxItems: 10 minItems: 1 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSectionRow' product_items: type: 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. minItems: 1 maxItems: 30 items: $ref: >- #/components/schemas/WhatsappMessageInteractiveActionSectionProductItem WhatsappMessageInteractiveActionParameters: type: object description: |- Action parameters. Required for Call-To-Action (CTA) buttons. properties: display_text: type: string description: |- Text of the CTA URL button. Maximum length: 20 bytes. maxLength: 20 example: See Docs url: type: string description: URL of the CTA URL button. example: https://developers.facebook.com/docs/whatsapp thumbnail_product_retailer_id: type: 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. flow_message_version: type: string description: |- Use for `flow` buttons. Value must be "3". enum: - '3' flow_token: type: string description: >- Use for `flow` buttons. Flow token that is generated by the business to serve as an identifier. Defaults to `unused`. flow_id: type: string description: >- Conditionally required for `flow` buttons. Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter. flow_name: type: 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_cta: type: string description: >- Required for `flow` buttons. Text on the CTA button. For example: "Open flow!". Maximum length: 20 characters. maxLength: 20 example: Open flow! flow_action: type: string description: |- Use for `flow` buttons. Either `navigate` or `data_exchange`. Defaults to `navigate`. enum: - navigate - data_exchange example: navigate flow_action_payload: type: object description: >- Optional when `flow_action` is `navigate`. Use it to select an entry screen and provide initial screen data. If omitted, WhatsApp opens the Flow at its default entry screen. Omit this field for other actions. properties: screen: type: string description: >- The ID of the screen displayed first. It needs to be an **entry** screen. data: type: object description: Optional input data for the first screen of the Flow. reference_id: type: 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. type: 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`. enum: - digital-goods - physical-goods beneficiaries: type: array description: >- Required for `physical-goods` orders sent with `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: $ref: '#/components/schemas/WhatsappMessageOrderBeneficiary' currency: type: string description: |- Required for `review_and_pay` buttons. The currency for this order. Currently the only supported value is `INR`. enum: - INR total_amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: |- Required for `review_and_pay` buttons. The total amount for this order. order: $ref: '#/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: type: array description: |- Required for `review_and_pay` buttons. Payment settings for the order. items: $ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting' not: anyOf: - required: - flow_id - flow_name - allOf: - properties: flow_action: enum: - data_exchange - required: - flow_action - flow_action_payload WhatsappMessageInteractiveActionCard: type: object description: >- A card object in `interactive` messages. All cards must have the same structure. required: - card_index - type - header - action properties: card_index: type: integer minimum: 0 maximum: 9 description: Card index. Unique index for each card (0-9). type: description: >- The card type. Must be `cta_url` for carousel cards with call-to-action URL buttons. type: string enum: - cta_url header: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardHeader' body: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardBody' action: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardAction' WhatsappMessageInteractiveMedia: type: object description: >- Media used in an interactive message header. Requests must reference an HTTPS URL. Responses may include the uploaded WhatsApp media ID for compatibility. not: allOf: - not: required: - id - not: required: - link properties: id: type: string readOnly: true description: >- Uploaded WhatsApp media ID returned in message responses. This response-only field cannot be used to send an interactive message header. link: type: string format: uri pattern: ^https:// description: Publicly accessible HTTPS URL of the media resource. caption: type: string description: Optional media caption. filename: type: string description: Optional filename for document media. WhatsappMessageInteractiveActionSectionRow: type: object required: - id - title properties: id: type: string description: 'Unique row ID. Maximum length: 200 characters.' maxLength: 200 title: type: string description: 'Row title content. Maximum length: 24 characters.' maxLength: 24 description: type: string description: 'Row description content. Maximum length: 72 characters.' maxLength: 72 WhatsappMessageInteractiveActionSectionProductItem: type: object required: - product_retailer_id properties: product_retailer_id: type: string description: |- Required for Multi-Product Messages. Unique identifier of the product in a catalog. WhatsappMessageOrderBeneficiary: type: 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: - name - address_line1 - city - state - country - postal_code properties: name: type: string description: >- Name of the individual or business receiving the physical goods. Cannot exceed 200 characters. maxLength: 200 address_line1: type: string description: >- Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters. maxLength: 100 address_line2: type: string description: >- Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters. maxLength: 100 city: type: string description: Name of the city. state: type: string description: Name of the state. country: type: string description: |- Name of the country. Currently the only supported value is `India`. postal_code: type: string description: 6-digit zipcode of shipping address. minLength: 6 maxLength: 6 WhatsappMessageOrderAmount: type: object description: Represents the amount of an order. required: - offset - value properties: offset: type: integer format: int32 description: Must be `100` for `INR`. example: 100 value: type: integer format: int32 description: |- Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. example: 1234 description: type: string description: |- Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. maxLength: 60 discount_program_name: type: 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. maxLength: 60 WhatsappMessageOrderInfo: type: object description: Order info. properties: status: $ref: '#/components/schemas/WhatsappMessageOrderStatusEnum' type: 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. catalog_id: type: 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`. items: type: array description: Array of items in the order. items: $ref: '#/components/schemas/WhatsappMessageOrderItem' subtotal: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: >- The value **must be equal** to sum of `order.amount.value` * `order.amount.quantity`. tax: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The tax information for this order. shipping: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The shipping cost of the order. discount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The discount amount for this order. expiration: $ref: '#/components/schemas/WhatsappMessageOrderExpiration' description: type: string description: >- **Optional.** Text for sharing status related information. Could be useful while sending cancellation. Max character limit is 120 characters. maxLength: 120 WhatsappMessageOrderPaymentSetting: type: object description: Payment settings for the order. required: - type - payment_gateway properties: type: type: string description: Must be set to `payment_gateway`. example: payment_gateway payment_gateway: $ref: '#/components/schemas/WhatsappMessageOrderPaymentGateway' WhatsappMessageInteractiveActionCardHeader: type: object required: - type properties: type: description: >- The media type for the carousel card header. Must be either `image` or `video`. type: string enum: - image - video image: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' video: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' allOf: - not: allOf: - properties: type: enum: - image - not: required: - image - not: allOf: - properties: type: enum: - video - not: required: - video WhatsappMessageInteractiveActionCardBody: type: object description: Optional for card. required: - text properties: text: type: string description: Max 160 chars, and up to 2 line breaks. maxLength: 160 WhatsappMessageInteractiveActionCardAction: type: 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). allOf: - not: allOf: - not: required: - name - parameters - not: required: - buttons - not: allOf: - required: - name - parameters - required: - buttons properties: name: type: string description: Required when card action is url button. Must be "cta_url". enum: - cta_url parameters: $ref: >- #/components/schemas/WhatsappMessageInteractiveActionCardActionParameters buttons: type: array description: Required when card action is quick reply button. minItems: 1 items: $ref: >- #/components/schemas/WhatsappMessageInteractiveActionCardActionButton WhatsappMessageOrderStatusEnum: type: 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`. enum: - pending - processing - partially_shipped - shipped - completed - canceled WhatsappMessageOrderItem: type: object required: - name - amount - quantity properties: retailer_id: type: string description: Content ID for an item in the order from your catalog. name: type: string description: >- The item's name to be displayed to the user. Cannot exceed 60 characters. maxLength: 60 image: $ref: '#/components/schemas/WhatsappMessageMedia' description: Custom image for the item to be displayed to the user. amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The price per item. sale_amount: $ref: '#/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. quantity: type: integer format: int32 description: The number of items in the order. country_of_origin: type: string description: |- Required if `catalog_id` is not present. The country of origin of the product. importer_name: type: string description: |- Required if `catalog_id` is not present. Name of the importer company. importer_address: type: string description: |- Required if `catalog_id` is not present. Address of importer company. WhatsappMessageOrderExpiration: type: object description: Expiration for this order. required: - timestamp properties: timestamp: type: string description: >- A string of UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds. example: '1727438564' description: type: string description: Text explanation for expiration. maxLength: 120 WhatsappMessageOrderPaymentGateway: type: object description: An object that describes payment account information. required: - type - configuration_name properties: type: type: string 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. enum: - billdesk - razorpay - payu - zaakpay configuration_name: type: string 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. maxLength: 60 billdesk: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk payu: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayPayu razorpay: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay zaakpay: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay WhatsappMessageInteractiveActionCardActionParameters: type: object description: >- Required when card action is url button. Only support `display_text` and `url`. Button display text Max 20 chars. required: - display_text - url properties: display_text: type: string description: |- Text of the CTA URL button. Maximum length: 20 bytes. maxLength: 20 example: See Docs url: type: string description: URL of the CTA URL button. example: https://developers.facebook.com/docs/whatsapp WhatsappMessageInteractiveActionCardActionButton: type: object required: - type - quick_reply properties: type: description: >- The button type. Must be `quick_reply` for carousel card quick reply buttons. type: string enum: - quick_reply quick_reply: type: object required: - id - title properties: title: type: string description: >- 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. maxLength: 20 id: type: string description: >- Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 20 characters. You cannot have leading or trailing spaces when setting the ID. maxLength: 20 WhatsappMessageMedia: type: 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: id: type: 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. Do not provide both. link: type: 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. Do not provide both. caption: type: string description: >- Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages. filename: type: string description: >- Describes the filename for the specific document. Use only with `document` media. voice: type: boolean description: >- Whether to send an `audio` message as a WhatsApp voice message. Set to `true` for a voice message. Set to `false`, or omit this field, to send the audio as a regular attachment. This field applies only when the enclosing message `type` is `audio`. allOf: - not: allOf: - not: required: - id - not: required: - link - not: required: - id - link WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk: type: 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: type: string additional_info2: type: string additional_info3: type: string additional_info4: type: string additional_info5: type: string additional_info6: type: string additional_info7: type: string WhatsappMessageOrderPaymentSettingPaymentGatewayPayu: type: 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: type: string udf2: type: string udf3: type: string udf4: type: string WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay: type: object description: Additional info for Razorpay. properties: receipt: type: 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. notes: type: object additionalProperties: type: string description: >- The object can be key value pairs with maximum 15 keys and each value limits to 256 characters. WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay: type: 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: type: string extra2: type: string securitySchemes: api_key: type: apiKey name: X-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.