YCloud WhatsApp API MCP Server

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 externalDocs: description: Homepage url: 'https://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 Messages - name: WhatsApp Phone Numbers - name: WhatsApp Templates paths: /balance: get: summary: Retrieve balance description: Retrieves the current account balance. operationId: balance-retrieve tags: - Balance responses: 200: description: Successfully retrieved balance. content: application/json: schema: $ref: '#/components/schemas/Balance' /contact/contacts: post: summary: Create a contact tags: - Contacts operationId: contact-create description: Creates a contact. requestBody: content: application/json: schema: $ref: '#/components/schemas/ContactCreateRequest' required: true responses: 200: description: Successfully created a contact. content: application/json: schema: $ref: '#/components/schemas/Contact' get: summary: List contacts tags: - Contacts operationId: contact-list description: Returns a paginated list of contacts. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - name: filter.tags in: query description: Comma-separated list of tags. required: false schema: type: string example: tag1,tag2 - name: filter.countryCode in: query description: |- Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). required: false schema: type: string example: 'US' - name: filter.phoneNumber in: query description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. schema: type: string example: '+16315551111' required: false - name: filter.email in: query description: The contact's email address. schema: type: string example: 'support@example.com' required: false responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/ContactPage' /contact/contacts/{id}: get: summary: Retrieve a contact tags: - Contacts operationId: contact-retrieve description: Retrieves a contact. parameters: - $ref: '#/components/parameters/id-in_path_for_contact' responses: 200: description: Successfully retrieved the contact. content: application/json: schema: $ref: '#/components/schemas/Contact' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update a contact tags: - Contacts operationId: contact-update description: Updates a contact. parameters: - $ref: '#/components/parameters/id-in_path_for_contact' requestBody: content: application/json: schema: $ref: '#/components/schemas/ContactUpdateRequest' responses: 200: description: Successfully updated the contact. content: application/json: schema: $ref: '#/components/schemas/Contact' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete a contact tags: - Contacts operationId: contact-delete description: Deletes a contact. parameters: - $ref: '#/components/parameters/id-in_path_for_contact' responses: 200: description: Successfully deleted the contact. content: application/json: schema: $ref: '#/components/schemas/Contact' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /event/definitions: post: summary: Create an event definition operationId: custom_events-create-definition tags: - Custom Events description: Creates a custom event definition. requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinitionCreateRequest' required: true responses: 200: description: Successfully created an event definition. content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinition' /event/definitions/{name}: get: summary: Retrieve an event definition operationId: custom_events-retrieve-definition tags: - Custom Events description: |- Retrieves a custom event definition you previously created. parameters: - $ref: '#/components/parameters/name-in_path_for_custom_event' responses: 200: description: Successfully retrieved the event definition. content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinition' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update an event definition operationId: custom_events-update-definition tags: - Custom Events description: |- Updates an event definition's label and description. parameters: - $ref: '#/components/parameters/name-in_path_for_custom_event' requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinitionUpdateRequest' required: true responses: 200: description: Successfully updated the event definition. content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinition' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /event/definitions/{name}/properties: post: summary: Create an event property definition operationId: custom_events-create-property-definition tags: - Custom Events description: Defines a new property for the event definition. parameters: - $ref: '#/components/parameters/name-in_path_for_custom_event' requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinitionPropertyCreateRequest' required: true responses: 200: description: Successfully created an event property. content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinitionProperty' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /event/definitions/{name}/properties/{propertyName}: patch: summary: Update an event property definition operationId: custom_events_update-property-definition tags: - Custom Events description: |- Updates an event property definition's label and description. parameters: - $ref: '#/components/parameters/name-in_path_for_custom_event' - $ref: '#/components/parameters/name-in_path_for_custom_event_property' requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinitionPropertyUpdateRequest' required: true responses: 200: description: Successfully updated the event property definition. content: application/json: schema: $ref: '#/components/schemas/CustomEventDefinitionProperty' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete an event property definition operationId: custom_events_delete-property-definition tags: - Custom Events description: |- Deletes a property of the event definition. parameters: - $ref: '#/components/parameters/name-in_path_for_custom_event' - $ref: '#/components/parameters/name-in_path_for_custom_event_property' responses: 200: description: Successfully deleted the event property definition. 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /event/events: post: summary: Send an event operationId: custom_events-send-event tags: - Custom Events description: |- Sends an event. requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomEventSendRequest' required: true responses: 200: description: Successfully sent the event. /emails: post: summary: Send an email operationId: email-send tags: - Emails description: Sends an outbound email message. requestBody: content: application/json: schema: $ref: '#/components/schemas/EmailSendRequest' required: true responses: 200: description: The request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/Email' /sms: post: summary: Send an SMS description: Sends an outbound text message. operationId: sms-send tags: - SMS requestBody: content: application/json: schema: $ref: '#/components/schemas/SmsSendRequest' description: SMS request that needs to be sent. required: true responses: 200: description: The request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/Sms' get: summary: List SMS records tags: - SMS operationId: sms-list description: Returns a paginated list of SMS messages you've previously sent. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/filter_createTime_gte-default_1d' - $ref: '#/components/parameters/filter_createTime_lte' - $ref: '#/components/parameters/filter_id' responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/SmsPage' /unsubscribers: post: summary: Create an unsubscriber description: |- Creates an unsubscriber. An unsubscriber is a configuration item representing that customers opt out of receiving messages from your business. **A customer and a channel form a unique identifier for an unsubscriber.** operationId: unsubscriber-create tags: - Unsubscribers requestBody: content: application/json: schema: $ref: '#/components/schemas/UnsubscriberCreateRequest' required: true responses: 200: description: Successfully created an unsubscriber. content: application/json: schema: $ref: '#/components/schemas/Unsubscriber' get: summary: List unsubscribers description: Returns a paginated list of unsubscribers. operationId: unsubscriber-list tags: - Unsubscribers x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/pageAfter' - name: filter.customer in: query schema: type: string description: |- The customer who has opted out. example: '+16315551111' - name: filter.channel in: query schema: $ref: '#/components/schemas/UnsubscriberChannel' - name: filter.regionCode in: query schema: type: string description: |- Region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/UnsubscriberPage' /unsubscribers/{customer}: get: summary: List all unsubscribers by customer description: Returns all unsubscribers for the specified customer. operationId: unsubscriber-list-all-by-customer tags: - Unsubscribers parameters: - $ref: '#/components/parameters/customer-in_path_for_unsubscriber' responses: 200: description: Successfully retrieved the unsubscribers. content: application/json: schema: type: array items: $ref: '#/components/schemas/Unsubscriber' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /unsubscribers/{customer}/{channel}: get: summary: Retrieve an unsubscriber description: Retrieves the unsubscriber for the specified customer and channel. operationId: unsubscriber-retrieve-by-customer-and-channel tags: - Unsubscribers parameters: - $ref: '#/components/parameters/customer-in_path_for_unsubscriber' - $ref: '#/components/parameters/channel-in_path_for_unsubscriber' responses: 200: description: Successfully retrieved the unsubscribers. content: application/json: schema: $ref: '#/components/schemas/Unsubscriber' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete an unsubscriber description: Deletes the unsubscriber for the specified customer and channel. operationId: unsubscriber-delete-by-customer-and-channel tags: - Unsubscribers parameters: - $ref: '#/components/parameters/customer-in_path_for_unsubscriber' - $ref: '#/components/parameters/channel-in_path_for_unsubscriber' responses: 200: description: Successfully deleted the unsubscriber. content: application/json: schema: $ref: '#/components/schemas/Unsubscriber' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /verify/verifications: post: summary: Start a verification description: |- Starts a verification by sending an SMS, voice, or email message to the recipient. This verification is charged once the message is sent successfully. operationId: verification-send tags: - Verify requestBody: content: application/json: schema: $ref: '#/components/schemas/VerificationSendRequest' description: Verification request that needs to be sent. required: true responses: 200: description: The request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/Verification' /verify/verificationChecks: post: summary: Check a verification tags: - Verify operationId: verification-check description: |- Checks a verification with a phone number, an email address, or a verification ID. A `pending` verification status changes to `approved` once you receive a response with the `valid` parameter is `true`. An approved verification cannot be checked anymore. requestBody: content: application/json: schema: $ref: '#/components/schemas/VerificationCheckRequest' required: true responses: 200: description: Successfully processed the verification check. content: application/json: schema: $ref: '#/components/schemas/VerificationCheck' /voices: post: summary: Send a voice code description: Sends an outbound voice call verification code. operationId: voice-send tags: - Voices requestBody: content: application/json: schema: $ref: '#/components/schemas/VoiceSendRequest' description: Voice call request that needs to be sent. required: true responses: 200: description: The request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/Voice' get: summary: List voice records description: Returns a paginated list of voice calls you've previously sent. operationId: voice-list tags: - Voices x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/filter_createTime_gte-default_1d' - $ref: '#/components/parameters/filter_createTime_lte' - $ref: '#/components/parameters/filter_id' responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/VoicePage' /webhookEndpoints: post: summary: Create a webhook endpoint tags: - Webhook Endpoints operationId: webhook_endpoint-create description: Creates a webhook endpoint listening for specific events. requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreateRequest' required: true responses: 200: description: Successfully created a webhook endpoint. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' get: summary: List webhook endpoints tags: - Webhook Endpoints operationId: webhook_endpoint-list description: Returns a paginated list of webhook endpoints. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointPage' /webhookEndpoints/{id}: get: summary: Retrieve a webhook endpoint tags: - Webhook Endpoints operationId: webhook_endpoint-retrieve description: Retrieves the webhook endpoint with the given ID. parameters: - $ref: '#/components/parameters/id-in_path_for_webhook_endpoint' responses: 200: description: Successfully retrieved the webhook endpoint. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update a webhook endpoint tags: - Webhook Endpoints operationId: webhook_endpoint-update description: Updates a webhook endpoint, such as url, events, status. parameters: - $ref: '#/components/parameters/id-in_path_for_webhook_endpoint' requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointUpdateRequest' required: true responses: 200: description: Successfully updated the webhook endpoint. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete a webhook endpoint tags: - Webhook Endpoints operationId: webhook_endpoint-delete description: Deletes a webhook endpoint. parameters: - $ref: '#/components/parameters/id-in_path_for_webhook_endpoint' responses: 200: description: Successfully deleted the webhook endpoint. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /webhookEndpoints/{id}/rotateSecret: post: summary: Rotate a webhook endpoint secret tags: - Webhook Endpoints operationId: webhook_endpoint-rotate-secret description: Generates a new secret for a webhook endpoint. parameters: - $ref: '#/components/parameters/id-in_path_for_webhook_endpoint' responses: 200: description: Successfully rotated the webhook endpoint secret. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/businessAccounts: get: summary: List WABAs tags: - WhatsApp Business Accounts operationId: whatsapp_business_account-list description: Returns a paginated list of WhatsApp business accounts you've registered. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/filter_accountReviewStatus-WABA' responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/WhatsappBusinessAccountPage' /whatsapp/businessAccounts/{id}: get: summary: Retrieve a WABA tags: - WhatsApp Business Accounts operationId: whatsapp_business_account-retrieve description: Retrieves a WABA you've registered. parameters: - name: id in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' responses: 200: description: Successfully retrieved the WABA. content: application/json: schema: $ref: '#/components/schemas/WhatsappBusinessAccount' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/inboundMessages/{id}/markAsRead: post: summary: Mark message as read operationId: whatsapp_inbound_message-mark-as-read tags: - WhatsApp Inbound Messages description: |- When you receive an inbound message from webhooks, you can use this endpoint to mark the message as read. Messages marked as read display two blue check marks alongside their timestamp. Marking a message as read will also mark earlier messages in the conversation as read. parameters: - name: id in: path description: |- ID of the message. A wamid (i.e., the original message ID on WhatsApp's platform) is also acceptable. required: true schema: type: string example: 627c8640675de8fc689ab9d9 responses: 200: description: Successfully marked the message as read. 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/messages/sendDirectly: post: summary: Send a message directly operationId: whatsapp_message-send-directly tags: - WhatsApp Messages 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. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageSendRequest' required: true responses: 200: description: The request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappMessage' /whatsapp/messages: post: summary: Enqueue a message operationId: whatsapp_message-send tags: - WhatsApp Messages description: |- Enqueues an outbound WhatsApp message for sending. Queued messages will be submitted to the WhatsApp Business API asynchronously. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageSendRequest' required: true responses: 200: description: The request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappMessage' /whatsapp/messages/{id}: get: summary: Retrieve a message operationId: whatsapp_message-retrieve tags: - WhatsApp Messages description: Retrieves a WhatsApp message you've previously sent. parameters: - $ref: '#/components/parameters/id-in_path' responses: 200: description: Successfully retrieved the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappMessage' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/phoneNumbers: get: summary: List phone numbers operationId: whatsapp_phone_number-list tags: - WhatsApp Phone Numbers description: Returns a paginated list of WhatsApp business phone numbers you've registered. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/filter_wabaId' responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberPage' /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}: get: summary: Retrieve a phone number operationId: whatsapp_phone_number-retrieve tags: - WhatsApp Phone Numbers description: |- Retrieves a WhatsApp business phone number you've registered. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' - name: phoneNumber in: path description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. required: true schema: type: string example: '+16315551111' responses: 200: description: Successfully retrieved the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumber' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile: get: summary: Retrieve a phone number profile operationId: whatsapp_phone_number-retrieve-profile tags: - WhatsApp Phone Numbers description: |- Retrieves a WhatsApp business phone number's profile. Customers can view your business profile by clicking your business's name or number in a conversation thread. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' - name: phoneNumber in: path description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. required: true schema: type: string example: '+16315551111' responses: 200: description: Successfully retrieved the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberProfile' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update a phone number profile operationId: whatsapp_phone_number-update-profile tags: - WhatsApp Phone Numbers description: |- Updates a WhatsApp business phone number profile. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' - name: phoneNumber in: path description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. required: true schema: type: string example: '+16315551111' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberProfileUpdateRequest' required: true responses: 200: description: Successfully updated the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberProfile' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings: get: summary: Retrieve commerce settings operationId: whatsapp_phone_number-retrieve-commerce-settings tags: - WhatsApp Phone Numbers description: |- Retrieves a WhatsApp business phone number's commerce settings. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' - name: phoneNumber in: path description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. required: true schema: type: string example: '+16315551111' responses: 200: description: Successfully retrieved the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappCommerceSettings' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update commerce settings operationId: whatsapp_phone_number-update-commerce-settings tags: - WhatsApp Phone Numbers description: |- Updates a WhatsApp business phone number's commerce settings. Use this endpoint to enable or disable the shopping cart or the product catalog for a specific business phone number. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' - name: phoneNumber in: path description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. required: true schema: type: string example: '+16315551111' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappCommerceSettingsUpdateRequest' required: true responses: 200: description: Successfully updated the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappCommerceSettings' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register: post: summary: Register a phone number operationId: whatsapp_phone_number-register tags: - WhatsApp Phone Numbers description: |- Registers a WhatsApp business phone number. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' - name: phoneNumber in: path description: Phone number ID. required: true schema: type: string example: '1234567890123456' responses: 200: description: Successfully registered the phone number. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumber' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/templates: post: summary: Create a template operationId: whatsapp_template-create tags: - WhatsApp Templates description: Creates a WhatsApp template. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplateCreateRequest' required: true responses: 200: description: Successfully created a WhatsApp template. content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplate' get: summary: List templates operationId: whatsapp_template-list tags: - WhatsApp Templates description: Returns a paginated list of WhatsApp templates you've previously created. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/filter_wabaId' - name: filter.name in: query description: Name of the template. required: false schema: type: string maxLength: 512 pattern: '[a-z0-9]{1,512}' example: sample_whatsapp_template - name: filter.language in: query description: Language code of the template. See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. required: false schema: type: string example: en_US responses: 200: description: Successfully retrieved a paginated list of objects. content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplatePage' /whatsapp/templates/{wabaId}/{name}: delete: summary: Delete templates by name operationId: whatsapp_template-delete-by-name tags: - WhatsApp Templates description: |- Deletes WhatsApp templates by name. If that template name exists in multiple languages, all languages will be deleted. HTTP status `404` is returned if no templates are found for the specific name. parameters: - $ref: '#/components/parameters/wabaId-in_path' - name: name in: path description: Name of the template. required: true schema: type: string pattern: '[a-z0-9]{1,512}' minimum: 1 maximum: 512 example: sample_whatsapp_template responses: 200: description: Successfully deleted the template(s). content: application/json: schema: type: array items: $ref: '#/components/schemas/WhatsappTemplate' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/templates/{wabaId}/{name}/{language}: delete: summary: Delete a template operationId: whatsapp_template-delete-by-name-and-language tags: - WhatsApp Templates description: |- Deletes a WhatsApp template by name and language. parameters: - $ref: '#/components/parameters/wabaId-in_path' - name: name in: path description: Name of the template. required: true schema: type: string pattern: '[a-z0-9]{1,512}' minimum: 1 maximum: 512 example: sample_whatsapp_template - name: language in: path description: Language code of the template. See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. required: true schema: type: string example: en_US responses: 200: description: Successfully deleted the template. content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplate' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Edit a template operationId: whatsapp_template-edit-by-name-and-language tags: - WhatsApp Templates description: |- Edits a WhatsApp template by name and language. Editing a template replaces its old contents entirely, so include any components you wish to preserve as well as components you wish to update using the components parameter. parameters: - $ref: '#/components/parameters/wabaId-in_path' - name: name in: path description: Name of the template. required: true schema: type: string pattern: '[a-z0-9]{1,512}' minimum: 1 maximum: 512 example: sample_whatsapp_template - name: language in: path description: Language code of the template. See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. required: true schema: type: string example: en_US requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplateEditRequest' responses: 200: description: Successfully edited the template. content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplate' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: Retrieve a template operationId: whatsapp_template-retrieve-by-name-and-language tags: - WhatsApp Templates description: |- Retrieves a WhatsApp template by name and language. parameters: - $ref: '#/components/parameters/wabaId-in_path' - name: name in: path description: Name of the template. required: true schema: type: string pattern: '[a-z0-9]{1,512}' minimum: 1 maximum: 512 example: sample_whatsapp_template - name: language in: path description: Language code of the template. See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. required: true schema: type: string example: en_US responses: 200: description: Successfully retrieved the template. content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplate' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: api_key: type: apiKey name: X-API-Key in: header parameters: channel-in_path_for_unsubscriber: name: channel in: path required: true schema: $ref: '#/components/schemas/UnsubscriberChannel' customer-in_path_for_unsubscriber: name: customer in: path description: The customer who has opted out. required: true schema: type: string example: '+16315551111' filter_createTime_gte-default_1d: name: filter.createTime.gte in: query description: |- Return results where the `createTime` field is greater than or equal to this value. Default: One day ago from now. required: false schema: type: string format: date-time example: '2022-03-01T12:00:00.000Z' filter_createTime_lte: name: filter.createTime.lte in: query description: |- Return results where the `createTime` field is less than or equal to this value. required: false schema: type: string format: date-time example: '2022-03-31T12:00:00.000Z' filter_id: name: filter.id in: query description: Unique object ID on our side. Other filter parameters will be ignored if this parameter is present. required: false schema: type: string filter_wabaId: name: filter.wabaId in: query description: |- **Required if you have more than 100 WABAs.** WhatsApp Business Account ID. required: false schema: type: string example: 'whatsapp-business-account-id' filter_accountReviewStatus-WABA: name: filter.accountReviewStatus in: query description: WhatsApp Business Account review status. required: false schema: type: string example: 'APPROVED' id-in_path: name: id in: path description: ID of the object. required: true schema: type: string example: 627c8640675de8fc689ab9d9 id-in_path_for_webhook_endpoint: name: id in: path description: ID of the webhook endpoint. required: true schema: type: string example: wh627c8640675de8fc689ab9d9 id-in_path_for_contact: name: id in: path description: ID of the contact. required: true schema: type: string example: 1693364594105000026 maxLength: 255 includeTotal: name: includeTotal in: query description: Return results inside an object that contains the total result count or not. required: false schema: type: boolean default: false limit: name: limit in: query description: A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10. required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 10 page: name: page in: query description: Page number of the results to be returned, 1-based. required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 1 pageAfter: name: pageAfter in: query description: |- A cursor to fetch the next page in cursor pagination. For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list. required: false schema: type: string example: 'id:foo' wabaId-in_path: name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' name-in_path_for_custom_event: name: name in: path description: Name of the custom event. required: true schema: type: string example: 'unique_event_name' pattern: '[a-z0-9_]{1,50}' name-in_path_for_custom_event_property: name: propertyName in: path description: Name of the custom event property. required: true schema: type: string example: 'unique_property_name' pattern: '[a-z0-9_]{1,50}' schemas: Balance: type: object required: - amount - currency properties: amount: type: number format: double description: Balance of current account. example: 190.0765 currency: type: string description: |- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD Contact: type: object description: Represents a contact. required: - id properties: id: type: string description: Unique ID for the object. example: 1693364594105000026 maxLength: 255 nickname: type: string description: Contact's nickname. example: nickname countryCode: type: string description: |- Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' countryName: type: string description: Full country name. phoneNumber: type: string description: Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' email: type: string description: |- The contact's email address. If present, the email address must be unique. example: 'support@example.com' lastSeen: type: string format: date-time description: The time at which the contact last sent a message to your business, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' lastMessageToPhoneNumber: type: string description: |- The business phone number that the contact last sent a message to. example: '+16315551111' tags: type: array description: Contact's tags. maxItems: 50 items: type: string maxLength: 50 createTime: type: string format: date-time description: The time at which the contact was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' customAttributes: type: array description: Contact's custom attributes. items: $ref: '#/components/schemas/ContactCustomAttribute' ownerEmail: type: string description: |- The email address of the contact's owner. example: 'support@example.com' maxLength: 250 ContactCustomAttribute: type: object properties: name: type: string description: Name of the attribute that you've previously defined. value: type: object description: |- Value of the attribute. Its data type depends on the format of the attribute you defined: For Text, the `value` is a string with a maximum length of 250. For Array, the `value` is an array of strings with a maximum length of 250. For Number, the `value` is a signed decimal number. For Boolean, the `value` is either `true` or `false`. For Time, the `value` is a Unix timestamp in milliseconds. For Long Text, the `value` is a string with a maximum length of 5000. ContactCreateRequest: type: object description: Contains the properties of the contact to be created. required: - phoneNumber properties: nickname: type: string description: |- Contact's nickname. Maximum length: 250 characters. example: nickname maxLength: 250 phoneNumber: type: string description: Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' countryCode: type: string description: |- Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' email: type: string description: |- Contact's email address. If present, the email address must be unique. example: 'support@example.com' maxLength: 250 tags: type: array description: |- Contact's tags. Max items: 50. Max characters per tag: 50. maxItems: 50 items: type: string description: |- Tag. Maximum length: 50 characters. maxLength: 50 customAttributes: type: array description: Contact's custom attributes. items: $ref: '#/components/schemas/ContactCustomAttribute' ownerEmail: type: string description: |- The email address of the contact's owner. example: 'support@example.com' maxLength: 250 ContactPage: type: object description: Represents a given page of contacts. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing contact objects. type: array items: $ref: '#/components/schemas/Contact' ContactUpdateRequest: type: object description: Contains the properties of the contact to be updated. properties: nickname: type: string description: |- Contact's nickname. Maximum length: 250 characters. example: nickname maxLength: 250 phoneNumber: type: string description: Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' countryCode: type: string description: |- Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' email: type: string description: |- The contact's email address. If present, the email address must be unique. example: 'support@example.com' maxLength: 250 tags: type: array description: |- Contact's tags. Maximum items: 50. maxItems: 50 items: type: string description: |- Tag. Maximum length: 50 characters. maxLength: 50 customAttributes: type: array description: |- Contact's custom attributes. If present (i.e., not `null`), all previous attributes of this contact will be replaced. items: $ref: '#/components/schemas/ContactCustomAttribute' ownerEmail: type: string description: |- The email address of the contact's owner. example: 'support@example.com' maxLength: 250 CustomEventDefinition: type: object description: Represents a custom event definition. properties: name: type: string description: The name of the custom event definition. example: 'propertyName' label: type: string description: The label of the event definition, used for display purposes. maxLength: 50 example: 'Property Label' description: type: string description: The description of the event definition. example: 'Describes this property' objectType: type: string description: |- Type of the object that the event will be associated with. - `CONTACT`: Indicates that the object is a `contact`. enum: - CONTACT example: 'CONTACT' createTime: type: string format: date-time description: The time at which this object is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2024-08-22T00:00:00.000Z' properties: type: array description: The list of property definitions for the event definition. items: $ref: '#/components/schemas/CustomEventDefinitionProperty' CustomEventDefinitionCreateRequest: type: object description: Contains the properties of the custom event definition to be created. required: - name - label - objectType properties: name: type: string description: The unique name of the custom event. pattern: '^[a-z0-9_]{1,50}' example: 'unique_event_name' maxLength: 50 label: type: string description: The label of the custom event. example: 'My event label' description: type: string description: The description of the event. example: 'Describes this event' maxLength: 200 objectType: type: string description: |- Type of the object that the event will be associated with. - `CONTACT`: Indicates that the object is a `contact`. enum: - CONTACT example: CONTACT properties: type: array description: A list of property definitions for the event. items: $ref: '#/components/schemas/CustomEventDefinitionPropertyCreateRequest' CustomEventDefinitionProperty: type: object description: Represents a custom property of a custom event definition. properties: name: type: string description: The name of the custom property. example: 'propertyName' label: type: string description: The label of the property, used for display purposes. maxLength: 50 example: 'Property Label' description: type: string description: The description of the property. example: 'Describes this property' createTime: type: string format: date-time description: The time at which this object is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2024-08-22T00:00:00.000Z' type: type: string description: |- The data type of the property. - `STRING`: Indicates a property that receives plain text strings. - `NUMBER`: Indicates a property that receives numeric values with up to one decimal. - `TIMESTAMP`: Indicates a property that receives epoch millisecond. - `URL`: Indicates a property that receives URLs, formatted as strings starting with `http://` or `https://`. enum: - STRING - NUMBER - TIMESTAMP - URL CustomEventDefinitionPropertyCreateRequest: type: object description: Contains the properties of the custom event property definition to be created. required: - name - label - type properties: name: type: string description: The unique name of the custom property. pattern: '^[a-z][a-z0-9_]{1,50}$' maxLength: 50 example: 'unique_property_name' label: type: string description: The label of the property. maxLength: 50 example: 'Property Label' description: type: string description: The description of the property. example: 'Describes this property' type: type: string description: |- Type of the property. - `STRING`: Indicates a property that receives plain text strings. - `NUMBER`: Indicates a property that receives numeric values with up to one decimal. - `TIMESTAMP`: Indicates a property that receives epoch millisecond. - `URL`: Indicates a property that receives URLs, formatted as strings starting with `http://` or `https://`. enum: - STRING - NUMBER - TIMESTAMP - URL example: STRING CustomEventDefinitionPropertyUpdateRequest: type: object description: Contains the properties of the event property definition to be updated. properties: label: type: string description: The label of the event property definition. example: 'New label' description: type: string description: The description of the event property definition. example: 'Describes the event property' CustomEventDefinitionUpdateRequest: type: object description: Contains the properties of the custom event definition to be updated. properties: label: type: string description: The label of the event definition. example: 'New Label' description: type: string description: The description of the event definition. example: 'Describes the event definition' CustomEventSendRequest: type: object description: Contains the properties of the custom event data to be sent. required: - eventName properties: eventName: type: string description: |- Name of the event. One of the custom event names you previously defined. example: 'unique_event_name' occurTime: type: string format: date-time description: |- The time at which the event occurred, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`, if not provided, the current time will be used. example: '2022-06-01T12:00:00.000Z' objectId: type: string description: |- ID of the object that the event is associated with. For events defined with `objectType` as `CONTACT`, the `objectId` should be a `contact` ID. Alternatively, you can use the `contactPhoneNumber` field to specify the contact. contactPhoneNumber: type: string description: |- The phone number of the contact for events defined with `objectType` as `CONTACT`. properties: type: object description: The properties of the custom event. additionalProperties: type: object example: property1: 'value1' property2: 'value2' Email: type: object required: - id properties: id: type: string description: Unique ID for the object. minLength: 6 maxLength: 128 from: $ref: '#/components/schemas/Mailbox' description: The sender's email address. to: type: array description: The intended recipients' email addresses. items: $ref: '#/components/schemas/Mailbox' cc: type: array description: Recipients who will receive a copy of the email. items: $ref: '#/components/schemas/Mailbox' bcc: type: array description: Recipients who will receive a blind carbon copy of the email. items: $ref: '#/components/schemas/Mailbox' replyTo: type: array description: If this field exists, then the reply should go to the addresses indicated in that field and not to the address(es) indicated in the `from` field. items: $ref: '#/components/schemas/Mailbox' subject: type: string description: |- The email subject, which contains a short string identifying the topic of the message. maxLength: 255 summary: type: string description: |- This is a summary of your email. Max length: 70. example: This is a summary. maxLength: 70 contentType: $ref: '#/components/schemas/EmailContentType' externalId: type: 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. callbackUrl: type: string description: |- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-email createTime: type: string format: date-time description: The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' totalRecipients: type: integer format: int32 description: Total recipients of this message, including `to`, `cc` and `bcc`. example: 3 totalPrice: type: number format: double description: Total price of this message. example: 0.0085 currency: type: string description: |- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD EmailContentType: type: string description: The MIME type of the email content (`text/html` or `text/plain`). Be aware that We won't count click and open events for the type `text/plain`. enum: - text/html - text/plain x-enum-varnames: - TEXT_HTML - TEXT_PLAIN EmailDelivery: type: object description: Represents an email delivery report. required: - emailId - recipientAddress properties: emailId: type: string description: Unique ID for the related email you've previously sent. minLength: 6 maxLength: 128 recipientAddress: type: string description: A recipient's email address. example: tom@example.com status: type: string description: |- Delivery status of the email to the specific recipient address. - `sending`: The messaging request is accepted by our system. - `failed`: The message failed to be sent from our system. - `sent`: The message has been sent from our system. - `delivered`: Our system has received a delivery receipt indicating that message is delivered. - `undelivered`: Our system has received a delivery receipt indicating that message is not delivered. enum: - sending - failed - sent - delivered - undelivered example: failed errorCode: type: string description: Error code when the email is undeliverable. example: 402 errorMessage: type: string description: Error message when the email is undeliverable. example: Unsubscribes externalId: type: string description: The `externalId` you set when you sent the email. bizType: type: string description: |- This can be either empty or one of `email`, or `verify`. Defaults to `email`. - `email`: Indicates that the message is sent via the **Email** product. - `verify`: Indicates that the message is sent via the **Verify** product. example: 'email' verificationId: type: string description: |- The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID EmailSendRequest: type: object required: - from - to - subject - content properties: from: type: string description: |- - The sender's email. Its domain should be one that has been registered and activated in your account. - The sender's email address is required while the sender's name is optional. For example, both `support@example.com` and `Sender<support@example.com>` work. example: 'SupportTeam<support@example.com>' to: type: string description: |- - The intended recipients' email addresses. - Supports a comma-separated list of one or more addresses. Max items: 100. example: 'to1@example.com,Nick<to2@example.com>' subject: type: string description: |- The email subject, which contains a short string identifying the topic of the message. Max length: 255. maxLength: 255 content: type: string description: |- - The email body. Max size: 150 KB. - Variables in the form of `#var_1#` are supported, they should be used together with the `variables` parameter. Variable keys only support letters, digits, and the underline character (`_`). - You can use the [Test Templates](https://help.ycloud.com/en/articles/6006545) provided by YCloud for testing. example: |- This is a test message from #nick#. contentType: $ref: '#/components/schemas/EmailContentType' variables: type: array description: |- - The variable key-value pairs that will replace the variable placeholders in `content` for each recipient. Variable keys are those that are wrapped with `#` as placeholders (e.g., `#var_1#`) in `content`. The placeholders will be replaced by variable values when sending the email. - The size of the array must be the same as the number of recipients in `to`. Be aware that `cc` and `bcc` addresses are excluded, and they can not receive emails that contain variables. - This parameter's size will be calculated together with the parameter `content`. The whole size must not exceed 150 KB. items: type: object description: Variable key-value pair. additionalProperties: type: string cc: type: string description: Recipients who will receive a copy of the email. example: 'cc1@example.com,Nick<cc2@example.com>' bcc: type: string description: Recipients who will receive a blind carbon copy of the email. example: 'bcc1@example.com,Nick<bcc2@example.com>' replyTo: type: string description: If this field exists, then the reply should go to the addresses indicated in that field and not to the address(es) indicated in the `from` field. summary: type: string description: |- This is a summary of your email. Max length: 70. example: This is a summary. maxLength: 70 externalId: type: 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. callbackUrl: type: string description: |- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-email 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. Typically used for **Send a WhatsApp message directly** API. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' Event: type: object description: |- Represents a webhook event payload. Every event contains certain common properties: `id`, `type`, `apiVersion`, `createTime`. Each event may also contain some properties unique to the event. For example, `sms` is returned when `type` is `sms.message.updated`. required: - id - type - apiVersion - createTime properties: id: type: string description: Unique ID for the event. minLength: 6 maxLength: 128 type: $ref: '#/components/schemas/EventType' apiVersion: type: string description: The API version used to render this event. example: v2 createTime: type: string format: date-time description: The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' emailDelivery: $ref: '#/components/schemas/EmailDelivery' description: Included when `type` is `email.delivery.updated`. sms: $ref: '#/components/schemas/Sms' description: Included when `type` is `sms.message.updated`. smsInbound: $ref: '#/components/schemas/SmsInbound' description: Included when `type` is `sms.inbound.received`. voice: $ref: '#/components/schemas/Voice' description: Included when `type` is `voice.message.updated`. whatsappBusinessAccount: $ref: '#/components/schemas/WhatsappBusinessAccount' description: Included when `type` is `whatsapp.business_account.deleted`, `whatsapp.business_account.reviewed`, or `whatsapp.business_account.updated`. whatsappInboundMessage: $ref: '#/components/schemas/WhatsappInboundMessage' description: Included when `type` is `whatsapp.inbound_message.received`. whatsappMessage: $ref: '#/components/schemas/WhatsappMessage' description: Included when `type` is `whatsapp.message.updated`. whatsappPhoneNumber: $ref: '#/components/schemas/WhatsappPhoneNumber' description: Included when `type` is `whatsapp.phone_number.deleted`, `whatsapp.phone_number.name_updated`, or `whatsapp.phone_number.quality_updated`. whatsappPayment: $ref: '#/components/schemas/WhatsappPayment' description: Included when `type` is `whatsapp.payment.updated`. whatsappTemplate: $ref: '#/components/schemas/WhatsappTemplate' description: Included when `type` is `whatsapp.template.reviewed`, `whatsapp.template.quality_updated`, or `whatsapp.template.category_updated`. EventType: type: string description: Type of event. enum: - email.delivery.updated - sms.message.updated - sms.inbound.received - voice.message.updated - whatsapp.business_account.deleted - whatsapp.business_account.reviewed - whatsapp.business_account.updated - whatsapp.inbound_message.received - whatsapp.message.updated - whatsapp.phone_number.deleted - whatsapp.phone_number.name_updated - whatsapp.phone_number.quality_updated - whatsapp.template.category_updated - whatsapp.template.quality_updated - whatsapp.template.reviewed x-enum-descriptions: - Occurs when an email delivery status is updated, and the status changes to `delivered` or `failed`. - Occurs when an SMS message status is updated, and the status changes to `delivered` or `undelivered`. - Occurs when an SMS inbound message is received, which means a user replies to your message. - Occurs when a voice message status is updated, and the status changes to `delivered` or `undelivered`. - Occurs when a WhatsApp Business Account is deleted. - Occurs when a WhatsApp Business Account has been reviewed. - Occurs when a policy violation happened, WhatsApp Business Account has been banned and more. - Occurs when a WhatsApp inbound message is received. - Occurs when a WhatsApp outbound message status is updated, and the status changes to `sent`, `failed`, `delivered`, or `read`. - Occurs when a WhatsApp business phone number is deleted. - Occurs when a WhatsApp business phone number's name has been approved or rejected. - Occurs when a WhatsApp business phone number's quality-related status is updated, and the status changes to `GREEN`, `YELLOW`, or `RED`. - Occurs when a WhatsApp template category is updated. - Occurs when a WhatsApp template quality rating is updated. - Occurs when a WhatsApp template status is updated, and the status changes to `REJECTED`, `APPROVED`, `PAUSED`, `DISABLED`, or `IN_APPEAL`. Mailbox: type: object description: Represents a mailbox. properties: name: type: string description: Name of the mailbox. example: 'Support Team' address: type: string description: Address of the mailbox. example: team@example.com MetaBusinessAccountVerificationStatus: type: string description: Current status of business verification of Meta Business Account which owns this WhatsApp Business Account. enum: - expired - failed - ineligible - not_verified - pending - pending_need_more_info - pending_submission - rejected - revoked - verified Page: type: object description: Represents a given page of items. required: - offset - limit - length properties: offset: description: |- The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10. type: integer format: int32 minimum: 0 limit: description: A limit on the number of items to be returned, between 1 and 100, defaults to 10. type: integer format: int32 minimum: 1 length: description: The actual number of items in the page. type: integer format: int32 minimum: 0 total: description: The total number of items. This field is returned only when the request parameter `includeTotal` is set to `true`. type: integer format: int32 minimum: 0 items: type: array items: type: object PageCursor: type: object description: |- A cursor object is returned only if the endpoint you requested supports cursor pagination. properties: after: type: string description: |- A cursor to fetch the next page in cursor pagination. For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list. This field is returned only if there are more items in the list. example: 'id:foo' Sms: type: object required: - id - to properties: id: type: string description: Unique ID for the object. minLength: 6 maxLength: 128 to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' text: type: string description: The text of this message. example: Your verification code is 123456. senderId: type: string description: Sender ID to be used. example: Brand regionCode: type: string description: |- [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) example: 'US' totalSegments: type: integer format: int32 minimum: 1 description: Number of message segments. See [SMS character encoding](https://help.ycloud.com/en/articles/3083427-sms-character-encoding) for more info. example: 1 totalPrice: type: number format: double description: Total price of this message. example: 0.0085 currency: type: string description: |- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD status: type: string description: |- Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`. - `accepted`: The messaging request is accepted by our system. - `failed`: The message failed to be sent from our system. - `sent`: The message has been sent from our system. - `delivered`: Our system has received a delivery receipt indicating that message is delivered. - `undelivered`: Our system has received a delivery receipt indicating that message is not delivered. example: sent enum: - accepted - failed - sent - delivered - undelivered errorCode: type: string description: Error code when the message is undeliverable. createTime: type: string format: date-time description: The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' updateTime: type: string format: date-time description: The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' externalId: type: 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. callbackUrl: type: string description: |- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-sms bizType: type: string description: |- This can be either empty or one of `sms`, or `verify`. Defaults to `sms`. - `sms`: Indicates that the message is sent via the **SMS** product. - `verify`: Indicates that the message is sent via the **Verify** product. example: 'sms' verificationId: type: string description: |- The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID SmsInbound: type: object description: Represents an inbound SMS message, which means a user replies to your message. properties: id: type: string description: Unique ID of the message. from: type: string description: The user's phone number who sent the message to your registered sender ID, formatted in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' to: type: string description: The receiver's phone number, which is one of your registered Sender IDs. text: type: string description: The text of this message. sendTime: type: string format: date-time description: The time at which this message was sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' SmsPage: type: object description: Represents a given page of SMS messages. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing SMS objects. type: array items: $ref: '#/components/schemas/Sms' UnsubscriberPage: type: object description: Represents a given page of unsubscriber objects. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing unsubscriber objects. type: array items: $ref: '#/components/schemas/Unsubscriber' cursor: $ref: '#/components/schemas/PageCursor' Verification: type: object required: - id properties: id: type: string description: ID of the verification. example: ve6j7n8i status: $ref: '#/components/schemas/VerificationStatus' to: type: string description: Recipient of the verification. example: '+16315551111' channel: $ref: '#/components/schemas/VerificationChannel' sendTime: type: string format: date-time description: The time at which this verification was sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' totalPrice: type: number format: double description: |- Total price of this verification. example: 0.0085 currency: type: string description: |- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD smsFallbackEnabled: type: boolean description: |- Whether sms fallback is enabled or not. Applicable when `channel` is `whatsapp`. If enabled, we will try to send the verification code via sms when the WhatsApp message is failed. smsFallback: $ref: '#/components/schemas/VerificationFallback' description: Included when `smsFallbackEnabled` is `true`. externalId: type: 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. VerificationChannel: type: string description: |- Supports several independent channels for verification: - `sms`: Sends an SMS message with a verification code. - `voice`: Makes a voice call with a verification code. - `email_code`: Sends an email with a verification code. - `whatsapp`: Sends a WhatsApp message with a verification code. enum: - sms - voice - email_code - whatsapp example: sms VerificationCheck: type: object required: - id - valid properties: id: type: string description: ID of this verification check. example: vc8f92c20 valid: type: boolean description: Whether the verification code is valid for this check. example: false status: $ref: '#/components/schemas/VerificationStatus' to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format or email address. example: '+16315551111' channel: $ref: '#/components/schemas/VerificationChannel' VerificationCheckRequest: type: object properties: verificationId: type: string description: ID of the verification to be checked. One of `verificationId` or `to` is required. example: vid to: type: string description: The recipient's phone number or email address. One of `verificationId` or `to` is required. example: '+16315551111' code: type: string description: The verification to be checked. example: '123456' VerificationFallback: type: object description: Contains information about verification fallback. For example, you can enable sms fallback for WhatsApp verification messages. properties: supported: type: boolean description: Whether this fallback you requested is supported. If `false` is returned, it means that there are errors for this fallback, and this fallback will not be triggered. unsupportedReason: type: string description: The reason why the fallback is unsupported, e.g, `PARAM_INVALID`, `SMS_SIGNATURE_UNAVAILABLE`, `SENDER_ID_UNAVAILABLE`, or `MESSAGING_REGION_UNSUPPORTED`. example: SENDER_ID_UNAVAILABLE unsupportedDetail: type: string description: The detail message why the fallback is unsupported. example: This Sender ID is not registered. VerificationSendRequest: type: object required: - channel - to properties: channel: $ref: '#/components/schemas/VerificationChannel' to: type: string description: |- The recipient's phone number or email address depending on `channel`. - Phone number: In [E.164](https://en.wikipedia.org/wiki/E.164) format. Applicable when `channel` is `sms` or `voice`. - Email address: For example, `tom@example.com`. Applicable when `channel` is `email_code`. example: '+16315551111' code: type: string description: Verification code to be sent. This field is optional. If not provided, we will automatically generate a code. maxLength: 8 minLength: 4 example: '123456' senderId: type: string description: |- [Sender ID](https://help.ycloud.com/en/articles/3080386) to be used. example: Brand signature: type: string description: This parameter is only required for Chinese mainland SMS messages. You must specify an approved signature such as `Brand`. It will be added to the beginning of SMS body and wrapped with `【】`, e.g. `【Brand】Your verification code is 123456`. example: Brand language: type: string description: |- [ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). If not specified, language will be set as `en` by default. Notably, in certain countries or regions, language will be automatically set as the local language due to the regional restrictions. Applicable languages: `ar`: Arabic `de`: German `en`: English `es`: Spanish `fr`: French `id`: Indonesian `it`: Italian `pt_BR`: Portuguese `ru`: Russian `tr`: Turkish `vi`: Vietnamese `zh_CN`: Simplified Chinese `zh_HK`: Traditional Chinese example: en externalId: type: 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. If present, this value will also be attached to the `externalId` of message objects. VerificationStatus: type: string description: |- Status of the verification. - `pending`: The verification message (SMS, Voice, etc.) is sent, waiting to be checked. This happens when you call the 'Start a verification' API successfully. - `approved`: The verification has been successfully checked. A `pending` verification status changes to `approved` when you call the 'Check a verification' API and receive a response with the `valid` parameter is `true`. An approved verification cannot be checked anymore. - `blocked`: The verification is blocked by user-defined rules such as denylist, and geographical permission restrictions. A blocked verification cannot be checked. - `expired`: The verification has expired and cannot be checked anymore. - `undelivered`: Our system has received a delivery receipt indicating that the verification message was not delivered. An undelivered verification cannot be checked anymore. enum: - pending - approved - blocked - expired - undelivered SmsSendRequest: type: object required: - to - text properties: to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' text: type: string description: The text of this message. example: Your verification code is 123456. senderId: type: string description: |- [Sender ID](https://help.ycloud.com/en/articles/3080386) to be used. example: Brand signature: type: string description: This parameter is only required for Chinese mainland SMS messages. You must specify an approved signature such as `Brand`. It will be added to the beginning of SMS body and wrapped with `【】`, e.g. `【Brand】Your verification code is 123456`. example: Brand externalId: type: 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. callbackUrl: type: string description: |- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-sms Unsubscriber: type: object description: |- An unsubscriber is a configuration item representing that customers opt out of receiving messages from your business. **A customer and a channel form a unique identifier for an unsubscriber.** properties: type: $ref: '#/components/schemas/UnsubscriberType' customer: type: string description: |- The customer who has opted out. For `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' channel: $ref: '#/components/schemas/UnsubscriberChannel' regionCode: type: string description: |- The customer's region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' createTime: type: string format: date-time description: The time at which this object was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' UnsubscriberCreateRequest: type: object required: - type - customer - channel properties: type: $ref: '#/components/schemas/UnsubscriberType' customer: type: string description: |- The customer who has opted out. For `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' channel: $ref: '#/components/schemas/UnsubscriberChannel' regionCode: type: string description: |- The customer's region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' UnsubscriberChannel: type: string description: |- Channel of unsubscriber. - `whatsapp`: Indicates that the customer opts out of receiving WhatsApp messages from your business. enum: - whatsapp UnsubscriberType: type: string description: |- Type of unsubscriber. - `PHONE_NUMBER`: Indicates that the `customer` is a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. enum: - PHONE_NUMBER Voice: type: object required: - id - to properties: id: type: string description: Unique ID for the object. minLength: 6 maxLength: 128 to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' verificationCode: type: string description: The verification code to be sent, 4 to 6 digits. example: '123456' language: type: string description: |- [ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). example: 'en' regionCode: type: string description: |- [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' totalSegments: type: integer format: int32 minimum: 1 description: Number of message segments. It's always 1 for voice calls. example: 1 totalPrice: type: number format: double description: Total price of this message. example: 0.05 currency: type: string description: |- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD status: type: string description: |- Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`. - `accepted`: The messaging request is accepted by our system. - `failed`: The message failed to be sent from our system. - `sent`: The message has been sent from our system. - `delivered`: Our system has received a delivery receipt indicating that message is delivered. - `undelivered`: Our system has received a delivery receipt indicating that message is not delivered. example: sent enum: - accepted - failed - sent - delivered - undelivered errorCode: type: string description: Error code when the message is undeliverable. createTime: type: string format: date-time description: The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' updateTime: type: string format: date-time description: The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' externalId: type: 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. callbackUrl: type: string description: |- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-voice bizType: type: string description: |- This can be either empty or one of `voice`, or `verify`. Defaults to `voice`. - `voice`: Indicates that the message is sent via the **Voice** product. - `verify`: Indicates that the message is sent via **Verify** product. example: 'voice' verificationId: type: string description: |- The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID VoicePage: type: object description: Represents a given page of Voice Calls. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing Voice objects. type: array items: $ref: '#/components/schemas/Voice' VoiceSendRequest: type: object required: - to - verificationCode properties: to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' verificationCode: type: string description: The verification code to be sent, 4 to 6 digits. example: '123456' language: type: string description: |- [ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). If not specified, language will be set as `en` by default. Notably, in certain countries or regions, language will be automatically set as the local language due to the regional restrictions. Applicable languages: `ar`: Arabic `de`: German `en`: English `es`: Spanish `fr`: French `id`: Indonesian `it`: Italian `pt`: Portuguese `ru`: Russian `tr`: Turkish `vi`: Vietnamese `zh`: Chinese example: en externalId: type: 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. callbackUrl: type: string description: |- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-voice WebhookEndpoint: type: object required: - id properties: id: type: string description: Unique ID for the object. example: wh627c8640675de8fc689ab9d9 url: type: string description: The URL of the webhook endpoint. example: https://httpbin.org/anything?tag=api enabledEvents: type: array description: The list of events to enable for this endpoint. example: [ "whatsapp.message.updated", "whatsapp.inbound_message.received" ] items: type: string description: type: string description: An optional description of what the webhook is used for. example: My first webhook endpoint. status: $ref: '#/components/schemas/WebhookEndpointStatus' secret: type: string description: The endpoint's secret, used to generate webhook signatures. example: whsec_abc4147651944f02baf3be1eb45d33f1 createTime: type: string format: date-time description: The time at which this object was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' updateTime: type: string format: date-time description: The time at which this object was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' WebhookEndpointCreateRequest: type: object required: - url - enabledEvents properties: url: type: string description: The URL of the webhook endpoint. maxLength: 500 example: https://httpbin.org/anything?tag=api enabledEvents: type: array description: The list of events to enable for this endpoint. items: $ref: '#/components/schemas/EventType' description: type: string description: An optional description of what the webhook is used for. maxLength: 400 example: My first webhook endpoint. status: $ref: '#/components/schemas/WebhookEndpointStatus' WebhookEndpointPage: type: object description: Represents a given page of webhook endpoints. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing webhook endpoint objects. type: array items: $ref: '#/components/schemas/WebhookEndpoint' WebhookEndpointStatus: type: string description: |- Webhook endpoint status. - `active`: Indicates that the webhook endpoint is active, and will receive notifications of events monitored. - `disabled`: Indicates that the webhook endpoint is disabled, and will not receive notifications. - `pending`: Indicates that the webhook endpoint is pending, and will not receive notifications. If a webhook endpoint fails to receive notifications frequently, it changes to pending. enum: - active - disabled - pending WebhookEndpointUpdateRequest: type: object properties: url: type: string description: The URL of the webhook endpoint. maxLength: 500 example: https://httpbin.org/anything?tag=api enabledEvents: type: array description: The list of events to enable for this endpoint. items: $ref: '#/components/schemas/EventType' description: type: string description: An optional description of what the webhook is used for. maxLength: 400 example: My first webhook endpoint. status: $ref: '#/components/schemas/WebhookEndpointStatus' 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 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: type: 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. WhatsappAuthIntlRateEligibilityCountry: type: object description: |- Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries: - June 1, 2024 – Indonesia (country calling code +62, country code `ID`) - July 1, 2024 – India (country calling code +91, country code `IN`) See also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). properties: countryCode: type: string description: |- [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'IN' startTime: type: string format: date-time description: Date when newly-opened authentication conversations are subject to authentication-international rates, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2024-07-01T00:00:00.000Z`. example: '2024-07-01T00:00:00.000Z' WhatsappBusinessAccount: type: object description: |- Represents a specific [WhatsApp Business Account (WABA)](https://developers.facebook.com/docs/whatsapp/overview/business-accounts). properties: id: type: string description: WhatApp Business Account ID. name: type: string description: User-friendly name to differentiate WhatsApp Business Accounts. currency: type: string description: The currency in which the payment transactions for the WhatsApp Business Account will be processed. messageTemplateNamespace: type: string description: Namespace string for the message templates that belong to the WhatsApp Business Account. accountReviewStatus: $ref: '#/components/schemas/WhatsappBusinessAccountReviewStatus' businessVerificationStatus: $ref: '#/components/schemas/MetaBusinessAccountVerificationStatus' country: type: string description: Country of the WhatsApp Business Account's owning Meta Business account. ownershipType: type: string description: Ownership type of the WhatsApp Business Account. paymentMethodAttached: type: boolean description: Whether we have attached a payment method to the WhatsApp Business Account. primaryFundingId: type: string description: Primary funding ID for the WhatsApp Business Account paid service. purchaseOrderNumber: type: string description: The purchase order number supplied by the business for payment management purposes. timezoneId: type: string description: The timezone ID of the WhatsApp Business Account. See [Timezone IDs](https://developers.facebook.com/docs/marketing-api/reference/ad-account/timezone-ids). example: '1' decision: $ref: '#/components/schemas/WhatsappReviewDecision' description: Review decision made on this WhatsApp Business Account. One of `APPROVED` or `REJECTED`. updateEvent: $ref: '#/components/schemas/WhatsappBusinessAccountUpdateEventEnum' banState: $ref: '#/components/schemas/WhatsappBusinessAccountBanState' banDate: type: string description: The date when the WABA is banned. example: 'December 9, 2022' violationType: type: string description: |- Used to report violations imposed on the WABA. See also [WhatsApp Business Platform Policy Violations](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/violations). example: SCAM restrictions: type: array description: Used to report restrictions imposed on the WABA, when that WABA violates [WhatsApp Business Platform policies](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement). items: $ref: '#/components/schemas/WhatsappBusinessAccountRestrictionInfo' authIntlRateEligibilityCountries: type: array description: |- Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries: - June 1, 2024 – Indonesia (country calling code +62, country code `ID`) - July 1, 2024 – India (country calling code +91, country code `IN`) See also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). items: $ref: '#/components/schemas/WhatsappAuthIntlRateEligibilityCountry' primaryBusinessLocation: type: string description: |- Your primary business location is the country where your business is based. It will appear in the Business Manager under the Primary Business Location field starting May 1, 2024. [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: 'US' WhatsappBusinessAccountBanState: type: string description: The ban state of the WhatsApp Business Account. enum: - SCHEDULE_FOR_DISABLE - DISABLE - REINSTATE WhatsappBusinessAccountPage: type: object description: Represents a given page of WhatsApp Business Accounts. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing WhatsApp Business Account objects. type: array items: $ref: '#/components/schemas/WhatsappBusinessAccount' WhatsappBusinessAccountRestrictionInfo: type: object description: |- Used to report restrictions imposed on a specific WABA, when that WABA violates [WhatsApp Business Platform policies](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement). properties: restrictionType: type: string description: Restriction type. enum: - RESTRICTED_ADD_PHONE_NUMBER_ACTION - RESTRICTED_BIZ_INITIATED_MESSAGING - RESTRICTED_CUSTOMER_INITIATED_MESSAGING expiration: type: string format: date-time description: The time at which this restriction expires, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' WhatsappBusinessAccountReviewStatus: type: string description: WhatsApp Business Account review status. enum: - PENDING - APPROVED - REJECTED WhatsappBusinessAccountUpdateEventEnum: type: string description: |- Indicates the update event type of the WABA when a notification is sent to you to report a [policy violation](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement), a WABA has been banned and more. - `DISABLED_UPDATE`: WhatsApp Business Account Banned. - `ACCOUNT_RESTRICTION`: WhatsApp Business Account Restricted Due To Policy Violations. - `ACCOUNT_VIOLATION`: WhatsApp Business Account Violates Policy. - `AUTH_INTL_PRICE_ELIGIBILITY_UPDATE`: WhatsApp Business Account is eligible for the [authentication-international rate](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). - `BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE`: Business's [primary business location](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#primary-business-location) is set. enum: - DISABLED_UPDATE - ACCOUNT_RESTRICTION - ACCOUNT_VIOLATION - AUTH_INTL_PRICE_ELIGIBILITY_UPDATE - BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE WhatsappCommerceSettings: type: object description: WhatsApp business phone number's commerce settings. properties: id: type: string description: Unique ID for the object. isCartEnabled: type: boolean description: |- When enabled, cart-related buttons appear in the conversation, catalog, and product details views. When the cart is disabled, customers can see products and their details, but all cart related buttons will not appear in any view. isCatalogVisible: type: boolean description: |- When enabled, the catalog storefront icon and catalog-related buttons appear in conversation and business profile views. When the catalog is disabled, the storefront icon and catalog-related buttons will not appear in any views and the catalog preview with thumbnails will not appear in the business profile view. WhatsappCommerceSettingsUpdateRequest: type: object properties: isCartEnabled: type: boolean description: |- When enabled, cart-related buttons appear in the conversation, catalog, and product details views. When the cart is disabled, customers can see products and their details, but all cart related buttons will not appear in any view. isCatalogVisible: type: boolean description: |- When enabled, the catalog storefront icon and catalog-related buttons appear in conversation and business profile views. When the catalog is disabled, the storefront icon and catalog-related buttons will not appear in any views and the catalog preview with thumbnails will not appear in the business profile view. WhatsappConversation: type: 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: id: type: string description: Unique ID for the object. type: $ref: '#/components/schemas/WhatsappConversationType' originType: $ref: '#/components/schemas/WhatsappConversationOriginType' expireTime: type: string format: 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`. example: '2022-06-01T12:00:00.000Z' WhatsappConversationOriginType: type: 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). enum: - referral_conversion - authentication - marketing - utility - service WhatsappConversationType: type: 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. enum: - FREE_ENTRY - FREE_TIER - REGULAR WhatsappInboundMessage: type: object description: WhatsApp inbound message object. required: - id properties: id: type: string description: Unique ID for the object. wamid: type: string description: The original message ID on WhatsApp's platform. example: 'wamid.BgNODYxN...' wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' from: type: string description: The customer's phone number who sent the message to the business, formatted in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: The customer's profile information. to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' sendTime: type: string format: date-time description: The time at which this message is sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' type: $ref: '#/components/schemas/WhatsappInboundMessageType' text: $ref: '#/components/schemas/WhatsappInboundMessageText' image: $ref: '#/components/schemas/WhatsappInboundMessageMedia' video: $ref: '#/components/schemas/WhatsappInboundMessageMedia' audio: $ref: '#/components/schemas/WhatsappInboundMessageMedia' document: $ref: '#/components/schemas/WhatsappInboundMessageMedia' sticker: $ref: '#/components/schemas/WhatsappInboundMessageMedia' interactive: $ref: '#/components/schemas/WhatsappInboundMessageInteractive' location: $ref: '#/components/schemas/WhatsappInboundMessageLocation' button: $ref: '#/components/schemas/WhatsappInboundMessageButton' contacts: type: array items: $ref: '#/components/schemas/WhatsappMessageContact' reaction: $ref: '#/components/schemas/WhatsappMessageReaction' order: $ref: '#/components/schemas/WhatsappInboundMessageOrder' system: $ref: '#/components/schemas/WhatsappInboundMessageSystem' errors: type: array items: $ref: '#/components/schemas/WhatsappInboundMessageError' context: $ref: '#/components/schemas/WhatsappInboundMessageContext' referral: $ref: '#/components/schemas/WhatsappInboundMessageReferral' WhatsappInboundMessageButton: type: object description: |- When the message type field is set to `button`, this object is included in the message object. properties: payload: type: string description: The payload for a button set up by the business that a customer clicked as part of an interactive message. text: type: string description: Button text. WhatsappInboundMessageContext: type: object description: |- Message context. properties: forwarded: type: boolean description: |- **Added to Webhooks if message was forwarded.** Set to `true` if the received message has been forwarded. frequently_forwarded: type: boolean description: |- **Added to Webhooks if message has been frequently forwarded.** Set to `true` if the received message has been forwarded more than five times. from: type: string description: |- **Added to Webhooks if message is an inbound reply to a sent message.** The WhatsApp ID (a phone number without the '+' prefix) of the sender of the sent message. id: type: string description: |- **Optional.** The `wamid` for the sent message for an inbound reply. `wamid` is the original message ID on WhatsApp’s platform. example: 'wamid.BgNODYxN...' referred_product: $ref: '#/components/schemas/WhatsappInboundMessageReferredProduct' description: |- **Required for Product Inquiry Messages.** Specifies the product the user is requesting information about. See also [Sell Products & Services](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services). WhatsappInboundMessageError: type: object description: |- When the message type `unsupported`, this object is included. properties: code: type: string description: The error code. example: 131051 title: type: string description: The error title. example: Message type unknown message: type: string description: The error message. example: Message type unknown error_data: type: object description: |- An error data object with the following properties: - `details`: A string describing the reason for the error. Example: `Message type is currently not supported.`. WhatsappInboundMessageInteractive: type: object description: |- When a customer has interacted with your message, this object is included in the message object. properties: type: type: string description: |- The type of interactive message received. - `button_reply`: Sent when a customer clicks a button. - `list_reply`: Sent when a customer selects an item from a list. enum: - button_reply - list_reply button_reply: type: object description: Sent when a customer clicks a button. Returned when `type` is `button_reply`. properties: id: type: string description: Unique ID of the clicked button. title: type: string description: Title of a button. list_reply: type: object description: Sent when a customer selects an item from a list. Returned when `type` is `list_reply`. properties: id: type: string description: Unique ID of the selected list item. title: type: string description: Title of the selected list item. description: type: string description: Description of the selected row. WhatsappInboundMessageLocation: type: object description: |- When you receive a notification of a user's static location, the location object provides the details of the location. properties: latitude: type: number format: double description: Latitude of location being sent. longitude: type: number format: double description: Longitude of location being sent. address: type: string description: Address of the location. name: type: string description: Name of the location. url: type: string description: URL for the website where the user downloaded the location information. WhatsappInboundMessageMedia: type: object description: |- When a message with media (`image` | `document` | `audio` | `video` | `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. properties: id: type: string description: ID of the media. Can be used to delete the media if stored locally on the client. link: type: string description: |- The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. caption: type: string description: The provided caption for the media. Only present if specified. filename: type: string description: Filename on the sender's device. This will only be present in `document` media messages. metadata: type: object additionalProperties: type: object description: Metadata pertaining to `sticker` media. mime_type: type: string description: Mime type of the media. sha256: type: string description: Checksum. WhatsappInboundMessageOrder: type: object description: |- When a customer places an order, the message type is set to `order`, and this field is included. properties: catalog_id: type: string description: The catalog ID. example: the-catalog_id product_items: type: array items: $ref: '#/components/schemas/WhatsappInboundMessageOrderProductItem' text: type: string description: Text message sent along with the order. WhatsappInboundMessageOrderProductItem: type: object properties: product_retailer_id: type: string description: The product SKU identifier. quantity: type: integer format: int32 description: Number of item. item_price: type: number format: double description: Unitary price of item. currency: type: string description: Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD WhatsappMessageReaction: type: object description: |- When a user reacts to messages with an emoji, the message type is set to `reaction`, and this field is included. required: - message_id properties: message_id: type: string description: Specifies the `wamid` of the message received that contained the reaction. example: 'wamid.BgNODYxN...' emoji: type: 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. WhatsappInboundMessageReferral: type: object description: |- When a user messages businesses using call-to-actions buttons on [Ads that Click to WhatsApp](https://www.facebook.com/business/help/447934475640650) or a [Facebook Page call-to-action buttons](https://www.facebook.com/help/977869848936797), this field is included as an attachment. properties: source_url: type: string description: Specifies the URL that leads to the ad or post clicked by the user. Opening this URL takes you to the ad viewed by your user. source_type: type: string description: Specifies the type of the ad's source. Supported values are "ad" or "post". source_id: type: string description: Specifies the Meta ID for an ad or post. headline: type: string description: Specifies the headline used in the ad or post that generated the message. body: type: string description: The description, or body, from the ad or post that generated the message. media_type: type: string description: Media present in the ad or post the user clicked. Supported values are "image" or "video". image_url: type: string description: |- **Added if media_type is "image".** Contains a URL to the raw image. video_url: type: string description: |- **Added if media_type is "video".** Contains a URL to the video. thumbnail_url: type: string description: |- **Added if media_type is "video".** Contains a URL to the thumbnail image of the clicked video. ctwa_clid: type: string description: Click ID generated by Meta for ads that click to WhatsApp. WhatsappInboundMessageReferredProduct: type: object description: |- A Product Inquiry Message is received when a user is asking for more information about a specific product. These can be received as in two scenarios: 1. When a customer replies to Single or Multi-Product Messages. 2. When a customer accesses a business’ catalog through another entry point, navigates to a Product Details Page, and clicks Message Business about this Product. properties: catalog_id: type: string description: The catalog ID. product_retailer_id: type: string description: The product SKU identifier. WhatsappInboundMessageSystem: type: object description: |- When the message type is set to `system`, this field is included. This object is added to Webhooks if a user has changed their phone number and if a user’s identity has potentially changed on WhatsApp. properties: body: type: string description: |- Describes the system message event. Supported use cases are: - Phone number update: for when a user changes from an old number to a new number. - Identity update: for when a user identity has changed. new_wa_id: type: string description: |- **Added to Webhooks for phone number updates.** New WhatsApp ID of the customer. type: type: string description: |- Supported types are: - `user_changed_number`: for a user changed number notification. - `user_identity_changed`: for user identity changed notification. user: type: string description: |- **Added to Webhooks for identity updates.** The new WhatsApp user ID of the customer. WhatsappInboundMessageText: type: object description: |- When the notification describes a text message, the text object provides the body of the text message. properties: body: type: string description: Message text. WhatsappInboundMessageType: type: string description: |- WhatsApp inbound message type. See also [WhatsApp webhook messages object](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object). enum: - text - image - video - audio - document - sticker - contacts - location - interactive - button - reaction - request_welcome - order - system - unsupported WhatsappMessage: type: object description: WhatsApp outbound message object. required: - id - wabaId - from - to properties: id: type: string description: Unique ID of the message. wamid: type: string description: The original message ID on WhatsApp's platform. example: 'wamid.BgNODYxN...' wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' from: type: string description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' conversation: $ref: '#/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). type: $ref: '#/components/schemas/WhatsappMessageType' template: $ref: '#/components/schemas/WhatsappMessageTemplate' text: $ref: '#/components/schemas/WhatsappMessageText' image: $ref: '#/components/schemas/WhatsappMessageMedia' video: $ref: '#/components/schemas/WhatsappMessageMedia' audio: $ref: '#/components/schemas/WhatsappMessageMedia' document: $ref: '#/components/schemas/WhatsappMessageMedia' sticker: $ref: '#/components/schemas/WhatsappMessageMedia' location: $ref: '#/components/schemas/WhatsappMessageLocation' interactive: $ref: '#/components/schemas/WhatsappMessageInteractive' contacts: type: array items: $ref: '#/components/schemas/WhatsappMessageContact' reaction: $ref: '#/components/schemas/WhatsappMessageReaction' context: $ref: '#/components/schemas/WhatsappMessageContext' externalId: type: 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. status: $ref: '#/components/schemas/WhatsappMessageStatus' errorCode: type: string description: Error code when the message status is `failed`. example: 'INTERNAL_SERVER_ERROR' errorMessage: type: string description: Error message when the message status is `failed`. createTime: type: string format: 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`. example: '2022-06-01T12:00:00.000Z' updateTime: type: string format: 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`. example: '2022-06-01T12:00:00.000Z' sendTime: type: string format: 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`. example: '2022-06-01T12:00:00.000Z' deliverTime: type: string format: 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`. example: '2022-06-01T12:00:00.000Z' readTime: type: string format: 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`. example: '2022-06-01T12:00:00.000Z' totalPrice: type: number format: 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`.** example: 0.05 currency: type: string description: |- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD regionCode: type: string description: |- The [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the recipient phone number. example: 'US' pricingCategory: $ref: '#/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`.** whatsappApiError: $ref: '#/components/schemas/WhatsappApiError' bizType: type: 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. example: 'whatsapp' verificationId: type: string description: |- The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID WhatsappMessageContact: type: object description: |- When the message type filed is set to `contacts`, this object is included in the message object. required: - name properties: addresses: type: array items: $ref: '#/components/schemas/WhatsappMessageContactAddress' birthday: type: string description: |- `YYYY-MM-DD` formatted string. example: '2022-09-27' emails: type: array items: $ref: '#/components/schemas/WhatsappMessageContactEmail' name: $ref: '#/components/schemas/WhatsappMessageContactName' org: $ref: '#/components/schemas/WhatsappMessageContactOrg' phones: type: array description: Contact phone number(s) formatted as a phone object. items: $ref: '#/components/schemas/WhatsappMessageContactPhone' urls: type: array description: Contact URL(s) formatted as a urls object. items: $ref: '#/components/schemas/WhatsappMessageContactUrl' WhatsappMessageContactAddress: type: object description: |- Full contact address(es) formatted as an addresses object. properties: street: type: string description: Street number and name. city: type: string description: City name. state: type: string description: State abbreviation. zip: type: string description: ZIP code. country: type: string description: Full country name. country_code: type: string description: Two-letter country abbreviation. type: type: string description: Standard values are `HOME` and `WORK`. example: WORK WhatsappMessageContactEmail: type: object description: |- Contact email address(es) formatted as an emails object. properties: email: type: string description: Email address. type: type: string description: Standard values are `HOME` and `WORK`. example: WORK WhatsappMessageContactName: type: object description: Full contact name formatted as a name object. required: - formatted_name properties: formatted_name: type: string description: Full name, as it normally appears. first_name: type: string description: First name. last_name: type: string description: Last name. middle_name: type: string description: Middle name. suffix: type: string description: Name suffix. prefix: type: string description: Name prefix. WhatsappMessageContactOrg: type: object description: Contact organization information formatted as an org object. properties: company: type: string description: Name of the contact's company. department: type: string description: Name of the contact's department. title: type: string description: Contact's business title. WhatsappMessageContactPhone: type: object properties: phone: type: string description: Automatically populated with the `wa_id` value as a formatted phone number. type: type: string description: Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`. wa_id: type: string description: WhatsApp ID. WhatsappMessageContactUrl: type: object properties: url: type: string description: URL. type: type: string description: Standard values are `HOME` and `WORK`. WhatsappMessageContext: type: object description: |- Used to mention a specific message you are replying to. The reply can be any message type. properties: message_id: type: string description: Specifies the `wamid` of the message your are replying to. `wamid` is the original message ID on WhatsApp’s platform. example: 'wamid.BgNODYxN...' WhatsappMessageInteractive: type: object description: |- Use for `interactive` messages. 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. - `flow`: Use for Flow Messages. enum: - button - list - cta_url - product - product_list - catalog_message - location_request_message - order_details - order_status - voice_call - flow action: $ref: '#/components/schemas/WhatsappMessageInteractiveAction' body: $ref: '#/components/schemas/WhatsappMessageInteractiveBody' header: $ref: '#/components/schemas/WhatsappMessageInteractiveHeader' footer: $ref: '#/components/schemas/WhatsappMessageInteractiveFooter' 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. 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 and Multi-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. - `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. enum: - cta_url - send_location - flow - review_and_pay - review_order - voice_call parameters: $ref: '#/components/schemas/WhatsappMessageInteractiveActionParameters' WhatsappMessageInteractiveActionButton: type: object description: |- A button object in `interactive` messages. properties: type: type: string description: Only supported type is `reply` (for Reply Button). enum: - reply reply: type: object 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 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". 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`. example: 'navigate' flow_action_payload: type: object description: |- Required if `flow_action` is `navigate`. Should be omitted otherwise. 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. If provided, this must be a non-empty object. additionalProperties: type: object 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`. beneficiaries: type: 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: $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`. 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' 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 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' WhatsappMessageInteractiveActionSectionProductItem: type: object properties: product_retailer_id: type: string description: |- Required for Multi-Product Messages. Unique identifier of the product in a catalog. WhatsappMessageInteractiveActionSectionRow: type: object 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 WhatsappMessageInteractiveBody: type: object description: |- Optional for type `product`. Required for other message types. properties: text: type: string description: |- The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. maxLength: 1024 WhatsappMessageInteractiveFooter: type: object description: |- Optional. An object with the footer of the message. properties: text: type: string description: |- The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters. maxLength: 60 WhatsappMessageInteractiveHeader: type: object description: |- Required for type `product_list`. Optional for other types. properties: type: 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. 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/WhatsappMessageMedia' video: $ref: '#/components/schemas/WhatsappMessageMedia' document: $ref: '#/components/schemas/WhatsappMessageMedia' WhatsappMessageLocation: type: object description: |- Use for `location` messages. required: - latitude - longitude properties: latitude: type: number format: double description: Latitude of the location. longitude: type: number format: double description: Longitude of the location. name: type: string description: Name of the location. address: type: string description: Address of the location. Only displayed if `name` is present. WhatsappMessageMedia: type: object description: |- Use for `image`, `video`, `audio`, `document`, or `sticker` messages. See also [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). required: - link properties: link: type: string description: The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. caption: type: string description: Describes the specified `image`, `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. 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 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 WhatsappMessageOrderDetails: type: object description: |- Contains the order details when sending a template message with a `order_details` button. required: - currency - order - reference_id - total_amount - type - payment_settings properties: currency: type: string description: |- The currency for this order. Currently the only supported value is `INR`. order: $ref: '#/components/schemas/WhatsappMessageOrderInfo' description: |- Provides order `status`, `items`, `subtotal`, `tax`, etc. reference_id: type: string 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: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: |- The total amount of the order. type: type: string description: |- The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`. payment_settings: type: array description: |- Payment settings for the order. items: $ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting' 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 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 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. 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' 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' 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 WhatsappMessageOrderStatus: type: object properties: reference_id: type: string description: |- Unique identifier for the order provided by the business. order: $ref: '#/components/schemas/WhatsappMessageOrderInfo' description: |- Provides only `status` and `description` of this order for `order_status` messages. 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 WhatsappMessageSendRequest: type: object required: - from - to - type properties: from: type: string description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: $ref: '#/components/schemas/WhatsappMessageType' template: $ref: '#/components/schemas/WhatsappMessageTemplate' description: Required when `type` is `template`. text: $ref: '#/components/schemas/WhatsappMessageText' description: Required when `type` is `text`. image: $ref: '#/components/schemas/WhatsappMessageMedia' description: Required when `type` is `image`. video: $ref: '#/components/schemas/WhatsappMessageMedia' description: Required when `type` is `video`. audio: $ref: '#/components/schemas/WhatsappMessageMedia' description: Required when `type` is `audio`. document: $ref: '#/components/schemas/WhatsappMessageMedia' description: Required when `type` is `document`. sticker: $ref: '#/components/schemas/WhatsappMessageMedia' description: Required when `type` is sticker. location: $ref: '#/components/schemas/WhatsappMessageLocation' description: Required when `type` is `location`. interactive: $ref: '#/components/schemas/WhatsappMessageInteractive' description: Required when `type` is `interactive`. contacts: type: array description: Required when `type` is `contacts`. items: $ref: '#/components/schemas/WhatsappMessageContact' reaction: $ref: '#/components/schemas/WhatsappMessageReaction' description: Required when `type` is `reaction`. context: $ref: '#/components/schemas/WhatsappMessageContext' externalId: type: 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. filterUnsubscribed: type: 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/message/sendDirectly`. filterBlocked: type: 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/message/sendDirectly`. WhatsappMessageStatus: type: 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. enum: - accepted - failed - sent - delivered - read WhatsappMessageTemplate: type: object description: |- Use for sending a WhatsApp `template` message. required: - name - language properties: name: type: string description: Name of the template. example: sample_whatsapp_template language: type: object description: Contains a language object. Specifies the language the template may be rendered in. properties: code: type: string description: The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. example: en_US policy: type: string description: |- The language policy the message should follow. Default (and only supported option): `deterministic`, which means that WhatsApp delivers the message template in exactly the language and locale asked for. example: 'deterministic' required: - code components: type: array description: |- **Required when the specified template contains variables or media.** Array of component objects containing the parameters of the message. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponent' WhatsappMessageTemplateComponent: type: object description: Component object containing the parameters of the message. required: - type properties: type: type: string description: |- Component type. enum: - header - body - button - limited_time_offer - carousel - order_status sub_type: 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. enum: - quick_reply - url - copy_code - catalog - mpm - flow - order_details index: type: integer format: int32 minimum: 0 maximum: 9 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. parameters: type: 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: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameter' cards: type: array description: |- Use for `carousel` components. Provides card components containing the parameters of the message. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentCard' WhatsappMessageTemplateComponentCard: type: object description: |- Card component containing the parameters of the message. properties: card_index: type: integer format: int32 description: |- **Required.** Zero-indexed order in which card appears within the card carousel. 0 indicates first card, 1 indicates second card, etc. minimum: 0 maximum: 9 components: type: array description: |- Card component. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentCardComponent' WhatsappMessageTemplateComponentCardComponent: type: object description: Card component object containing the parameters of the message. required: - type properties: type: type: string description: |- Component type. enum: - header - body - button sub_type: 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. enum: - quick_reply - url index: type: integer format: int32 minimum: 0 maximum: 9 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. parameters: type: 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: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameter' WhatsappMessageTemplateComponentParameter: type: object properties: type: 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`. - `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`. enum: - text - image - video - document - payload - coupon_code - limited_time_offer - action - order_status - location text: type: 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. payload: type: 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. coupon_code: type: string description: |- **Required when `type` = `coupon_code`.** The coupon code to be copied when the customer taps the button. image: $ref: '#/components/schemas/WhatsappMessageMedia' description: |- **Required when the template `HEADER` format is `IMAGE`.** video: $ref: '#/components/schemas/WhatsappMessageMedia' description: |- **Required when the template `HEADER` format is `VIDEO`.** document: $ref: '#/components/schemas/WhatsappMessageMedia' description: |- **Required when the template `HEADER` format is `DOCUMENT`.** limited_time_offer: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterLimitedTimeOffer' action: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterAction' order_status: $ref: '#/components/schemas/WhatsappMessageOrderStatus' location: $ref: '#/components/schemas/WhatsappMessageLocation' description: |- **Required when `type` = `location`.** WhatsappMessageTemplateComponentParameterAction: type: object description: |- Required if template uses catalog or MPM (multi-product message) buttons. properties: thumbnail_product_retailer_id: type: 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. example: '2lc20305pt' sections: type: array description: |- Use for MPM templates. Product sections. You can define up to 10 sections. maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterActionSection' 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_action_data: type: object additionalProperties: type: object description: |- Use for `FLOW` buttons. JSON object with the data payload for the first screen. order_details: $ref: '#/components/schemas/WhatsappMessageOrderDetails' description: |- Required for `order_details` buttons. WhatsappMessageTemplateComponentParameterActionSection: type: object properties: title: type: string description: |- Section title text. Maximum 24 characters. Markdown is not supported. maxLength: 24 product_items: type: 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. minItems: 1 maxItems: 30 items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterActionSectionProductItem' WhatsappMessageTemplateComponentParameterActionSectionProductItem: type: object properties: product_retailer_id: type: 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: type: object description: |- Required if template uses offer expiration details. properties: expiration_time_ms: type: integer format: int64 description: |- **Required.** Offer code expiration time as a UNIX timestamp in milliseconds. example: '1698562800000' WhatsappMessageText: type: object description: |- WhatsApp Message Text Object. required: - body properties: body: type: string 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. maxLength: 4096 preview_url: type: 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: type: string description: |- WhatsApp outbound message type. See also [WhatsApp messages](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages). enum: - template - text - image - audio - video - document - sticker - location - interactive - contacts - reaction WhatsappPayment: type: object description: |- Represents a payment object. Businesses receive updates via webhooks when the status of the user-initiated transaction changes. required: - wabaId - referenceId - status properties: wabaId: type: string description: WhatsApp Business Account ID. referenceId: type: string description: |- Unique identifier for the payment 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. status: $ref: '#/components/schemas/WhatsappPaymentStatus' transactions: type: array description: |- Contains the latest transaction attempt for this payment. items: $ref: '#/components/schemas/WhatsappPaymentTransaction' WhatsappPaymentStatus: type: string description: |- Status of this payment. - `captured`: Indicates the payment is successfully completed. - `pending`: Indicates the user attempted but yet to receive success transactions signal. enum: - captured - pending WhatsappPaymentTransaction: type: object description: |- Represents a transaction attempt for a payment. required: - id - type - status - createdTimestamp - updatedTimestamp - amount - currency properties: id: type: string description: Transaction ID. type: type: string description: |- The payment type for this transactions. One of `billdesk`, `razorpay`, `payu`, or `zaakpay`. enum: - billdesk - razorpay - payu - zaakpay status: type: string description: |- The status of the transaction. One of `pending`, `success` or `failed`. enum: - pending - success - failed createdTimestamp: type: integer format: int64 description: |- Time when transaction was created in epoch milliseconds. updatedTimestamp: type: integer format: int64 description: |- Time when transaction was last updated in epoch milliseconds. amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: Total amount that user has paid. currency: type: string description: |- The currency for this payment. Currently the only supported value is `INR`. methodType: type: string description: |- Describes the type of payment method used by consumer to pay for the order. Can be one of `upi`, `card`, `wallet`, or `netbanking`. The payment method information might not be available for failed payments. example: 'upi' error: type: object description: |- The payment error details might not be available for all payments attempts. required: - code - reason properties: code: type: string description: |- Describes the payment failure reason that generated by payment gateway and Meta transmits this to partners. reason: type: string description: |- Describes the payment failure reason in plain text that is generated by payment gateway and Meta transmits this to partners. WhatsappPhoneNumber: type: object description: |- See [WhatsApp Business Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers) properties: id: type: string description: Phone number ID. example: '1234567890123456' phoneNumber: type: string description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' displayPhoneNumber: type: string description: Display phone number. example: '+1 631-555-1111' wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' qualityRating: $ref: '#/components/schemas/WhatsappPhoneNumberQualityRating' messagingLimit: type: string description: |- Messaging limits determine the maximum number of business-initiated conversations each phone number can start in a rolling 24-hour period. See also [Messaging Limits](https://developers.facebook.com/docs/whatsapp/messaging-limits). - `TIER_NOT_SET`: Unknown limit. - `TIER_50`: 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: 250 business-initiated conversations in a rolling 24-hour period. - `TIER_1K`: 1K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_10K`: 10K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_100K`: 100K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_UNLIMITED`: An unlimited number of business-initiated conversations in a rolling 24-hour period. example: TIER_1K verifiedName: type: string description: Verified name. example: John’s Cake Shop codeVerificationStatus: $ref: '#/components/schemas/WhatsappPhoneNumberCodeVerificationStatus' isOfficialBusinessAccount: type: boolean description: |- Whether this phone number is an official business account or not. An official business account has a green checkmark badge in its profile and chat thread headers. See [Official Business Account](https://developers.facebook.com/docs/whatsapp/overview/business-accounts#official-business-account) for more information. status: $ref: '#/components/schemas/WhatsappPhoneNumberStatus' nameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' newNameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' description: |- The review status of the new display name request. See also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). decision: $ref: '#/components/schemas/WhatsappReviewDecision' description: Review decision made on this phone number. One of `APPROVED` or `REJECTED`. requestedVerifiedName: type: string description: Last requested verified name. rejectionReason: type: string description: Rejection reason. qualityUpdateEvent: $ref: '#/components/schemas/WhatsappPhoneNumberQualityUpdateEventEnum' WhatsappPhoneNumberCodeVerificationStatus: type: string description: To see if a phone number has been verified via OTP (one-time password). enum: - VERIFIED - NOT_VERIFIED - EXPIRED WhatsappPhoneNumberNameStatus: type: string description: |- The review status of the current display name request. See also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). - `APPROVED`: The name has been approved. You can download your certificate now. - `AVAILABLE_WITHOUT_REVIEW`: The certificate for the phone is available and display name is ready to use without review. - `DECLINED`: The name has not been approved. You cannot download your certificate. - `EXPIRED`: Your certificate has expire and can no longer be downloaded. - `PENDING_REVIEW`: Your name request is under review. You cannot download your certificate. - `NONE`: No certificate is available. enum: - APPROVED - AVAILABLE_WITHOUT_REVIEW - DECLINED - EXPIRED - PENDING_REVIEW - NONE WhatsappPhoneNumberPage: type: object description: Represents a given page of WhatsApp phone numbers. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing WhatsApp phone number objects. type: array items: $ref: '#/components/schemas/WhatsappPhoneNumber' WhatsappPhoneNumberProfile: type: object description: |- WhatsApp Phone Number Business Profile. Customers can view your business profile by clicking your business's name or number in a conversation thread. properties: about: type: string description: |- The business's **About** text. This text appears in the business's profile, beneath its profile image, phone number, and contact buttons. example: ABOUT address: type: string maxLength: 256 description: Address of the business. Character limit 256. example: ADDRESS description: type: string maxLength: 512 description: Description of the business. Character limit 512. example: DESCRIPTION email: type: string maxLength: 128 description: The contact email address (in valid email format) of the business. Character limit 128. example: tom@example.com profilePictureUrl: type: string description: URL of the profile picture used to upload to Meta. example: 'https://URL' vertical: $ref: '#/components/schemas/WhatsappPhoneNumberProfileVertical' websites: type: array maxItems: 2 description: |- The URLs associated with the business. For instance, a website, Facebook Page, or Instagram. You must include the http:// or https:// portion of the URL. There is a maximum of 2 websites with a maximum of 255 characters each. items: type: string maxLength: 255 example: 'https://WEBSITE-1' WhatsappPhoneNumberProfileUpdateRequest: type: object description: |- WhatsApp Phone Number Business Profile. Customers can view your business profile by clicking your business's name or number in a conversation thread. properties: about: type: string minLength: 1 maxLength: 139 description: |- The business's **About** text. This text appears in the business's profile, beneath its profile image, phone number, and contact buttons. - String cannot be empty. - Strings must be between 1 and 139 characters. - Rendered emojis are supported however their unicode values are not. Emoji unicode values must be Java- or JavaScript-escape encoded. - Hyperlinks can be included but will not render as clickable links. - Markdown is not supported. example: ABOUT address: type: string maxLength: 256 description: Address of the business. Character limit 256. example: ADDRESS description: type: string maxLength: 512 description: Description of the business. Character limit 512. example: DESCRIPTION email: type: string maxLength: 128 description: The contact email address (in valid email format) of the business. Character limit 128. example: tom@example.com profilePictureUrl: type: string description: URL of the profile picture that was uploaded to Meta. example: 'https://PICTURE-URL' vertical: $ref: '#/components/schemas/WhatsappPhoneNumberProfileVertical' websites: type: array maxItems: 2 description: |- The URLs associated with the business. For instance, a website, Facebook Page, or Instagram. You must include the http:// or https:// portion of the URL. There is a maximum of 2 websites with a maximum of 255 characters each. items: type: string maxLength: 255 example: 'https://WEBSITE-1' WhatsappPhoneNumberProfileVertical: type: string description: Industry of the WhatsApp phone number business profile. This can be either an empty string or one of the accepted values. example: OTHER enum: - OTHER - AUTO - BEAUTY - APPAREL - EDU - ENTERTAIN - EVENT_PLAN - FINANCE - GROCERY - GOVT - HOTEL - HEALTH - NONPROFIT - PROF_SERVICES - RETAIL - TRAVEL - RESTAURANT WhatsappPhoneNumberQualityRating: type: string description: |- Quality rating. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001). - `GREEN`: High quality. - `YELLOW`: Medium quality. - `RED`: Low quality. - `UNKNOWN`: Unknown quality. enum: - GREEN - YELLOW - RED - UNKNOWN WhatsappPhoneNumberQualityUpdateEventEnum: type: string description: |- Indicates the update event type of WhatsApp phone number quality when a notification is sent to you. - `ONBOARDING`: Typically when the messaging limit changes from `TIER_NOT_SET` to another tier. - `UPGRADE`: Messaging limit tier upgraded. - `DOWNGRADE`: Messaging limit tier downgraded. - `FLAGGED`: Flagged status occurs when the quality rating reaches a low state. If the message quality improves to a high or medium state and maintains this for 7 days, your status will return to Connected. If the quality rating doesn't improve, your status will still return to Connected, but you'll be placed in a lower messaging limit tier. Learn more on [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001) docs. - `UNFLAGGED`: Phone number status changes from `FLAGGED` to `CONNECTED`. enum: - ONBOARDING - UPGRADE - DOWNGRADE - FLAGGED - UNFLAGGED WhatsappPhoneNumberStatus: type: string description: |- The status of a WhatsApp business phone number. - `PENDING`: Pending. Phone number is newly added. Verify and register this phone number so it can be connected to your account. - `UNVERIFIED`: Unverified. Verify this phone number to start sending messages. - `MANUAL_REVIEW`: Being reviewed. Phone number is currently being reviewed for connection to your account. - `DISCONNECTED`: Offline. Phone number is currently not reachable by WhatsApp servers. - `CONNECTED`: Connected. Phone number is associated with this account and working properly. - `FLAGGED`: Flagged. This phone number has been flagged due to low quality messages. - `WARNED`: Warned. A warning has been issued for this number, potentially due to spam reports. - `RATE_LIMITED`: Rate limited. The number of messages you can send from this phone number may be restricted. - `BANNED`: Banned. Phone number cannot be used with a WhatsApp account. - `RESTRICTED`: Restricted. This phone number has reached its 24-hour messaging limit and can no longer send messages to customers. Please wait until the messaging limit is reset to send messages. - `BLOCKED`: Message limit reached. The limit has been reached for this 24-hour period. - `MIGRATED`: Transferred. This phone number has been transferred to another WhatsApp Business account. - `UNKNOWN`: Unavailable. The status of this phone number can't be determined right now. enum: - PENDING - UNVERIFIED - MANUAL_REVIEW - DISCONNECTED - CONNECTED - FLAGGED - WARNED - RATE_LIMITED - BANNED - RESTRICTED - BLOCKED - MIGRATED - UNKNOWN WhatsappPricingCategory: type: 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). enum: - referral_conversion - authentication - authentication_international - marketing - marketing_lite - utility - service WhatsappProfile: type: object description: Represents the profile of a WhatsApp account. properties: name: type: string description: Name of the WhatsApp account. example: John WhatsappReviewDecision: type: string description: Used if a decision about WhatsApp accounts or phone numbers has been made. enum: - APPROVED - REJECTED WhatsappTemplate: type: object description: See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). required: - wabaId - name - language properties: wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' name: type: string description: Name of the template. maxLength: 512 pattern: '[a-z0-9]{1,512}' language: type: string description: Language code of the template. See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. example: en_US category: $ref: '#/components/schemas/WhatsappTemplateCategory' subCategory: $ref: '#/components/schemas/WhatsappTemplateSubCategory' previousCategory: type: string description: |- This field indicates the template's previous category (or `null`, for newly created templates after April 1, 2023). Compare this value to the template's `category` field value, which indicates the template's current category. messageSendTtlSeconds: type: integer format: int32 description: |- If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of **10 minutes**, and messages that use a utility or marketing template have a default TTL of **30 days**. Set its value between `30` and `900` seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or `30` and `43200` seconds (i.e., 30 seconds to 12 hours) for utility templates, or `43200` and `2592000` seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to `-1`, which will set a custom TTL of 30 days for either type of template. We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Authentication templates created before October 23, 2024, have a default TTL of 30 days. example: 600 components: type: array description: |- Template components. A template consists of `HEADER`, `BODY`, `FOOTER`, and `BUTTONS` components. `BODY` component is required, the other types are optional. minItems: 1 items: $ref: '#/components/schemas/WhatsappTemplateComponent' status: $ref: '#/components/schemas/WhatsappTemplateStatus' qualityRating: $ref: '#/components/schemas/WhatsappTemplateQualityRating' reason: type: string description: The reason why the template is rejected. createTime: type: string format: date-time description: The time at which this object is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' updateTime: type: string format: date-time description: The time at which this object is updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' statusUpdateEvent: $ref: '#/components/schemas/WhatsappTemplateStatusUpdateEventEnum' disableDate: type: string description: |- The date at which the template will be disabled. When a WhatsApp template `FLAGGED` event is received, this field is set. example: 'December 9, 2022' whatsappApiError: $ref: '#/components/schemas/WhatsappApiError' WhatsappTemplateCategory: type: string description: |- Category of WhatsApp templates. - `AUTHENTICATION`: Enable businesses to authenticate users with one-time passcodes, potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges). - `MARKETING`: Include promotions or offers, informational updates, or invitations for customers to respond / take action. Any conversation that does not qualify as utility or authentication is a marketing conversation. - `UTILITY`: Facilitate a specific, agreed-upon request or transaction or update to a customer about an ongoing transaction, including post-purchase notifications and recurring billing statements. enum: - AUTHENTICATION - MARKETING - UTILITY WhatsappTemplateComponent: type: object properties: type: type: string description: |- **Required.** Template component type. - `BODY`: Body components are text-only components and are required by all templates. Templates are limited to one body component. - `HEADER`: Headers are optional components that appear at the top of template messages. Headers support text, media (images, videos, documents). Templates are limited to one header component. - `FOOTER`: Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component. - `BUTTONS`: Buttons are optional interactive components that perform specific actions when tapped. - `LIMITED_TIME_OFFER`: Use for limited-time offer templates. The delivered message can display an offer expiration details section with a heading, an optional expiration timer, and the offer code itself. - `CAROUSEL`: Carousel templates allow you to send a single text message (1), accompanied by a set of up to 10 carousel cards (2) in a horizontally scrollable view. enum: - BODY - HEADER - FOOTER - BUTTONS - LIMITED_TIME_OFFER - CAROUSEL format: type: string description: |- **Required for type `HEADER`.** enum: - TEXT - IMAGE - VIDEO - DOCUMENT - LOCATION text: type: string description: |- For body text (type = `BODY`), maximum 1024 characters. For header text (type = `HEADER`, format = `TEXT`), maximum 60 characters. For footer text (type = `FOOTER`), maximum 60 characters. For card body text (`CAROUSEL` card component type = `BODY`), maximum 160 characters. maxLength: 1024 buttons: type: array description: |- **Required for type `BUTTONS`.** Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits. If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a **See all options** button. Tapping the **See all options** button reveals the remaining buttons. maxItems: 10 items: $ref: '#/components/schemas/WhatsappTemplateComponentButton' add_security_recommendation: type: boolean description: |- **Optional. Only applicable in the `BODY` component of an AUTHENTICATION template.** Set to `true` if you want the template to include the string, *For your security, do not share this code.* Set to `false` to exclude the string. code_expiration_minutes: type: integer format: int32 description: |- **Optional. Only applicable in the `FOOTER` component of an AUTHENTICATION template.** Indicates number of minutes the password or code is valid. If omitted, the code expiration warning will not be displayed in the delivered message. Minimum 1, maximum 90. maximum: 90 minimum: 1 example: 5 limited_time_offer: $ref: '#/components/schemas/WhatsappTemplateComponentLimitedTimeOffer' example: $ref: '#/components/schemas/WhatsappTemplateComponentExample' cards: type: array description: |- **Required for type `CAROUSEL`.** Carousel templates support up to 10 carousel cards. maxItems: 10 items: $ref: '#/components/schemas/WhatsappTemplateComponentCard' WhatsappTemplateComponentButton: type: object required: - type properties: type: $ref: '#/components/schemas/WhatsappTemplateComponentButtonType' text: type: string description: |- **Required for button type `PHONE_NUMBER` or `URL`.** Button text. For `CODE_CODE` buttons, the text is a pre-set value and cannot be customized. For `OTP` buttons, if omitted, the text will default to a pre-set value localized to the template's language. For example, `Copy Code` for English (US). If your template is using a one-tap autofill button and you supply this value, the authentication template message will display a copy code button with this text if we are unable to validate your [handshake](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/autofill-button-authentication-templates#handshake). Maximum 25 characters. maxLength: 25 url: type: string description: |- **Required for button type `URL`.** URL of website. There can be at most 1 variable at the end of the URL. Example: `https://www.luckyshrub.com/shop?promo={{1}}`. 2000 characters maximum. maxLength: 2000 phone_number: type: string description: |- **Required for button type `PHONE_NUMBER`.** Alphanumeric string. Business phone number to be (display phone number) called when the user taps the button. 20 characters maximum. maxLength: 20 example: 15550051310 otp_type: $ref: '#/components/schemas/WhatsappTemplateComponentButtonOtpType' description: |- **Required for button type `OTP`.** Indicates button OTP type. Set to `COPY_CODE` if you want the template to use a copy code button, `ONE_TAP` to have it use a one-tap autofill button, or `ZERO_TAP` to have no button at all. autofill_text: type: string description: |- **One-tap and zero-tap buttons only.** One-tap button text. Maximum 25 characters. maxLength: 25 example: 'Autofill' package_name: type: string description: |- **One-tap and zero-tap buttons only.** Your Android app's package name. example: 'com.example.myapplication' signature_hash: type: string description: |- **One-tap and zero-tap buttons only.** Your app signing key hash. See [App Signing Key Hash](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/zero-tap-authentication-templates#app-signing-key-hash). example: 'K8a%2FAINcGX7' zero_tap_terms_accepted: type: boolean description: |- **Zero-tap buttons only.** Set to `true` to indicate that you understand that your use of zero-tap authentication is subject to the WhatsApp Business Terms of Service, and that it's your responsibility to ensure your customers expect that the code will be automatically filled in on their behalf when they choose to receive the zero-tap code through WhatsApp. If set to `false`, the template will not be created as you need to accept zero-tap terms before creating zero-tap enabled message templates. example: type: array description: |- Sample full URL for a `URL` button with a variable. items: type: string flow_id: type: string description: |- **Conditionally required for button type `FLOW`.** The unique ID of the Flow. Cannot be used if `flow_name` or `flow_json` parameters are provided. Only one of these parameters is allowed. example: '1' flow_name: type: string description: |- **Conditionally required for button type `FLOW`.** The name of the Flow. Cannot be used if `flow_id` or `flow_json` parameters are provided. Only one of these parameters is allowed. The Flow ID is stored in the message template, not the name, so changing the Flow name will not affect existing message templates. flow_json: type: string description: |- **Conditionally required for button type `FLOW`.** The Flow JSON encoded as string with escaping. The Flow JSON specifies the content of the Flow. Cannot be used if `flow_id` or `flow_name` parameters are provided. Only one of these parameters is allowed. flow_action: type: string description: |- **Use for button type `FLOW`.** Either `navigate` or `data_exchange`. Defaults to `navigate`. example: 'navigate' navigate_screen: type: string description: |- **Required if `flow_action` is `navigate`.** The unique ID of the Screen in the Flow. example: 'WELCOME_SCREEN' WhatsappTemplateComponentButtonOtpType: type: string description: |- Indicates button OTP type. Set to `COPY_CODE` if you want the template to use a copy code button, `ONE_TAP` to have it use a one-tap autofill button, or `ZERO_TAP` to have no button at all. enum: - COPY_CODE - ONE_TAP - ZERO_TAP WhatsappTemplateComponentButtonType: type: string description: |- Button type. - `PHONE_NUMBER`: Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button. - `URL`: URL buttons load the specified URL in the device's default web browser when tapped by the app user. Templates are limited to two URL buttons. - `QUICK_REPLY`: Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. - `COPY_CODE`: Copy code buttons 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. Templates are limited to one copy code button. - `OTP`: One-time password (OTP) buttons are a special type of URL button component used with authentication templates. - `CATALOG`: When a customer taps the **View catalog** button in a catalog template message, your product catalog appears within WhatsApp. - `MPM`: Customers can browse products and sections by tapping the **View items** button in a multi-product template message. - `FLOW`: Use this type to specify the [Flow](https://developers.facebook.com/docs/whatsapp/flows) to be sent with the template message. - `ORDER_DETAILS`: Provides a order details button with `Review and Pay` text. - `VOICE_CALL`: Triggers a WhatsApp call, when clicked by a WhatsApp customer. enum: - PHONE_NUMBER - URL - QUICK_REPLY - COPY_CODE - OTP - CATALOG - MPM - FLOW - ORDER_DETAILS - VOICE_CALL WhatsappTemplateComponentCard: type: object description: |- Carousel templates support up to 10 carousel cards. Cards must have a media header (image or video) and can optionally include body text and up to 2 quick reply buttons, phone number buttons, or URL buttons (button types can be mixed). properties: components: type: array description: |- **Required.** Card components. items: $ref: '#/components/schemas/WhatsappTemplateComponentCardComponent' description: |- Cards must have a media header (image or video) and can optionally include body text and up to 2 quick reply buttons, phone number buttons, or URL buttons (button types can be mixed). WhatsappTemplateComponentCardComponent: type: object properties: type: type: string description: |- **Required.** Card component type. - `BODY`: Body components are text-only components. Cards must have body text. - `HEADER`: Cards must have a media header (image or video). - `BUTTONS`: Buttons are interactive components that perform specific actions when tapped. Cards must have at least one button, up to 2 buttons. enum: - BODY - HEADER - BUTTONS format: type: string description: |- **Required for type `HEADER`.** Cards must have a media header (image or video). enum: - IMAGE - VIDEO text: type: string description: |- **Required for type `BODY`.** Card body text supports variables. Maximum 160 characters. maxLength: 160 buttons: type: array description: |- **Required for type `BUTTONS`.** Cards must have at least one button. Supports 2 buttons. Buttons can be the same or a mix of quick reply buttons, phone number buttons, or URL buttons. minItems: 1 maxItems: 2 items: $ref: '#/components/schemas/WhatsappTemplateComponentButton' example: $ref: '#/components/schemas/WhatsappTemplateComponentExample' WhatsappTemplateComponentExample: type: object description: |- **Required** when: - `type` is `HEADER`, and `format` is one of `IMAGE`, `VIDEO`, or `DOCUMENT`. Provide a sample media URL in `header_url`. - `type` is `HEADER`, `format` is `TEXT`, and a variable is used in `text`. Provide a sample value for that variable in `header_text`. There can be at most 1 variable in `HEADER` text. - `type` is `BODY`, and variables are used in `text`. Provide sample values for those variables in `body_text`. properties: body_text: type: array description: |- Sample values for variables in `text` of a `BODY` component. items: type: array items: type: string header_text: type: array description: |- Sample value for the variable in `text` of a `HEADER` component. items: type: string header_url: type: array description: |- Sample media URL for a `HEADER` component whose format is one of `IMAGE`, `VIDEO`, or `DOCUMENT`. Supported types: - For `IMAGE`, the URL must end with one of `.jpg`, `.jpeg`, or `.png`, size limit is 5MB. - For `VIDEO`, the URL must end with `.mp4`, size limit is 16MB. - For `DOCUMENT`, the URL must end with `.pdf`, size limit is 100MB. items: type: string WhatsappTemplateComponentLimitedTimeOffer: type: object description: |- Use for `LIMITED_TIME_OFFER` components. properties: text: type: string description: |- **Required.** Offer details text. Maximum 16 characters. maxLength: 16 example: 'Expiring offer!' has_expiration: type: boolean description: |- **Optional.** Set to `true` to have the [offer expiration details](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/limited-time-offer-templates#offer-expiration-details) appear in the delivered message. If set to `true`, the copy code button component must be included in the `buttons` array, and must appear first in the array. If set to `false`, offer expiration details will not appear in the delivered message and the copy code button component is optional. If including the copy code button, it must appear first in the `buttons` array. WhatsappTemplateCreateRequest: type: object description: See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). required: - wabaId - name - language - category - components properties: wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' name: type: string description: Name of the template. maxLength: 512 pattern: '[a-z0-9]{1,512}' example: sample_whatsapp_template language: type: string description: Language code of the template. See [Supported Languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) for all codes. example: en_US category: $ref: '#/components/schemas/WhatsappTemplateCategory' subCategory: $ref: '#/components/schemas/WhatsappTemplateSubCategory' messageSendTtlSeconds: type: integer format: int32 description: |- If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of **10 minutes**, and messages that use a utility or marketing template have a default TTL of **30 days**. Set its value between `30` and `900` seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or `30` and `43200` seconds (i.e., 30 seconds to 12 hours) for utility templates, or `43200` and `2592000` seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to `-1`, which will set a custom TTL of 30 days for either type of template. We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Authentication templates created before October 23, 2024, have a default TTL of 30 days. example: 600 components: type: array items: $ref: '#/components/schemas/WhatsappTemplateComponent' WhatsappTemplateEditRequest: type: object description: The request body to edit a WhatsApp template. required: - components properties: components: type: array items: $ref: '#/components/schemas/WhatsappTemplateComponent' messageSendTtlSeconds: type: integer format: int32 description: |- If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of **10 minutes**, and messages that use a utility or marketing template have a default TTL of **30 days**. Set its value between `30` and `900` seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or `30` and `43200` seconds (i.e., 30 seconds to 12 hours) for utility templates, or `43200` and `2592000` seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to `-1`, which will set a custom TTL of 30 days for either type of template. We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Authentication templates created before October 23, 2024, have a default TTL of 30 days. example: 600 WhatsappTemplatePage: type: object description: Represents a given page of WhatsApp templates. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing WhatsApp template objects. type: array items: $ref: '#/components/schemas/WhatsappTemplate' WhatsappTemplateQualityRating: type: string description: |- Quality rating of WhatsApp template. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Template Quality Rating](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#quality-rating). - `GREEN`: High quality. - `YELLOW`: Medium quality. - `RED`: Low quality. - `UNKNOWN`: Unknown quality. enum: - GREEN - YELLOW - RED - UNKNOWN WhatsappTemplateStatus: type: string description: |- The status of a WhatsApp template. - `PENDING`: The template is still under review. Review can take up to 24 hours. - `REJECTED`: The template has been rejected during review process. - `APPROVED`: The template is approved, and you may begin sending it to customers. - `PAUSED`: The template has been paused due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers. See [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing). - `DISABLED`: The template has been disabled due to recurring negative feedback from customers or for violating one or more of our policies. Message templates with this status cannot be sent to customers. You may be able to edit a disabled message template and request an appeal. See [Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals). - `IN_APPEAL`: The template is in appeal. See also [Template Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals). - `DELETED`: The template is deleted. enum: - PENDING - REJECTED - APPROVED - PAUSED - DISABLED - IN_APPEAL - DELETED example: REJECTED WhatsappTemplateStatusUpdateEventEnum: type: string description: |- Used when an event happened on WhatsApp template status updates. - `PENDING`: Pending. - `APPROVED`: Approved. - `REJECTED`: Rejected. - `IN_APPEAL`: In appeal. See also [Template Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals). - `PAUSED`: Paused. See also [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing). - `FLAGGED`: Flagged. The template is scheduled for disabling. - `DISABLED`: Disabled. See also [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing). - `REINSTATED`: Reinstated. - `PENDING_DELETION`: Pending deletion. enum: - PENDING - APPROVED - REJECTED - IN_APPEAL - PAUSED - FLAGGED - DISABLED - REINSTATED - PENDING_DELETION WhatsappTemplateSubCategory: type: string description: |- Subcategory of WhatsApp templates. - ORDER_STATUS: Order status template is categorized as `UTILITY` template and apart from name and language of choice, it has general template components such as `BODY`, `FOOTER` and additionally subcategory as `ORDER_STATUS`. enum: - ORDER_STATUS