# ReadMe API definition target: ycloud-api.json 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 Media - name: Messenger Messages - name: WhatsApp Messages - name: WhatsApp Blocked Users - name: WhatsApp Groups - name: WhatsApp Calling - name: WhatsApp Phone Numbers - name: WhatsApp Templates - name: WhatsApp Flows - name: Meta Business Agent 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' 400: description: The notes array or note content is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List contacts tags: - Contacts operationId: contact-list description: |- Returns a paginated list of contacts. Omit `pageAfter` to use the existing page-based pagination. To use forward cursor pagination, set `pageAfter=0` for the first page, then pass the exact `cursor.after` value returned by the previous response. Cursor results are ordered by contact ID in ascending order. Do not combine `pageAfter` with `page`, `pageBefore`, `offset`, or `sort`. Keep all filters unchanged while following a cursor. Concurrent contact inserts, deletions, or filter-field updates use weak consistency; restart a full traversal with `pageAfter=0` when a fresh snapshot is required. x-group-parameters: true parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/includeTotal' - $ref: '#/components/parameters/contactPageAfter' - name: filter.tags in: query description: |- Comma-separated list of tag names. If any tag does not exist, the request fails with a parameter error. 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' 400: description: One or more query parameters are invalid, including an invalid cursor, incompatible pagination parameters, an out-of-range limit, or an unknown tag. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /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. If every supplied persisted contact field already has the requested value, the contact is not updated and no `contact.attributes_changed` event is emitted. Note mutations in the same request are still applied. 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' 400: description: The notes array, note ID, or note content is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The contact or referenced contact note does not exist, or the note is not owned by the contact. 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' /contact/contacts/{contactIdentifier}/notes: get: summary: List contact notes tags: - Contacts operationId: contact-notes-list description: |- Returns all notes for a contact, ordered by creation time descending. The `{contactIdentifier}` path parameter supports a contact ID, a phone number in E.164 format starting with `+`, or a Meta username without the leading `@`. Ambiguous numeric values are resolved as Meta usernames first and fall back to contact IDs only when no matching Meta username exists. Contact retrieve, list, and search responses do not include notes; use this endpoint to read contact notes. parameters: - $ref: '#/components/parameters/contactIdentifier-in_path_for_contact_note' responses: 200: description: Successfully retrieved contact notes. content: application/json: schema: type: array maxItems: 50 items: $ref: '#/components/schemas/ContactNote' 400: description: The contact identifier is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Create a contact note tags: - Contacts operationId: contact-note-create description: |- Creates one note for the contact and returns the created note. Leading and trailing whitespace is removed before storage. This operation does not use a client idempotency key; repeating the request creates another note with a different ID. parameters: - $ref: '#/components/parameters/contactIdentifier-in_path_for_contact_note' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactNoteWriteRequest' responses: 200: description: Successfully created the contact note. content: application/json: schema: $ref: '#/components/schemas/ContactNote' 400: description: The contact identifier or note content is invalid, or the contact already has 50 notes. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The contact does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /contact/notes/{noteId}: patch: summary: Update a contact note tags: - Contacts operationId: contact-note-update description: |- Updates one note in the current tenant by note ID and returns the updated note. Repeating the same request leaves the stored content unchanged, but an accepted update may still produce another `contact.note.updated` event. parameters: - $ref: '#/components/parameters/noteId-in_path_for_contact_note' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContactNoteWriteRequest' responses: 200: description: Successfully updated the contact note. content: application/json: schema: $ref: '#/components/schemas/ContactNote' 400: description: The contact note ID or content is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The contact note does not exist in the current tenant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete a contact note tags: - Contacts operationId: contact-note-delete description: |- Deletes one note in the current tenant by note ID and returns its snapshot before deletion. Deleting the same note again returns `404`; the operation does not use a client idempotency key. parameters: - $ref: '#/components/parameters/noteId-in_path_for_contact_note' responses: 200: description: Successfully deleted the contact note. content: application/json: schema: $ref: '#/components/schemas/ContactNote' 400: description: The contact note ID is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The contact note does not exist in the current tenant. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /contact/contacts/attributes: get: summary: List contact attributes tags: - Contacts operationId: contact-attributes-list description: Returns a list of all available contact attributes and their configurations. responses: 200: description: Successfully retrieved contact attributes. content: application/json: schema: type: array items: $ref: '#/components/schemas/ContactAttribute' /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 occurrence of a previously defined custom event. For contact events, identify the contact using one of a contact ID, phone number, or Meta username. requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomEventSendRequest' examples: byContactId: summary: By contact ID value: eventName: 'unique_event_name' objectId: '123456789' byPhoneNumber: summary: By phone number value: eventName: 'unique_event_name' contactPhoneNumber: '+16315551111' byUsername: summary: By Meta username value: eventName: 'unique_event_name' contactUsername: 'customer_demo' required: true responses: 200: description: Successfully accepted the event. Returns an empty JSON object. /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/businessAccounts/{wabaId}/automatic-creative-optimizations": get: summary: Retrieve WABA automatic creative optimizations tags: - WhatsApp Business Accounts operationId: whatsapp_waba-retrieve-automatic-creative-optimizations description: |- Retrieves current automatic creative optimization feature enrollment for a WhatsApp Business Account from Meta. This endpoint does not persist feature enrollment locally. If Meta returns `degrees_of_freedom_spec.data[0].creative_features_spec[0]` as an object, its string fields are returned as `creativeOptimizationFeatures` without feature-key filtering, status-value validation, or case normalization. If Meta returns success without a valid `creative_features_spec[0]` object, `creativeOptimizationFeatures` is returned as an empty object. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' responses: 200: description: Successfully retrieved current automatic creative optimization features. content: application/json: schema: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationRetrieveResponse' 400: description: Meta returned an error for the WABA automatic creative optimization query. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: You have no access to the requested WABA. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update WABA automatic creative optimizations tags: - WhatsApp Business Accounts operationId: whatsapp_waba-update-automatic-creative-optimizations description: |- Partially updates automatic creative optimization feature enrollment for a WhatsApp Business Account. Only submitted feature keys are updated. This endpoint does not persist feature enrollment locally and does not check whether the WABA has completed Meta MM Lite / ACO onboarding before forwarding the request to Meta. parameters: - name: wabaId in: path description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationUpdateRequest' responses: 200: description: Successfully updated submitted automatic creative optimization features. content: application/json: schema: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationUpdateResponse' 400: description: One or more request parameters are invalid, or Meta returned an error for the WABA automatic creative optimization update. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: You have no access to the requested WABA. 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/inboundMessages/{id}/typing: post: summary: Mark message as read and display a typing indicator with a JSON response operationId: whatsapp_inbound_message-typing tags: - WhatsApp Inbound Messages description: |- Marks an inbound message as read and displays a typing indicator so the WhatsApp user knows you are preparing a response. Messages marked as read display two blue check marks alongside their timestamp. The typing indicator is dismissed once you respond, or after 25 seconds, whichever comes first. Marking a message as read also marks earlier messages in the conversation as read. Repeating this request sends another typing-indicator request and refreshes the indicator; this endpoint does not provide an idempotency key. A successful request returns `WhatsappInboundMessageTypingResponse`. Errors reuse the standard `ErrorResponse`. 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 and displayed a typing indicator. content: application/json: schema: $ref: '#/components/schemas/WhatsappInboundMessageTypingResponse' 400: description: The inbound message cannot be used to send a typing indicator, or the upstream request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 401: description: Authentication failed because the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: You do not have access to the inbound message or permission to use this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested inbound message does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: description: Too many requests were sent in a given amount of time. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 500: description: The typing indicator could not be sent because of an internal or upstream error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/media/{phoneNumber}/upload": post: summary: Upload media operationId: whatsapp_media-upload tags: - WhatsApp Media description: |- Uploads media that can later be sent in WhatsApp messages. This endpoint interfaces with Meta's WhatsApp Business API media endpoints. All media files sent through this endpoint are encrypted and persist for 30 days. For supported media types and size limitations, please refer to [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). For more information, refer to [Meta's WhatsApp Cloud API Media documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media). Note that all interactive messages cannot send images, documents, videos, or audio using a Media ID in the header section. These elements must be sent using a link. parameters: - name: phoneNumber in: path description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format to use for the upload. required: true schema: type: string example: '+16315551111' requestBody: content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The media file to upload. Only one file is supported. If multiple files are uploaded, only the first file will be processed. required: true responses: 200: description: Successfully uploaded the media. content: application/json: schema: type: object properties: id: type: string description: The ID of the uploaded media that can be used in subsequent message requests. 400: description: Bad request. The file may be invalid or exceed size limits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /messenger/messages/sendDirectly: post: tags: - Messenger Messages summary: Send a Messenger text reply directly operationId: messenger_message-send-directly description: | Use your connected Facebook Page to send a one-to-one text reply. Meta determines reply eligibility; YCloud does not precheck the messaging window. Use a Tenant API Key. Developer App API Keys are not supported. Each call submits a new message. If a timeout occurs or you receive 502 MESSENGER_MESSAGE_RESULT_UNKNOWN, Meta may still have accepted the message. Do not automatically resubmit it. Check the saved message status using a returned YCloud or Meta message ID when available, or contact support to investigate. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MessengerTextSendRequest' example: from: '422500000000000' to: '100800000000000' type: text text: body: Hello, how can I help you? responses: '200': description: | Meta has accepted the submission. This receipt does not assert delivery or the record's current status. headers: YCloud-Request-ID: $ref: '#/components/headers/YCloudRequestId' content: application/json: schema: $ref: '#/components/schemas/MessengerSendReceipt' example: id: '1308528868252065792' metaMessageId: m_SAMPLE_001 from: '422500000000000' to: '100800000000000' status: accepted '400': $ref: '#/components/responses/MessengerBadRequest' '401': $ref: '#/components/responses/MessengerUnauthorized' '403': $ref: '#/components/responses/MessengerForbidden' '404': $ref: '#/components/responses/MessengerNotFound' '429': $ref: '#/components/responses/MessengerRateLimited' '500': $ref: '#/components/responses/MessengerInternalError' '502': $ref: '#/components/responses/MessengerResultUnknown' /messenger/messages/{id}: get: tags: - Messenger Messages summary: Retrieve an outbound message by its YCloud ID operationId: messenger_message-retrieve x-group-parameters: true description: | Retrieves a locally stored outbound record scoped by authenticated tenant and from. Does not query Meta or require the Page to remain connected. There is no inbound detail lookup or public message-history list in this phase. parameters: - name: id in: path required: true description: | YCloud outbound record ID as a positive decimal Long string, without signs or leading zeroes; never a Meta message ID. Nonmatching paths return 404; Long overflow returns 400. schema: type: string pattern: ^[1-9][0-9]{0,18}$ minLength: 1 example: '1308528868252065792' - $ref: '#/components/parameters/MessengerFromPage' responses: '200': description: | The current locally stored outbound record, including rejected or unknown submission results. Null optional fields are omitted. Query success is 200 even when the message was rejected. Includes active reactions reconstructed from saved events, or [] when none remain. Only interactions saved after reaction persistence was enabled are available. headers: YCloud-Request-ID: $ref: '#/components/headers/YCloudRequestId' content: application/json: schema: $ref: '#/components/schemas/MessengerMessage' example: id: '1308528868252065792' metaMessageId: m_SAMPLE_001 from: '422500000000000' to: '100800000000000' type: text text: body: Hello, how can I help you? status: read createTime: '2026-10-16T10:00:00.000Z' updateTime: '2026-10-16T10:00:03.000Z' sendTime: '2026-10-16T10:00:00.500Z' deliverTime: '2026-10-16T10:00:01.000Z' readTime: '2026-10-16T10:00:03.000Z' reactions: - psid: '100800000000000' reaction: love emoji: '❤' updateTime: '2026-10-16T10:00:04.000Z' '400': $ref: '#/components/responses/MessengerBadRequest' '401': $ref: '#/components/responses/MessengerUnauthorized' '403': $ref: '#/components/responses/MessengerForbidden' '404': $ref: '#/components/responses/MessengerNotFound' '429': $ref: '#/components/responses/MessengerRateLimited' '500': $ref: '#/components/responses/MessengerInternalError' /messenger/messages/retrieveByMetaMessageId: get: tags: - Messenger Messages summary: Retrieve an outbound message by its Meta message ID operationId: messenger_message-retrieve-by-meta-message-id x-group-parameters: true description: | The opaque Meta ID is a query parameter to avoid path-segment encoding problems. Use the YCloud message ID to retrieve records without a confirmed Meta ID. Only locally stored outbound messages are available. parameters: - $ref: '#/components/parameters/MessengerFromPage' - name: metaMessageId in: query required: true description: Nonblank opaque Meta message ID, URL encoded and matched exactly. schema: type: string minLength: 1 maxLength: 256 example: m_SAMPLE_001 responses: '200': description: | The current locally stored outbound record, including rejected or unknown submission results. Null optional fields are omitted. Query success is 200 even when the message was rejected. Includes active reactions reconstructed from saved events, or [] when none remain. Only interactions saved after reaction persistence was enabled are available. headers: YCloud-Request-ID: $ref: '#/components/headers/YCloudRequestId' content: application/json: schema: $ref: '#/components/schemas/MessengerMessage' example: id: '1308528868252065792' metaMessageId: m_SAMPLE_001 from: '422500000000000' to: '100800000000000' type: text text: body: Hello, how can I help you? status: read createTime: '2026-10-16T10:00:00.000Z' updateTime: '2026-10-16T10:00:03.000Z' sendTime: '2026-10-16T10:00:00.500Z' deliverTime: '2026-10-16T10:00:01.000Z' readTime: '2026-10-16T10:00:03.000Z' reactions: - psid: '100800000000000' reaction: love emoji: '❤' updateTime: '2026-10-16T10:00:04.000Z' '400': $ref: '#/components/responses/MessengerBadRequest' '401': $ref: '#/components/responses/MessengerUnauthorized' '403': $ref: '#/components/responses/MessengerForbidden' '404': $ref: '#/components/responses/MessengerNotFound' '429': $ref: '#/components/responses/MessengerRateLimited' '500': $ref: '#/components/responses/MessengerInternalError' /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. For endpoint selection, status synchronization, safe retries, and production controls, see [WhatsApp Messages API best practices](/en/api-reference/guides/whatsapp-platform/whatsapp-messages-api-best-practices). For custom utility content or template conversion, see [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). Utility Direct Send is in public beta and requires no allowlist or access application. 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' 400: description: Bad request. Invalid request parameters or malformed message payload. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. For example, the specified phone number or template is not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 422: description: Unprocessable entity. Business rule violation, such as template not in APPROVED status or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /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. For endpoint selection, status synchronization, safe retries, and production controls, see [WhatsApp Messages API best practices](/en/api-reference/guides/whatsapp-platform/whatsapp-messages-api-best-practices). For custom utility content or template conversion, see [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). Utility Direct Send is in public beta and requires no allowlist or access application. For ordinary WhatsApp `template` sends, the referenced template must be in `APPROVED` status. `ARCHIVED` templates cannot be sent as ordinary template messages. Direct Send conversion requires an existing template with supported components and does not require `APPROVED` status. 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' 400: description: Bad request. Invalid request parameters or malformed message payload. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. For example, the specified phone number or template is not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 422: description: Unprocessable entity. Business rule violation, such as template not in APPROVED status or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/messages/{wabaId}/messageSamples": post: summary: Submit a Direct Send message sample operationId: whatsapp_message-submit-sample tags: - WhatsApp Messages description: |- Submits one representative message sample to Meta and returns its detected category. We recommend submitting 3–4 samples that cover your utility use cases, one per request. This request does not send a message to a recipient. Utility Direct Send is in public beta. You do not need to join an allowlist or apply for access. Use an API key for the YCloud account that manages the specified WhatsApp Business Account. Samples support text, an interactive CTA URL button, or interactive reply buttons. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send) for limits, sending examples, and template conversion. parameters: - $ref: '#/components/parameters/wabaId-in_path' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageSamplesRequest' examples: text: summary: Text sample value: type: text text: body: Your order ORDER-123 is ready for pickup. cta_url: summary: CTA URL button sample value: type: interactive interactive: type: cta_url header: type: text text: Order update body: text: Your order ORDER-123 has shipped. Track its delivery below. footer: text: Thank you for your order. action: name: cta_url parameters: display_text: Track order url: https://example.com/orders/ORDER-123 reply_buttons: summary: Reply button sample value: type: interactive interactive: type: button body: text: Your appointment is tomorrow at 10 AM. Please confirm. action: buttons: - type: reply reply: id: confirm_appointment title: Confirm responses: 200: description: The sample was processed. Check its detected category before sending utility content. content: application/json: schema: $ref: '#/components/schemas/WhatsappMessageSamplesResponse' example: success: true category: UTILITY 400: description: Invalid sample or an error returned by Meta. Meta errors include `error.whatsappApiError`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 401: description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: The WhatsApp Business Account is not managed by your YCloud account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 429: description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 500: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/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/{businessPhoneNumber}/blockUsers": post: summary: Block users operationId: whatsapp_user-block tags: - WhatsApp Blocked Users description: |- Blocks users from sending messages to the specified WhatsApp business phone number. You must have management permissions for this business phone number. YCloud synchronizes the operation with Meta's WhatsApp platform. Provide at least one non-empty list: `users` for phone numbers in E.164 format or `userIds` for WhatsApp Business-scoped user IDs (BSUIDs). You can provide both lists, with at most 100 entries in total. Check `block_users.added_users` for successful results and `block_users.failed_users` for per-user failures. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappBlockUsersRequest' examples: phoneNumbers: summary: Block users by phone number value: users: - '+12025550101' userIds: summary: Block users by BSUID value: userIds: - 'US.123456789012345' responses: 200: description: Successfully processed the block request. Check the successful and failed user lists. content: application/json: schema: $ref: '#/components/schemas/WhatsappBlockUsersResponse' example: messaging_product: whatsapp block_users: added_users: - input: '+12025550101' wa_id: '12025550101' user_id: 'US.123456789012345' failed_users: [] 400: $ref: '#/components/responses/WhatsappBlockedUsersBadRequest' 401: $ref: '#/components/responses/WhatsappBlockedUsersUnauthorized' 403: $ref: '#/components/responses/WhatsappBlockedUsersForbidden' 429: $ref: '#/components/responses/WhatsappBlockedUsersRateLimited' 500: $ref: '#/components/responses/WhatsappBlockedUsersInternalError' "/whatsapp/{businessPhoneNumber}/unblockUsers": post: summary: Unblock users operationId: whatsapp_user-unblock tags: - WhatsApp Blocked Users description: |- Removes users from the blocklist so they can send messages to the specified WhatsApp business phone number again. You must have management permissions for this business phone number. YCloud synchronizes the operation with Meta's WhatsApp platform. Provide at least one non-empty list: `users` for phone numbers in E.164 format or `userIds` for WhatsApp Business-scoped user IDs (BSUIDs). You can provide both lists, with at most 100 entries in total. Check `block_users.removed_users` for successful results and `block_users.failed_users` for per-user failures. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappBlockUsersRequest' examples: phoneNumbers: summary: Unblock users by phone number value: users: - '+12025550101' userIds: summary: Unblock users by BSUID value: userIds: - 'US.123456789012345' responses: 200: description: Successfully processed the unblock request. Check the result for each user. content: application/json: schema: $ref: '#/components/schemas/WhatsappBlockUsersResponse' example: messaging_product: whatsapp block_users: removed_users: - input: '+12025550101' wa_id: '12025550101' user_id: 'US.123456789012345' failed_users: [] 400: $ref: '#/components/responses/WhatsappBlockedUsersBadRequest' 401: $ref: '#/components/responses/WhatsappBlockedUsersUnauthorized' 403: $ref: '#/components/responses/WhatsappBlockedUsersForbidden' 429: $ref: '#/components/responses/WhatsappBlockedUsersRateLimited' 500: $ref: '#/components/responses/WhatsappBlockedUsersInternalError' "/whatsapp/{businessPhoneNumber}/blockedUsers": get: summary: List blocked users operationId: whatsapp_user-list-blocked tags: - WhatsApp Blocked Users description: |- Lists blocked users for the specified WhatsApp business phone number. You must have management permissions for this business phone number. Results come from Meta's blocklist. Users do not need to exist in YCloud Contacts to appear in the results. The response includes the available phone and user IDs; it does not include contact details or block timestamps. Use cursor pagination. Omit the cursors for the first request, then pass `cursor.after` as `pageAfter` to request the next page, or `cursor.before` as `pageBefore` to request the previous page. x-group-parameters: true parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - name: limit in: query required: false description: Maximum number of items to request, from 1 to 100. Set this explicitly to control the page size. schema: type: integer minimum: 1 maximum: 100 example: 10 - name: pageAfter in: query description: The `cursor.after` value from the previous response. Omit it for the first page. schema: type: string - name: pageBefore in: query description: The `cursor.before` value from a response. Use it to request the previous page. schema: type: string responses: 200: description: Successfully retrieved the blocked users from Meta. content: application/json: schema: $ref: '#/components/schemas/WhatsappBlockedUsersPage' example: offset: 0 limit: 10 length: 1 items: - phoneNumber: '+12025550101' waId: '12025550101' userId: 'US.123456789012345' parentUserId: 'US.ENT.123456789012345' cursor: before: 'previous-page-cursor' after: 'next-page-cursor' 400: $ref: '#/components/responses/WhatsappBlockedUsersBadRequest' 401: $ref: '#/components/responses/WhatsappBlockedUsersUnauthorized' 403: $ref: '#/components/responses/WhatsappBlockedUsersForbidden' 429: $ref: '#/components/responses/WhatsappBlockedUsersRateLimited' 500: $ref: '#/components/responses/WhatsappBlockedUsersInternalError' "/whatsapp/{businessPhoneNumber}/groups": post: summary: Create a group operationId: whatsapp_group-create tags: - WhatsApp Groups description: |- Creates a WhatsApp group for the specified business phone number. The request is processed asynchronously. Use webhooks to receive the final group lifecycle result. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupCreateRequest' required: true responses: 200: description: The group creation request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupAsyncResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: List groups operationId: whatsapp_group-list tags: - WhatsApp Groups description: Returns a cursor-paginated list of active WhatsApp groups. x-group-parameters: true parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupLimit' - $ref: '#/components/parameters/groupBefore' - $ref: '#/components/parameters/groupAfter' responses: 200: description: Successfully retrieved groups. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupListResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}": get: summary: Retrieve a group operationId: whatsapp_group-retrieve tags: - WhatsApp Groups description: Retrieves a WhatsApp group. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' responses: 200: description: Successfully retrieved the group. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroup' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete a group operationId: whatsapp_group-delete tags: - WhatsApp Groups description: |- Deletes a WhatsApp group. The request is processed asynchronously. Use webhooks to receive the final group lifecycle result. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' responses: 200: description: The group deletion request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupAsyncResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}/inviteLink": get: summary: Retrieve a group invite link operationId: whatsapp_group-retrieve-invite-link tags: - WhatsApp Groups description: Retrieves the invite link for a WhatsApp group. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' responses: 200: description: Successfully retrieved the group invite link. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupInviteLink' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}/inviteLink/reset": post: summary: Reset a group invite link operationId: whatsapp_group-reset-invite-link tags: - WhatsApp Groups description: Resets and returns the invite link for a WhatsApp group. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' responses: 200: description: Successfully reset the group invite link. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupInviteLink' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/inviteLink/messages": post: summary: Send a group invite link message operationId: whatsapp_group-send-invite-link-message tags: - WhatsApp Groups description: |- Sends a WhatsApp template message that contains the group invite link parameter. This sends a message to an individual WhatsApp user. It does not send a message into the group conversation. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupInviteLinkMessageRequest' required: true responses: 200: description: The message request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappMessage' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests": get: summary: List group join requests operationId: whatsapp_group-list-join-requests tags: - WhatsApp Groups description: Returns a cursor-paginated list of pending join requests for a WhatsApp group. x-group-parameters: true parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' - $ref: '#/components/parameters/groupLimit' - $ref: '#/components/parameters/groupBefore' - $ref: '#/components/parameters/groupAfter' responses: 200: description: Successfully retrieved group join requests. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupJoinRequestListResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests/approve": post: summary: Approve group join requests operationId: whatsapp_group-approve-join-requests tags: - WhatsApp Groups description: Approves one or more pending join requests for a WhatsApp group. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupJoinRequestActionRequest' required: true responses: 200: description: Successfully processed the join request approval. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupJoinRequestActionResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests/reject": post: summary: Reject group join requests operationId: whatsapp_group-reject-join-requests tags: - WhatsApp Groups description: Rejects one or more pending join requests for a WhatsApp group. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupJoinRequestActionRequest' required: true responses: 200: description: Successfully processed the join request rejection. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupJoinRequestActionResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/groups/{groupId}/participants/remove": post: summary: Remove group participants operationId: whatsapp_group-remove-participants tags: - WhatsApp Groups description: |- Removes one or more participants from a WhatsApp group. The request is processed asynchronously. Use webhooks to receive the final participants update result. x-codeSamples: - lang: curl label: Remove by WhatsApp user ID source: | curl --request POST \ --url https://api.ycloud.com/v2/whatsapp/groups/{groupId}/participants/remove \ --header 'Content-Type: application/json' \ --header 'X-API-Key: ' \ --data '{"participants":[{"user":"16315551111"}]}' - lang: python label: Remove by WhatsApp user ID source: | import requests response = requests.post( "https://api.ycloud.com/v2/whatsapp/groups/{groupId}/participants/remove", headers={"X-API-Key": ""}, json={"participants": [{"user": "16315551111"}]}, ) response.raise_for_status() - lang: javascript label: Remove by WhatsApp user ID source: | const response = await fetch( "https://api.ycloud.com/v2/whatsapp/groups/{groupId}/participants/remove", { method: "POST", headers: { "Content-Type": "application/json", "X-API-Key": "", }, body: JSON.stringify({ participants: [{ user: "16315551111" }], }), }, ); parameters: - $ref: '#/components/parameters/groupId-in_path' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupRemoveParticipantsRequest' example: participants: - user: '16315551111' required: true responses: 200: description: The participant removal request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupAsyncResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/{businessPhoneNumber}/groups/{groupId}/settings": patch: summary: Update group settings operationId: whatsapp_group-update-settings tags: - WhatsApp Groups description: |- Updates a WhatsApp group's settings, such as subject or description. The request is processed asynchronously. Use webhooks to receive the final settings update result. parameters: - $ref: '#/components/parameters/businessPhoneNumber-in_path' - $ref: '#/components/parameters/groupId-in_path' requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupUpdateSettingsRequest' multipart/form-data: schema: type: object description: Provide at least one setting. You can update text settings and the profile picture in the same request. properties: subject: type: string maxLength: 128 description: New group subject. description: type: string maxLength: 2048 description: New group description. profile_picture_file: type: string format: binary description: JPEG group profile picture. required: true responses: 200: description: The group settings update request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappGroupAsyncResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/calls/connect: post: summary: Connect a call operationId: whatsapp_call-connect tags: - WhatsApp Calling description: |- Initiates a WhatsApp call connection. Establishes the initial connection for a WhatsApp call by providing SDP offer information. This endpoint is used for business-initiated calling scenarios. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingConnectRequest' required: true responses: 200: description: The call connection request is successfully accepted. content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/calls/preAccept: post: summary: Pre-accept a call operationId: whatsapp_call-pre-accept tags: - WhatsApp Calling description: |- Pre-accepts an inbound WhatsApp call. Pre-accepting calls allows the calling media connection to be established before attempting to send call media through the connection. This facilitates faster connection times and avoids audio clipping issues. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingPreAcceptRequest' required: true responses: 200: description: The call pre-accept request is successfully processed. content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/calls/accept: post: summary: Accept a call operationId: whatsapp_call-accept tags: - WhatsApp Calling description: |- Accepts an inbound WhatsApp call. Once the WebRTC connection is made, this endpoint is used to accept the call. Media will begin flowing immediately since the connection was established prior to call connect. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingPreAcceptRequest' required: true responses: 200: description: The call accept request is successfully processed. content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/calls/terminate: post: summary: Terminate a call operationId: whatsapp_call-terminate tags: - WhatsApp Calling description: |- Terminates an active WhatsApp call. Both the business or the WhatsApp user can terminate the call at any time. This endpoint is used by the business to end the call. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingTerminateRequest' required: true responses: 200: description: The call termination request is successfully processed. content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/calls/reject: post: summary: Reject a call operationId: whatsapp_call-reject tags: - WhatsApp Calling description: |- Rejects an inbound WhatsApp call. This endpoint is used to reject an incoming call from a WhatsApp user. The call will be terminated on the WhatsApp user side with appropriate notification. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingTerminateRequest' required: true responses: 200: description: The call rejection request is successfully processed. content: application/json: schema: $ref: '#/components/schemas/WhatsappCallingResponse' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/calls/media/{mediaAssetId}: get: summary: Download call media operationId: whatsapp_call-download-media tags: - WhatsApp Calling description: |- Downloads an available recording or transcription generated for an API-sourced WhatsApp call. Media can be downloaded only by the owning tenant for 30 days from its creation time. Requests without a Range header or with a blank Range header return the complete file as a download attachment with HTTP 200. A non-empty Range header is rejected with HTTP 400 because byte-range downloads are not supported. parameters: - name: mediaAssetId in: path required: true description: YCloud call media asset ID received in a recording or transcription webhook. schema: type: string example: '66b1f0c2e4b05c2d8f1a3b47' responses: 200: description: The complete recording or transcription file. headers: Accept-Ranges: description: Always `none`; byte-range downloads are not supported. schema: type: string enum: - none Content-Disposition: description: Download attachment filename. Recordings use the `.ogg` extension and transcriptions use the `.json` extension. schema: type: string example: attachment; filename="calling-media-66b1f0c2e4b05c2d8f1a3b47.ogg" Content-Length: schema: type: integer format: int64 content: audio/ogg: schema: type: string format: binary application/json: schema: type: string format: binary 400: description: The request includes a non-empty Range header. Byte-range downloads are not supported. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The media asset does not exist, is not available, is expired, or does not belong to the authenticated tenant. 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}/displayName": patch: summary: Update a phone number display name operationId: whatsapp_phone_number-update-displayName tags: - WhatsApp Phone Numbers description: |- Updates a WhatsApp business phone number display name. 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/WhatsappPhoneNameUpdateRequest' required: true responses: 200: description: Successfully updated the object. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNameUpdateResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername": get: summary: Retrieve a phone number business username operationId: whatsapp_phone_number-retrieve-business-username tags: - WhatsApp Phone Numbers description: |- Retrieves the Business Username state for a WhatsApp business phone number. The response reflects YCloud's latest known phone number state. If the phone number has no locally stored Business Username state, YCloud may sync the current username state from Meta before returning the response. 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/WhatsappBusinessUsername' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update a phone number business username operationId: whatsapp_phone_number-update-business-username tags: - WhatsApp Phone Numbers description: |- Requests a Business Username update for a WhatsApp business phone number. The requested username may require Meta review before it becomes active. If Meta accepts or reserves the request for review, the response status is usually `reserved`; `pending_review` is kept only as a legacy compatibility value. If Meta returns an error, YCloud returns the error and does not change the stored Business Username state. The `username` value is a plain username without `@`. YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission. 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/WhatsappBusinessUsernameUpdateRequest' required: true responses: 200: description: Successfully submitted the update request. content: application/json: schema: $ref: '#/components/schemas/WhatsappBusinessUsername' 400: description: Bad request. Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: Delete a phone number business username operationId: whatsapp_phone_number-delete-business-username tags: - WhatsApp Phone Numbers description: |- Deletes the active Business Username for a WhatsApp business phone number. This operation removes the currently active Business Username. It does not cancel or remove a reserved Business Username request. If a reserved request still exists after deletion, the returned `businessUsernameStatus` remains `reserved`; otherwise it becomes `not_set`. 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 deleted the business username. content: application/json: schema: $ref: '#/components/schemas/WhatsappBusinessUsernameDeleteResult' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername/suggestions": get: summary: Retrieve phone number business username suggestions operationId: whatsapp_phone_number-retrieve-business-username-suggestions tags: - WhatsApp Phone Numbers description: |- Retrieves reserved Business Username suggestions for a WhatsApp business phone number. The response flattens Meta username suggestions into a string array. If no suggestions are available, `data` is an empty array. 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 suggestions. content: application/json: schema: $ref: '#/components/schemas/WhatsappBusinessUsernameSuggestions' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}": delete: summary: Delete a Meta contact book entry operationId: whatsapp_phone_number-delete-contact-book-entry tags: - WhatsApp Phone Numbers description: |- Deletes the Meta contact book entry that associates a WhatsApp business phone number with a customer's WhatsApp Business-scoped user ID (BSUID). Only standard BSUIDs such as `US.11815799212886844830` are supported. Parent BSUIDs such as `US.ENT.11815799212886844830` are not supported. The BSUID must be scoped to the same Meta business portfolio as the phone number. The specified WABA must belong to the authenticated YCloud account and be available, and the phone number must be bound to that WABA in YCloud. Use the YCloud account API key in the `X-API-Key` header. Developer App API keys are not supported and return HTTP 403. An HTTP 200 response always has `success=true`. `deleted=true` means Meta reports that it deleted a matching contact book entry. `deleted=false` means Meta processed the request but found no matching entry to delete. This operation does not delete or modify YCloud Contact, message, or BSUID business records, and it does not bypass Meta's 30-day caching behavior. A later WhatsApp interaction between the same business phone number and customer may cause Meta to create the entry again. 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, bound to the specified WABA in YCloud. When constructing the path manually, URL-encode the leading `+` as `%2B`. required: true schema: type: string example: '+16315551111' - name: bsuid in: path description: Standard WhatsApp Business-scoped user ID (BSUID) from the same Meta business portfolio as the phone number. Parent BSUIDs containing `.ENT.` are not supported. required: true schema: type: string pattern: '^[A-Z]{2}\.[0-9]+$' example: 'US.11815799212886844830' responses: 200: description: The delete request was processed successfully. content: application/json: schema: $ref: '#/components/schemas/WhatsappContactBookEntryDeleteResult' 400: description: One or more path parameters are invalid, or Meta returned HTTP 400 for the delete request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: The API key is not permitted to call this endpoint, the specified WABA is unavailable to the authenticated YCloud account, the phone number is unavailable or not bound to that WABA in YCloud, or Meta returned HTTP 403. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: Meta returned HTTP 404 for the phone number's upstream contact book resource. This status is not used when no matching contact book entry exists; that case returns HTTP 200 with `deleted=false`. 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/phoneNumbers/{wabaId}/{phoneNumber}/settings": get: summary: Retrieve phone number settings operationId: whatsapp_phone_number-retrieve-settings tags: - WhatsApp Phone Numbers description: |- Retrieves phone number specific 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: '+6283138205170' - name: type in: query required: false description: Set to `capture` to retrieve only Calling recording and transcription capture settings. Omit it or set it to `calling` to retrieve the existing Calling settings response. schema: type: string enum: - capture - calling responses: 200: description: Successfully retrieved the phone number settings. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberSettings' examples: callingSettings: summary: Existing Calling settings response value: calling: id: "19213232132" status: "ENABLED" iconVisibility: "DEFAULT" captureSettings: summary: Capture settings response when `type=capture` value: capture: recordingEnabled: true transcriptionEnabled: true purpose: "quality_assurance" announcementLanguage: "en_US" 400: description: Bad request. The settings type is unsupported. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Save phone number settings operationId: whatsapp_phone_number-save-settings tags: - WhatsApp Phone Numbers description: |- Saves phone number specific settings. Send `calling`, `capture`, or both. When both are supplied, the service independently attempts both saves after shared authorization and phone-number validation. A failure in either branch does not prevent the other branch from being attempted. If either branch fails, the existing error response is returned and the other setting may already have been saved. 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: '+6283138205150' requestBody: description: Phone number settings to save. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberSettings' examples: callingSettings: summary: Save existing Calling settings value: calling: status: "ENABLED" iconVisibility: "DEFAULT" captureSettings: summary: Save Capture settings value: capture: recordingEnabled: true transcriptionEnabled: true purpose: "quality_assurance" announcementLanguage: "en_US" callingAndCaptureSettings: summary: Save Calling and Capture settings together value: calling: status: "ENABLED" iconVisibility: "DEFAULT" capture: recordingEnabled: true transcriptionEnabled: true purpose: "quality_assurance" announcementLanguage: "en_US" required: true responses: 200: description: Successfully saved the phone number settings. content: application/json: schema: $ref: '#/components/schemas/WhatsappPhoneNumberSettings' examples: callingSettings: summary: Existing Calling settings response value: calling: id: "19213232132" status: "ENABLED" iconVisibility: "DEFAULT" captureSettings: summary: Capture settings response value: capture: recordingEnabled: true transcriptionEnabled: true purpose: "quality_assurance" announcementLanguage: "en_US" callingAndCaptureSettings: summary: Calling and Capture settings response value: calling: id: "19213232132" status: "ENABLED" iconVisibility: "DEFAULT" capture: recordingEnabled: true transcriptionEnabled: true purpose: "quality_assurance" announcementLanguage: "en_US" 400: description: Bad request. A Calling or Capture setting is invalid. For a combined request, the other setting may already have been saved. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. Include `limited_time_offer` only in a component whose `type` is `LIMITED_TIME_OFFER`. Other component types do not require this object or its `text` field. requestBody: content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplateCreateRequest' example: wabaId: '' name: order_confirmation language: en_US category: UTILITY components: - type: BODY text: 'Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}.' example: body_text: - - ORDER-5555 - 99 USD - February 25, 2023 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. Archived templates are included when they match the query. Use `filter.status=ARCHIVED` to list archived templates explicitly. 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. required: false schema: type: string example: en - name: filter.status in: query description: |- Comma-separated template statuses to filter by. Supported values include `PENDING`, `REJECTED`, `APPROVED`, `PAUSED`, `DISABLED`, `ARCHIVED`, `IN_APPEAL`, and `DELETED`. required: false schema: type: string example: APPROVED,ARCHIVED 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. required: true schema: type: string example: en 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. Only templates in `APPROVED`, `REJECTED`, or `PAUSED` status can be edited. `ARCHIVED` templates cannot be edited. 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. required: true schema: type: string example: en 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. The returned template `status` may be `ARCHIVED`. 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. required: true schema: type: string example: en 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' /whatsapp/templates/analytics: post: summary: Retrieve WhatsApp template analytics operationId: whatsapp_template-analytics tags: - WhatsApp Templates description: |- Returns daily YCloud message metrics and, when available, Meta Template Insights for one WhatsApp template. Authenticate with `X-API-Key`. `analyticsStatus` describes Meta Template Insights only; it does not describe YCloud metrics. Dates are interpreted in the WABA timezone, both boundaries are inclusive, and the range must contain between 1 and 90 calendar days. The selected template must currently exist under the requested WABA. REST resolves and validates the template before querying any statistics. A missing template returns `404`, a template that belongs to another WABA returns `403`, and a template lookup failure returns `500`; none of these errors returns partial statistics. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplateAnalyticsRequest' responses: 200: description: Successfully retrieved template analytics. content: application/json: schema: $ref: '#/components/schemas/WhatsappTemplateAnalytics' 400: description: The request parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: The WABA or template is not accessible. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The WABA does not exist, or the template selected by either supported selector was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 500: description: A required dependency, such as current template resolution or YCloud message statistics, could not be retrieved. Meta Template Insights failures after successful template validation are returned as a 200 response with analyticsStatus set to ERROR. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /whatsapp/flows: post: summary: Create a flow operationId: whatsapp_flow-create tags: - WhatsApp Flows description: |- Creates a new WhatsApp Flow. New Flows are by default created in DRAFT state. You can create a new published Flow in single request by specifying flowJson and publish parameters. requestBody: content: application/json: schema: type: object required: - wabaId - name - categories properties: wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' name: type: string description: Flow name. example: 'My first flow' categories: type: array description: Flow categories. items: $ref: '#/components/schemas/WhatsappFlowCategory' flowJson: type: string description: JSON string of the Flow structure. example: '{"version":"5.0","screens":[{"id":"WELCOME_SCREEN","layout":{"type":"SingleColumnLayout","children":[{"type":"TextHeading","text":"Hello World"},{"type":"Footer","label":"Complete","on-click-action":{"name":"complete","payload":{}}}]},"title":"Welcome","terminal":true,"success":true,"data":{}}]}' publish: type: boolean description: If true, the Flow will be created in PUBLISHED state. default: false cloneFlowId: type: string description: ID of source Flow to clone. You must have permission to access the specified Flow. example: 'flow-id-to-clone' endpointUri: type: string description: The endpoint URI for the Flow. example: 'https://example.com/flow-endpoint' required: true responses: 200: description: Successfully created a flow. content: application/json: schema: type: object properties: id: type: string description: The ID of the created Flow. example: 'flow-1' success: type: boolean description: Whether the operation was successful. example: true 400: description: Bad request. The Flow may be invalid. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: false validationErrors: type: array description: List of validation errors. items: $ref: '#/components/schemas/WhatsappFlowValidationError' get: summary: List flows operationId: whatsapp_flow-list tags: - WhatsApp Flows description: |- Returns a list of WhatsApp Flows under a WhatsApp Business Account (WABA). parameters: - name: wabaId in: query description: WhatsApp Business Account ID. required: true schema: type: string example: 'whatsapp-business-account-id' responses: 200: description: Successfully retrieved the list of flows. content: application/json: schema: type: object properties: items: type: array description: List of flows. items: $ref: '#/components/schemas/WhatsappListFlowItem' "/whatsapp/flows/{flowId}/metadata": patch: summary: Update flow metadata operationId: whatsapp_flow-update-metadata tags: - WhatsApp Flows description: |- Updates a WhatsApp Flow's metadata (name or categories). parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' requestBody: content: application/json: schema: type: object properties: name: type: string description: Flow name. example: 'New flow name' categories: type: array description: Flow categories. items: $ref: '#/components/schemas/WhatsappFlowCategory' endpointUri: type: string description: The endpoint URI for the Flow. example: 'https://example.com/flow-endpoint' required: true responses: 200: description: Successfully updated the flow metadata. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: true "/whatsapp/flows/{flowId}/assets": patch: summary: Update flow structure operationId: whatsapp_flow-update-structure tags: - WhatsApp Flows description: |- Updates a WhatsApp Flow's structure. Note that the file must be attached as form-data. parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' requestBody: content: multipart/form-data: schema: type: object required: - flowJson properties: flowJson: type: string format: binary description: JSON file containing the Flow structure. required: true responses: 200: description: Successfully updated the flow structure. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: true 400: description: Bad request. The Flow structure may be invalid. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: false validationErrors: type: array description: List of validation errors. items: $ref: '#/components/schemas/WhatsappFlowValidationError' "/whatsapp/flows/{flowId}": delete: summary: Delete a flow operationId: whatsapp_flow-delete tags: - WhatsApp Flows description: |- Deletes a WhatsApp Flow. Only Flows in DRAFT status can be deleted. parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' responses: 200: description: Successfully deleted the flow. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: true get: summary: Retrieve a flow operationId: whatsapp_flow-retrieve tags: - WhatsApp Flows description: |- Retrieves a WhatsApp Flow's details. parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' responses: 200: description: Successfully retrieved the flow. content: application/json: schema: $ref: '#/components/schemas/WhatsappFlow' "/whatsapp/flows/{flowId}/publish": post: summary: Publish a flow operationId: whatsapp_flow-publish tags: - WhatsApp Flows description: |- Updates the status of the Flow to "PUBLISHED". You can either edit this flow in the future and turn it back to the "DRAFT" state, or create a new flow by specifying the existing Flow ID as the cloneFlowId parameter. parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' responses: 200: description: Successfully published the flow. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: true "/whatsapp/flows/{flowId}/deprecate": post: summary: Deprecate a flow operationId: whatsapp_flow-deprecate tags: - WhatsApp Flows description: |- Marks a published Flow as deprecated. Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated. parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' responses: 200: description: Successfully deprecated the flow. content: application/json: schema: type: object properties: success: type: boolean description: Whether the operation was successful. example: true "/whatsapp/flows/{flowId}/preview": get: summary: generate a web preview URL with this flow. operationId: whatsapp_flow-preview tags: - WhatsApp Flows description: |- In order to visualize the Flows created, you can generate a web preview URL with this request. **The preview URL is public and can be shared with different stakeholders to visualize the Flow.**. parameters: - name: flowId in: path description: Flow ID. required: true schema: type: string example: 'flow-1' - name: invalidate in: query description: the link will expire in 30 days in default, or if you set with invalidate=true which will generate a new link. required: false schema: type: boolean example: false responses: 200: description: Successfully generate the flow preview url. content: application/json: schema: $ref: '#/components/schemas/WhatsappFlowPreviewUrl' /metaBusinessAgents/{entityId}/settings: get: summary: Retrieve Meta Business Agent settings operationId: meta_business_agent-settings-retrieve tags: - Meta Business Agent description: Retrieves the settings associated with the specified Meta Business Agent entity. x-group-parameters: true parameters: - $ref: '#/components/parameters/metaBusinessAgentEntityId-in_path' - name: agent_id in: query required: false description: Optional Meta Agent ID used to select one settings record. schema: type: string responses: 200: description: Successfully retrieved the settings. content: application/json: schema: type: array items: $ref: '#/components/schemas/MetaBusinessAgentSettings' 400: $ref: '#/components/responses/MetaBusinessAgentBadRequest' 401: $ref: '#/components/responses/MetaBusinessAgentUnauthorized' 403: $ref: '#/components/responses/MetaBusinessAgentForbidden' 429: $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' 500: $ref: '#/components/responses/MetaBusinessAgentServerError' 502: $ref: '#/components/responses/MetaBusinessAgentBadGateway' put: summary: Replace Meta Business Agent settings operationId: meta_business_agent-settings-replace tags: - Meta Business Agent description: |- Replaces the supplied settings fields. Omitting `never_say_phrases` preserves the current list, an empty list clears it, and a non-empty list fully replaces it. parameters: - $ref: '#/components/parameters/metaBusinessAgentEntityId-in_path' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MetaBusinessAgentSettingsReplaceRequest' responses: 200: description: Successfully replaced the settings. content: application/json: schema: $ref: '#/components/schemas/MetaBusinessAgentSettings' 400: $ref: '#/components/responses/MetaBusinessAgentBadRequest' 401: $ref: '#/components/responses/MetaBusinessAgentUnauthorized' 403: $ref: '#/components/responses/MetaBusinessAgentForbidden' 429: $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' 500: $ref: '#/components/responses/MetaBusinessAgentServerError' 502: $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/budgets: get: summary: Retrieve Meta Business Agent budgets operationId: meta_business_agent-budget-retrieve tags: - Meta Business Agent description: Retrieves the complete Budget collection for the Business Manager associated with the specified WhatsApp Business Phone Number ID. parameters: - $ref: '#/components/parameters/metaBusinessAgentEntityId-in_path' responses: 200: description: Successfully retrieved the Budget collection. content: application/json: schema: $ref: '#/components/schemas/MetaBusinessAgentBudgetResponse' 400: $ref: '#/components/responses/MetaBusinessAgentBadRequest' 401: $ref: '#/components/responses/MetaBusinessAgentUnauthorized' 403: $ref: '#/components/responses/MetaBusinessAgentForbidden' 404: $ref: '#/components/responses/MetaBusinessAgentNotFound' 422: $ref: '#/components/responses/MetaBusinessAgentUnprocessableEntity' 429: $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' 500: $ref: '#/components/responses/MetaBusinessAgentServerError' 502: $ref: '#/components/responses/MetaBusinessAgentBadGateway' put: summary: Replace Meta Business Agent budgets operationId: meta_business_agent-budget-replace tags: - Meta Business Agent description: |- Replaces the complete Budget collection. Include both `token` and `ai_turn` entries that should remain. An empty collection removes all limits and restores unlimited usage. parameters: - $ref: '#/components/parameters/metaBusinessAgentEntityId-in_path' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MetaBusinessAgentBudgetReplaceRequest' responses: 200: description: Successfully replaced the Budget collection. content: application/json: schema: $ref: '#/components/schemas/MetaBusinessAgentBudgetResponse' 400: $ref: '#/components/responses/MetaBusinessAgentBadRequest' 401: $ref: '#/components/responses/MetaBusinessAgentUnauthorized' 403: $ref: '#/components/responses/MetaBusinessAgentForbidden' 404: $ref: '#/components/responses/MetaBusinessAgentNotFound' 422: $ref: '#/components/responses/MetaBusinessAgentUnprocessableEntity' 429: $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' 500: $ref: '#/components/responses/MetaBusinessAgentServerError' 502: $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/conversationTurns: get: summary: Retrieve Meta Business Agent conversation turns operationId: meta_business_agent-conversation-turns-retrieve tags: - Meta Business Agent description: |- Retrieves conversation turns for one WhatsApp user. `entityId` is the WhatsApp Business Phone Number ID. Timestamp boundaries are inclusive and use Unix epoch milliseconds. Supply at most one of `before` and `after`; cursors are opaque. Continue pagination while `paging.next` is present, including when the current `data` array is empty. x-group-parameters: true parameters: - $ref: '#/components/parameters/metaBusinessAgentEntityId-in_path' - name: user_phone_number in: query required: true description: WhatsApp user phone number including the country code, with digits only and no leading `+`, spaces, or separators. schema: type: string pattern: '^[1-9][0-9]{1,14}$' example: '14155550123' - name: start_timestamp_ms in: query required: false description: Inclusive start time as Unix epoch milliseconds. schema: type: integer format: int64 minimum: 0 - name: end_timestamp_ms in: query required: false description: Inclusive end time as Unix epoch milliseconds. Must be greater than or equal to `start_timestamp_ms` when both are supplied. schema: type: integer format: int64 minimum: 0 - name: before in: query required: false description: Opaque backward-pagination cursor. Do not combine with `after`. schema: type: string minLength: 1 - name: after in: query required: false description: Opaque forward-pagination cursor. Do not combine with `before`. schema: type: string minLength: 1 - name: limit in: query required: false description: Maximum number of conversation turns to return. schema: type: integer format: int32 minimum: 1 responses: 200: description: Successfully retrieved conversation turns. content: application/json: schema: $ref: '#/components/schemas/MetaBusinessAgentConversationTurnPage' 400: $ref: '#/components/responses/MetaBusinessAgentBadRequest' 401: $ref: '#/components/responses/MetaBusinessAgentUnauthorized' 403: $ref: '#/components/responses/MetaBusinessAgentForbidden' 404: $ref: '#/components/responses/MetaBusinessAgentNotFound' 422: $ref: '#/components/responses/MetaBusinessAgentUnprocessableEntity' 429: $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' 500: $ref: '#/components/responses/MetaBusinessAgentServerError' 502: $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/connectors: get: operationId: meta-business-agent-list-connectors summary: List Connectors description: Lists the external API connectors configured for the agent, including their endpoint and authentication definitions. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. responses: '200': description: Operation completed successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' post: operationId: meta-business-agent-create-connector summary: Create Connector description: Creates an external API connector with its name, description, base URL, authentication type, and optional user-auth or certificate configuration. For MCP, base_url is the remote MCP server address and authentication uses the existing auth fields. Creating a connector does not guarantee discovered tools are immediately ready; inspect mcp_tool_sync when returned. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. responses: '201': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicCreateConnectorRequest' /metaBusinessAgents/{entityId}/connectors/{connectorId}: get: operationId: meta-business-agent-get-connector summary: Get Connector description: Retrieves the external API connector identified by `connectorId`. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' patch: operationId: meta-business-agent-update-connector summary: Update Connector description: Updates the connector definition identified by `connectorId`, including its descriptive, endpoint, authentication, and certificate requirement fields. connector_protocol cannot be changed after creation. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicUpdateConnectorRequest' delete: operationId: meta-business-agent-delete-connector summary: Delete Connector description: Deletes the external API connector identified by `connectorId` from the agent configuration. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '204': description: Operation completed successfully. '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/connectors/{connectorId}/refreshMCPTools: post: operationId: meta-business-agent-refresh-connector-mcp-tools summary: Refresh MCP Connector Tools description: Triggers Meta to rediscover the MCP tools exposed by this connector. The request has no body. A successful HTTP 200 returns the current Connector; inspect mcp_tool_sync.status because remote discovery or provisioning failure can still return HTTP 200 with status ERROR. This operation has no idempotency key. Do not retry it automatically; after a timeout, query the Connector because the refresh outcome is uncertain. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Meta Connector ID returned by the Connector API. This is not a YCloud local Connector UUID. responses: '200': description: Refresh request completed. Inspect mcp_tool_sync.status for discovery outcome. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/connectors/{connectorId}/logs: get: operationId: meta-business-agent-list-connector-logs summary: List Connector Logs description: Retrieves third-party connector error logs for the requested time and tool filters. It can return individual entries, aggregated failure patterns, and optional success-rate or latency statistics; Meta limits the query window and retention to seven days. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. - name: start_time in: query required: false schema: type: integer format: int64 - name: end_time in: query required: false schema: type: integer format: int64 - name: limit in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 1000 - name: tool_id in: query required: false schema: type: string description: Meta Connector Tool ID。 - name: include_stats in: query required: false schema: type: boolean - name: summary_only in: query required: false schema: type: boolean - name: top_n in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 50 responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorLogStatsDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/connectors/{connectorId}/credentials/apiKey: put: operationId: meta-business-agent-upsert-connector-api-key summary: Upsert Connector Api Key description: Sets or rotates the API key credentials for `connectorId`. Existing API key credentials are replaced, and the updated connector is returned. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicUpsertConnectorApiKeyRequest' /metaBusinessAgents/{entityId}/connectors/{connectorId}/credentials/certificate: put: operationId: meta-business-agent-upsert-connector-certificate summary: Upsert Connector Certificate description: Uploads or rotates the mTLS client certificate, private key, and optional CA certificate for `connectorId`, then returns the updated connector. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicUpsertConnectorCertificateRequest' /metaBusinessAgents/{entityId}/connectors/{connectorId}/credentials/oauth: put: operationId: meta-business-agent-upsert-connector-o-auth summary: Upsert Connector O Auth description: Sets or rotates the OAuth 2.0 client credentials for `connectorId`. Existing OAuth credentials are replaced, and the updated connector is returned. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicUpsertConnectorOAuthRequest' /metaBusinessAgents/{entityId}/connectors/{connectorId}/tools: get: operationId: meta-business-agent-list-connector-tools summary: List Connector Tools description: Lists the tool operations defined under `connectorId` that the agent can use to call the external service. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/ConnectorToolDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' post: operationId: meta-business-agent-create-connector-tool summary: Create Connector Tool description: 'Creates a tool under `connectorId`, including its agent-facing description, outbound request definition, and optional user-auth extraction configuration. transformation_spec is optional: omit it to preserve an existing transformation on update, send null to delete it, or send an object to set it.' tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. responses: '201': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorToolDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicCreateConnectorToolRequest' examples: omitted: summary: Preserve transformation on update value: name: get_order description: Gets an order request_definition: method: GET path: /orders user_auth_required: false clear: summary: Delete transformation on update value: name: get_order description: Gets an order request_definition: method: GET path: /orders user_auth_required: false transformation_spec: null configured: summary: Set an ordered transformation value: name: get_order description: Gets an order request_definition: method: GET path: /orders user_auth_required: false transformation_spec: version: 1 steps: - kind: allowlist target: null params: '{"paths":["order.id","order.status"]}' /metaBusinessAgents/{entityId}/connectors/{connectorId}/tools/{toolId}: get: operationId: meta-business-agent-get-connector-tool summary: Get Connector Tool description: Retrieves the connector tool identified by `toolId`, including its outbound request and user-auth definitions. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. - name: toolId in: path required: true schema: type: string description: Connector tool resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorToolDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' patch: operationId: meta-business-agent-update-connector-tool summary: Update Connector Tool description: 'Updates the name, description, outbound request definition, and user-auth configuration of the connector tool identified by `toolId`. transformation_spec is optional: omit it to preserve an existing transformation on update, send null to delete it, or send an object to set it.' tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. - name: toolId in: path required: true schema: type: string description: Connector tool resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorToolDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicUpdateConnectorToolRequest' examples: omitted: summary: Preserve transformation on update value: name: get_order description: Gets an order request_definition: method: GET path: /orders user_auth_required: false clear: summary: Delete transformation on update value: name: get_order description: Gets an order request_definition: method: GET path: /orders user_auth_required: false transformation_spec: null configured: summary: Set an ordered transformation value: name: get_order description: Gets an order request_definition: method: GET path: /orders user_auth_required: false transformation_spec: version: 1 steps: - kind: allowlist target: null params: '{"paths":["order.id","order.status"]}' delete: operationId: meta-business-agent-delete-connector-tool summary: Delete Connector Tool description: Deletes the tool identified by `toolId` from `connectorId`. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. - name: toolId in: path required: true schema: type: string description: Connector tool resource ID. responses: '204': description: Operation completed successfully. '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' /metaBusinessAgents/{entityId}/connectors/{connectorId}/tools/{toolId}/runs: post: operationId: meta-business-agent-run-connector-tool summary: Run Connector Tool description: Executes the connector tool identified by `toolId` with the supplied `input` and returns the upstream API result exposed by Meta. tags: - Meta Business Agent parameters: - name: entityId in: path required: true schema: type: string description: WhatsApp Business Phone Number ID that owns the Meta Business Agent. - name: connectorId in: path required: true schema: type: string description: Connector resource ID. - name: toolId in: path required: true schema: type: string description: Connector tool resource ID. responses: '200': description: Operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConnectorToolRunResultDTO' '400': $ref: '#/components/responses/MetaBusinessAgentBadRequest' '401': $ref: '#/components/responses/MetaBusinessAgentUnauthorized' '403': $ref: '#/components/responses/MetaBusinessAgentForbidden' '404': $ref: '#/components/responses/MetaBusinessAgentNotFound' '409': $ref: '#/components/responses/MetaBusinessAgentConflict' '429': $ref: '#/components/responses/MetaBusinessAgentTooManyRequests' '500': $ref: '#/components/responses/MetaBusinessAgentServerError' '502': $ref: '#/components/responses/MetaBusinessAgentBadGateway' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicRunConnectorToolRequest' components: headers: YCloudRequestId: description: Server-generated HTTP request identifier for troubleshooting. schema: type: string responses: MessengerBadRequest: description: | 400 PARAM_MISSING, PARAM_INVALID, PARAM_INVALID_LENGTH or BAD_REQUEST. A confirmed Meta refusal maps to BAD_REQUEST and does not trigger automatic resubmission. When numeric provider diagnostics are available, error.messengerApiError contains the Meta code and optional subcode. The message provides a categorized hint; raw provider error text is not returned. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MessengerUnauthorized: description: Existing API-key authentication failure (401 UNAUTHORIZED). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MessengerForbidden: description: | 403 FORBIDDEN. Includes unavailable channel/new-send authorization and unsupported developer app API keys. Does not block historical record reads merely because a Page is disconnected. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MessengerNotFound: description: 404 NOT_FOUND. Missing/unowned Page for a new send, or no record in tenant/from scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MessengerRateLimited: description: 429 TOO_MANY_REQUESTS. Reuse existing REST rate limiting and applicable retry/rate-limit headers. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MessengerInternalError: description: 500 INTERNAL_SERVER_ERROR. The service cannot store or retrieve the record, or is not configured correctly. If the send may have reached Meta, the response is 502 MESSENGER_MESSAGE_RESULT_UNKNOWN instead. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MessengerResultUnknown: description: | 502 MESSENGER_MESSAGE_RESULT_UNKNOWN. YCloud cannot confirm the submission result. Meta may still have accepted the message. Do not automatically resubmit it. Check the saved status using a returned message ID when available, or contact support. An unavailable result does not include an invented message ID. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' WhatsappBlockedUsersBadRequest: description: Invalid request parameters, or Meta rejected the request. Meta errors are included in `error.whatsappApiError`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' WhatsappBlockedUsersUnauthorized: description: Authentication failed. The API key is invalid or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' WhatsappBlockedUsersForbidden: description: You do not have permission to access this resource, the business phone number is not registered with YCloud, or its WABA is unavailable to your account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' WhatsappBlockedUsersRateLimited: description: The request rate limit was exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' WhatsappBlockedUsersInternalError: description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentConflict: description: The requested operation conflicts with the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentBadRequest: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentUnauthorized: description: A valid API key is required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentForbidden: description: The tenant does not own the requested resource or lacks the required Meta permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentNotFound: description: The requested Meta Business Agent resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentUnprocessableEntity: description: The request is well-formed but cannot be processed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentTooManyRequests: description: Too many requests were sent to YCloud or Meta. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentServerError: description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MetaBusinessAgentBadGateway: description: Meta Business Agent returned an invalid or unavailable upstream response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: api_key: type: apiKey name: X-API-Key in: header parameters: MessengerFromPage: name: from in: query required: true description: Nonblank Facebook Page ID, matched exactly within the authenticated tenant. schema: type: string minLength: 1 maxLength: 64 example: '422500000000000' businessPhoneNumber-in_path: name: businessPhoneNumber in: path description: The WhatsApp business phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. required: true schema: type: string example: '+16315551111' 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: |- Identifier of the contact. Supports a contact ID, a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+` (for example, `+16315551111`), or a Meta username without the leading `@`. A Meta username must contain 3 to 35 letters, digits, periods, or underscores. If a numeric value can be interpreted as both a Meta username and a contact ID, it is resolved as a Meta username first. If no contact has that Meta username, the value is resolved as a contact ID. required: true schema: type: string example: alice_01 maxLength: 255 contactIdentifier-in_path_for_contact_note: name: contactIdentifier in: path description: |- Identifier of the contact that owns the note. Supports a contact ID, a username without the leading `@`, or a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format starting with `+`. Usernames contain 3 to 35 letters, digits, periods, or underscores. A numeric value is resolved as a username first and then as a contact ID when no matching username exists. required: true schema: type: string example: alice_01 maxLength: 255 contactPageAfter: name: pageAfter in: query description: |- Contact ID cursor for forward pagination. Use `0` to start a new cursor traversal. For each subsequent page, pass the exact `cursor.after` value from the previous response. The value must be a non-negative decimal integer in the signed 64-bit range (`0` through `9223372036854775807`). It cannot be combined with `page`, `pageBefore`, `offset`, or `sort`. required: false schema: type: string pattern: '^[0-9]+$' example: '0' noteId-in_path_for_contact_note: name: noteId in: path description: The 24-character ObjectId of the contact note. required: true schema: type: string minLength: 24 maxLength: 24 pattern: '^[0-9a-fA-F]{24}$' example: 6a3de646e18f344f743aaa4d groupAfter: name: after in: query description: A cursor to fetch the next page. required: false schema: type: string example: eyJvIjoiYWZ0ZXIifQ groupBefore: name: before in: query description: A cursor to fetch the previous page. required: false schema: type: string example: eyJvIjoiYmVmb3JlIn0 groupId-in_path: name: groupId in: path description: WhatsApp group ID. required: true schema: type: string example: '120363345678901234@g.us' groupLimit: name: limit in: query description: A limit on the number of results to be returned, between 1 and 1024. Defaults to 25. required: false schema: type: integer format: int32 minimum: 1 maximum: 1024 default: 25 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}' metaBusinessAgentEntityId-in_path: name: entityId in: path required: true description: |- Endpoint-specific Meta Business Agent entity ID. Budget and Conversation Turns operations use the tenant-owned WhatsApp Business Phone Number ID. schema: type: string minLength: 1 example: '1249005978294267' schemas: MessengerText: type: object required: - body properties: body: type: string minLength: 1 description: Nonblank text. Leading and trailing spaces are preserved. MessengerTextSendRequest: type: object required: - from - to - type - text properties: from: type: string minLength: 1 maxLength: 64 description: The Facebook Page ID; not an authorization-record ID or phone number. to: type: string minLength: 1 maxLength: 64 description: Recipient PSID scoped to the specified Page; do not substitute a global Facebook ID. type: type: string enum: - text text: $ref: '#/components/schemas/MessengerText' MessengerSendReceipt: type: object required: - id - metaMessageId - from - to - status properties: id: type: string description: The local outbound recordId, serialized as a decimal string. metaMessageId: type: string description: The confirmed Meta message ID. from: type: string to: type: string status: type: string enum: - accepted description: Submission receipt only; retrieve the record for its current state. MessengerMessage: type: object required: - id - from - to - type - text - status - createTime - updateTime properties: id: type: string description: YCloud outbound ID, a decimal string; never serialize it as a JSON number. metaMessageId: type: string description: Omitted when no Meta ID is confirmed. from: type: string description: Facebook Page ID. to: type: string description: Peer PSID for this Page. reactions: type: array description: | Active reactions reconstructed when retrieving an outbound message. Returns [] when no saved active reaction exists, including after withdrawal. Customer status webhooks omit this field; receiving a reaction does not change the message delivery status or updateTime. items: $ref: '#/components/schemas/MessengerMessageReactionState' type: type: string enum: - text text: $ref: '#/components/schemas/MessengerText' status: type: string enum: - unknown - accepted - rejected - sent - delivered - read description: | Current stored facts: read > delivered > sent > submission result. Unknown means unconfirmed or in progress, never a definitive failure. Missing receipts do not imply failure and no intermediate state is fabricated. errorCode: type: string description: | Locally recorded submission error, when present. A confirmed rejection may be MESSENGER_MESSAGE_REJECTED(#100:2018276), MESSENGER_MESSAGE_REJECTED(#100), or the legacy MESSENGER_MESSAGE_REJECTED when diagnostics are unavailable. MESSENGER_MESSAGE_RESULT_UNKNOWN means the submission outcome is unconfirmed. Never contains the raw Meta error body or credentials. createTime: type: string format: date-time description: Local creation time in UTC RFC 3339 with millisecond precision. updateTime: type: string format: date-time description: Local update time in UTC RFC 3339 with millisecond precision. sendTime: type: string format: date-time description: Confirmed send time in UTC RFC 3339 with millisecond precision; omitted when unknown. deliverTime: type: string format: date-time description: Confirmed delivery time in UTC RFC 3339 with millisecond precision; omitted when unknown. readTime: type: string format: date-time description: Confirmed read time in UTC RFC 3339 with millisecond precision; omitted when unknown. MessengerMessageReactionState: type: object description: The latest active reaction from a user, reconstructed from saved interaction events. required: - psid - updateTime properties: psid: type: string description: Page-scoped ID of the user who reacted. reaction: type: string description: Provider reaction description, when available. Clients should tolerate new values. example: love emoji: type: string description: Reaction emoji, when available. example: '❤' updateTime: type: string format: date-time description: Source interaction time in UTC RFC 3339 with millisecond precision; independent of the message updateTime. example: '2026-10-16T10:00:04.000Z' 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 remarkName: type: string description: The business-managed remark name for the contact. example: Priority customer maxLength: 250 nickname: type: string description: The read-only nickname obtained from WhatsApp. example: nickname metaUsername: type: string description: The read-only Meta username associated with the contact, without the leading `@`. example: alice_01 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 sourceType: $ref: '#/components/schemas/ContactSourceType' description: |- The source type of the contact. Indicates how the contact was created. sourceId: type: string description: |- Source identifier. A unique identifier related to the contact creation source. example: 'batch_import_123' maxLength: 255 sourceUrl: type: string description: |- Source URL. The source link address where the contact was created. example: 'https://example.com/signup' maxLength: 500 ContactNote: type: object description: Represents an internal note attached to a contact. required: - id - contactId - content properties: id: type: string description: Unique 24-character ObjectId for the contact note. IDs remain unchanged after storage migration. example: 6a3de646e18f344f743aaa4d minLength: 24 maxLength: 24 pattern: '^[0-9a-fA-F]{24}$' contactId: type: string description: Unique ID of the contact that owns this note. example: 1693364594105000026 content: type: string description: Note content. example: Customer prefers follow-up in the morning. maxLength: 500 operatorId: type: string description: ID of the actor who created the note. example: user_123 updateOperatorId: type: string description: ID of the actor who last updated the note. example: user_123 createTime: type: string format: date-time description: The time at which the note 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 the note was last 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' ContactNoteCreateInput: type: object description: A contact note to create together with a contact. required: - content properties: content: type: string description: Note content. Leading and trailing whitespace is removed before validation and storage. minLength: 1 maxLength: 500 example: Customer prefers follow-up in the morning. ContactNoteMutationInput: type: object description: |- An incremental note mutation for a contact update. When `id` is absent, a new note is created. When `id` is present, the owned note is updated. Notes omitted from the array remain unchanged. required: - content properties: id: type: string description: Existing note ID. Omit to create a new note. minLength: 24 maxLength: 24 pattern: '^[0-9a-fA-F]{24}$' example: 6a3de646e18f344f743aaa4d content: type: string description: Note content. Leading and trailing whitespace is removed before validation and storage. minLength: 1 maxLength: 500 example: Customer now prefers afternoon follow-up. ContactNoteWriteRequest: type: object description: Request body for creating or updating one contact note. required: - content properties: content: type: string description: Note content. Leading and trailing whitespace is removed before validation and storage. minLength: 1 maxLength: 500 example: Customer now prefers afternoon follow-up. ContactNoteWebhookPayload: type: object description: Customer-facing Contact Note webhook snapshot. Internal operator identifiers are not exposed. required: - id - contactId - username - phoneNumber - content - createTime - updateTime properties: id: type: string description: Unique 24-character ObjectId for the contact note. IDs remain unchanged after storage migration. example: 6a3de646e18f344f743aaa4d minLength: 24 maxLength: 24 pattern: '^[0-9a-fA-F]{24}$' contactId: type: string description: Unique ID of the contact that owns this note. example: 1693364594105000026 username: type: string nullable: true description: Username of the contact that owns this note, without the leading `@`. example: alice_01 phoneNumber: type: string nullable: true description: Phone number of the contact that owns this note in E.164 format. example: '+16315551111' content: type: string description: Note content. example: Customer prefers follow-up in the morning. maxLength: 500 createTime: type: string format: date-time description: The time at which the note was created, formatted in RFC 3339. example: '2022-06-01T12:00:00.000Z' updateTime: type: string format: date-time description: The time at which the note was last updated, formatted in RFC 3339. example: '2022-06-01T12:00:00.000Z' 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: remarkName: type: string description: |- Contact's remark name. Maximum length: 250 characters. example: remark name maxLength: 250 nickname: type: string deprecated: true description: |- Deprecated compatibility alias for `remarkName`. When `remarkName` is absent, this value is saved as the contact's remark name. It does not update the read-only WhatsApp nickname. Maximum length: 250 characters. example: remark name 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 notes: type: array description: |- Optional notes created atomically with the contact. The response remains the Contact schema; use the List Contact Notes endpoint to retrieve generated note IDs. maxItems: 50 items: $ref: '#/components/schemas/ContactNoteCreateInput' ContactPage: type: object description: |- Represents a given page of contacts. In cursor mode, `offset` is `0`, items are ordered by contact ID in ascending order, and `cursor` is returned only when another page exists. When `includeTotal=true`, `total` is the complete filtered count and is not reduced by the cursor position. allOf: - $ref: '#/components/schemas/Page' properties: items: description: An array containing contact objects. type: array items: $ref: '#/components/schemas/Contact' cursor: $ref: '#/components/schemas/ContactPageCursor' ContactPageCursor: type: object description: Position of the next Contact page. This object is returned only when another page exists. required: - after properties: after: type: string description: Contact ID of the last public item in this page. Pass this value unchanged as `pageAfter` to fetch the next page. pattern: '^[1-9][0-9]{0,18}$' example: '1866762588313988096' ContactUpdateRequest: type: object description: Contains the properties of the contact to be updated. properties: remarkName: type: string description: |- Contact's remark name. Maximum length: 250 characters. example: remark name maxLength: 250 nickname: type: string deprecated: true description: |- Deprecated compatibility alias for `remarkName`. When `remarkName` is absent, this value is saved as the contact's remark name. It does not update the read-only WhatsApp nickname. Maximum length: 250 characters. example: remark name 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 notes: type: array description: |- Optional incremental note mutations. An empty array changes nothing. Items without `id` create notes; items with `id` update owned notes. Notes not listed remain unchanged. Delete notes with the dedicated endpoint. maxItems: 50 items: $ref: '#/components/schemas/ContactNoteMutationInput' ContactSourceType: type: string description: |- Contact source type enumeration values. These are internal type identifiers, not the display names shown on the contact page. Each enumeration value corresponds to the following display names: - WHATSAPP: "Inbound message" - GROWTH_TOOL: "Link/QR Code" - MANUALLY_ADDED: "Manually added" - FILE_IMPORT: "File import" - SHOPIFY: "Shopify" - API: "API added" - AD: "AD" - POST: "Post" - CALLING: "Calling" - SMB: "Whatsapp Business App" - UNKNOWN: "Unknown" enum: - WHATSAPP - GROWTH_TOOL - MANUALLY_ADDED - FILE_IMPORT - SHOPIFY - API - AD - POST - CALLING - SMB - UNKNOWN example: API ContactAttributesChanged: type: object description: |- Represents a contact attributes changed event. Contains information about which contact attributes were modified and their old/new values. This event is emitted only when at least one persisted contact field actually changes; note-only and contact no-op updates do not emit it. required: - id - updateTime - changedAttributes properties: id: type: string description: The ID of the contact whose attributes were changed. example: "182426659410206xxxx" phoneNumber: type: string description: The contact's phone number in E.164 format. example: '+16315551111' updateTime: type: string format: date-time description: The time at which the contact attributes were updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: "2025-07-09T02:24:16.193Z" changedAttributes: type: object description: |- An object containing the changed attributes. Each key represents the name of the changed attribute, and the value contains the old value, new value, and change actions. additionalProperties: $ref: '#/components/schemas/ContactAttributeChange' example: remark_name: oldValue: "Standard customer" newValue: "Priority customer" extra: - action: "CHANGED" tags: newValue: ["customer", "vip"] extra: - action: "ADDED" id: "686dd294334be8606a5bfxxx" value: "customer" waba_id: oldValue: "wabaId1" newValue: "wabaId2" extra: - action: "CHANGED" age: oldValue: 25 newValue: 26 extra: - action: "CHANGED" is_verified: oldValue: false newValue: true extra: - action: "CHANGED" ContactAttributeChange: type: object description: |- Represents a single attribute change, containing the old value, new value, and change actions. properties: oldValue: description: |- The previous value of the attribute before the change. Can be a string, number, array, or boolean depending on the attribute type. This field is not included when the value is null. example: "previous_value" newValue: description: |- The new value of the attribute after the change. Can be a string, number, array, or boolean depending on the attribute type. This field is not included when the value is null. example: [ "tag1", "tag2" ] extra: type: array description: |- An array of change actions that describe what operations were performed on this attribute. items: $ref: '#/components/schemas/AttributeChangeAction' AttributeChangeAction: type: object description: |- Represents a single change action performed on an attribute. For tag attributes, includes additional id and value fields. required: - action properties: action: type: string description: The type of change action performed. enum: - ADDED - REMOVED - CHANGED example: "ADDED" x-enum-descriptions: ADDED: A new value was added to the attribute. REMOVED: An existing value was removed from the attribute. CHANGED: The attribute value was modified. id: type: string description: |- The ID of the item when the attribute is 'tags'. This field is only present for tag-related changes. example: "686dd294334be8606a5bfxxx" value: type: string description: |- The value of the item when the attribute is 'tags'. This field is only present for tag-related changes. example: "tag1" ContactCreated: type: object description: |- Represents a contact created event. Contains the full contact information that was created. required: - id properties: id: type: string description: Unique ID for the object. example: "1824266594102064128" remarkName: type: string description: The business-managed remark name for the contact. example: "Priority customer" nickName: type: string description: Contact's nickname. example: "John Doe" realName: type: string description: Contact's real name. example: "John Smith" 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' countryName: type: string description: Full country name. example: "United States" email: type: string description: |- The contact's email address. If present, the email address must be unique. example: 'john.doe@example.com' sourceType: type: string description: The source type where the contact was created. example: "api" sourceId: type: string description: The source ID where the contact was created. example: "import_batch_123" sourceUrl: type: string description: The source URL where the contact was created. example: "https://example.com/signup" 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: '2025-07-09T02:24:16.193Z' lastConnectedNumber: type: string description: |- The business phone number that the contact last connected to. example: '+16315551111' ownerEmail: type: string description: |- The email address of the contact's owner. example: 'support@example.com' tags: type: array description: Contact's tags. items: type: string example: ["customer", "vip"] 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: '2025-07-09T02:24:16.193Z' updateTime: type: string format: date-time description: The time at which the contact was last updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-09T02:24:16.193Z' blocked: type: boolean description: Whether the contact is blocked. example: false customAttributes: type: object description: Contact's custom attributes as key-value pairs. additionalProperties: type: object example: company: "YCloud Inc" age: 25 preferences: newsletter: true ContactDeleted: type: object description: |- Represents a contact deleted event. Contains the contact information that was deleted. required: - id properties: id: type: string description: Contact ID example: "1824266594102064129" remarkName: type: string description: The business-managed remark name from the deleted contact snapshot. example: "Former customer" nickName: type: string description: Contact's nickname. example: "Jane Smith" phoneNumber: type: string description: Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16475551234' updateTime: type: string format: date-time description: The time at which the contact was last updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-08T15:25:00.000Z' ContactUnsubscribeCreated: type: object description: |- Represents a customer initiates an unsubscribe event. required: - id properties: id: type: string description: Unique ID of the contact unsubscribe event. phoneNumber: type: string description: Unique Customer Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16475551234' source: type: string description: |- The source from which a customer initiates an unsubscribe. - `Whatsapp`: The customer initiated an unsubscribe on the whatsapp client. - `Inbox`:You added a customer to the unsubscribe list on the Inbox page of YCloud. - `Chatbot`: The message sent by the customer triggered the unsubscribe keyword configured by the Chatbot. - `API`: You add customers to the unsubscribe list through YCloud's OpenAPI. - `Manual`: You added a customer to the unsubscribe list on the Contact page of YCloud. enum: - Whatsapp - Inbox - Chatbot - API - Manual example: "Whatsapp" x-enum-descriptions: Whatsapp: The customer initiated an unsubscribe on the whatsapp client. Inbox: You added a customer to the unsubscribe list on the Inbox page of YCloud. Chatbot: The message sent by the customer triggered the unsubscribe keyword configured by the Chatbot. API: You add customers to the unsubscribe list through YCloud's OpenAPI. Manual: You added a customer to the unsubscribe list on the Contact page of YCloud. updateTime: type: string format: date-time description: The time when a customer initiates an unsubscribe, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-08T15:25:00.000Z' ContactUnsubscribeDeleted: type: object description: |- Represents a customer resumed their subscription event. required: - id properties: id: type: string description: Unique ID of the contact resubscribe event. phoneNumber: type: string description: Unique Customer Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16475551234' source: type: string description: |- The source from which a customer resumed their subscription - `Whatsapp`: The customer resumed their subscription on the whatsapp client - `API`: You remove the customer from the unsubscribe list through the OpenAPI of YCloud - `Manual`: You remove the customer from the unsubscribe list on the Contact page of YCloud. enum: - Whatsapp - API - Manual example: "Whatsapp" updateTime: type: string format: date-time description: The time when customers cancel unsubscribe, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-08T15:25:00.000Z' ContactAttribute: type: object description: |- Represents a contact attribute configuration. Contains information about the attribute's metadata and available values. required: - id - name - key - type properties: id: type: string description: Unique identifier for the contact attribute. example: "6865e6c17c3854485be550b0" name: type: string description: Display name of the contact attribute. example: "Blocked" key: type: string description: Key name used to reference this attribute. example: "blocked" type: type: string description: Data type of the contact attribute. enum: - BOOLEAN - TEXT - LONG_TEXT - TIME - NUMBER - ARRAY example: "BOOLEAN" x-enum-descriptions: BOOLEAN: A true/false value. TEXT: A short text string. LONG_TEXT: A longer text string with multiple lines. TIME: A date or time value. NUMBER: A numeric value. ARRAY: An array of predefined values. desc: type: string description: Description of the contact attribute. example: "" values: type: array description: |- Array of possible values for this attribute. Only present when type is "ARRAY". items: type: string example: [ "a1", "wa", "a3" ] example: id: "6865e6c17c3854485be550b0" name: "Blocked" key: "blocked" type: "BOOLEAN" desc: "" values: [] 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. For events defined with `objectType` as `CONTACT`, provide one of `objectId`, `contactPhoneNumber`, or `contactUsername` to identify the contact. Only one identifier is used per event. If multiple identifiers are provided, a numeric `objectId` takes precedence, followed by a non-blank `contactPhoneNumber`, then `contactUsername`. required: - eventName oneOf: - required: - objectId - required: - contactPhoneNumber not: required: - objectId - required: - contactUsername not: anyOf: - required: - objectId - required: - contactPhoneNumber 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`, provide the numeric ID of an existing contact in your account. A numeric `objectId` takes precedence over `contactPhoneNumber` and `contactUsername`. If that contact is not found, the request fails without trying another identifier. contactPhoneNumber: type: string description: |- The contact's phone number in E.164 format for events defined with `objectType` as `CONTACT`. Used when no numeric `objectId` is provided. Looks up a contact in your account by phone number and creates one if no match exists. Takes precedence over `contactUsername`. example: '+16315551111' contactUsername: type: string description: |- The Meta username of an existing contact in your account for events defined with `objectType` as `CONTACT`. Provide the username saved on the contact, without the leading `@`. Used when neither a numeric `objectId` nor a non-blank `contactPhoneNumber` is provided. If no matching contact exists, the request fails. A username does not automatically create a contact. example: 'customer_demo' 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 x-enum-descriptions: 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. 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` work. example: 'SupportTeam' 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' 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://helpdocs.ycloud.com/help-center/integrations/channels/email/email-template-samples) 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' bcc: type: string description: Recipients who will receive a blind carbon copy of the email. example: 'bcc1@example.com,Nick' 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. metaBusinessAgentApiError: $ref: '#/components/schemas/MetaBusinessAgentApiError' description: Sanitized upstream details returned when a Meta Business Agent request fails. messengerApiError: $ref: '#/components/schemas/MessengerApiError' description: Numeric Meta diagnostics for a confirmed Messenger submission refusal. Omitted when unavailable. MessengerApiError: type: object description: Numeric provider diagnostics only. Does not contain raw Meta error text or access credentials. required: - code properties: code: type: string description: Meta error code, encoded as a string. example: '100' subcode: type: string description: Meta error subcode, encoded as a string. Omitted if Meta did not provide it. example: '2018276' ErrorResponse: type: object required: - error properties: error: description: Contains the error code and human-readable message for the API error. $ref: '#/components/schemas/Error' WhatsappInboundMessageTypingResponse: type: object description: Successful response from the JSON typing-indicator endpoint. required: - success properties: success: type: boolean description: Always `true` in an HTTP 200 response. enum: - true example: true WhatsappTemplateAnalyticsRequest: type: object required: - wabaId - startDate - endDate properties: wabaId: type: string example: '102012345678901' officialTemplateId: type: string nullable: true description: Official WhatsApp/Meta template ID exposed by the existing template REST APIs. example: '875432109876543' templateName: type: string nullable: true description: Exact template name. Must be provided together with language when officialTemplateId is absent. example: order_update language: type: string nullable: true description: Template language code. Must be provided together with templateName when officialTemplateId is absent. example: en_US startDate: type: string format: date description: Inclusive start date interpreted in the WABA timezone. example: '2026-07-01' endDate: type: string format: date description: Inclusive end date interpreted in the WABA timezone. The inclusive range must not exceed 90 calendar days. example: '2026-07-07' description: |- Specify exactly one template selector: either officialTemplateId alone, or templateName together with language. officialTemplateId cannot be combined with templateName or language. WhatsappTemplateAnalytics: type: object required: - wabaId - officialTemplateId - templateName - language - timezone - analyticsStatus - startDate - endDate - dataPoints properties: wabaId: type: string description: WhatsApp Business Account ID. officialTemplateId: type: string nullable: true description: Resolved official WhatsApp/Meta template ID. Successful queries resolve a current template; the property remains nullable for contract compatibility. templateName: type: string description: Template name used for the statistics query. language: type: string description: Template language used for the statistics query. timezone: type: string description: IANA timezone resolved from the WABA configuration and used to interpret the date range. analyticsStatus: type: string enum: [ENABLED, NOT_ENABLED, UNSUPPORTED_REGION, PERMISSION_DENIED, NO_DATA, ERROR] description: |- Meta Template Insights status only; it does not describe YCloud message metrics. NO_DATA means the Meta query completed without data for the requested date range. ERROR indicates that Template Insights are unavailable because of an error after the current template was successfully resolved and validated. startDate: type: string format: date description: Inclusive start date from the request. endDate: type: string format: date description: Inclusive end date from the request. dataPoints: type: array description: One item for every date in the requested range, ordered by date ascending. Missing metrics are returned as zero and missing button details as an empty array. items: $ref: '#/components/schemas/WhatsappTemplateAnalyticsDataPoint' WhatsappTemplateAnalyticsDataPoint: type: object required: [date, sent, delivered, failed, read, clicks, uniqueReplies, buttonClicks] properties: date: type: string format: date sent: type: integer format: int64 description: Number of messages created on this date for the selected template. delivered: type: integer format: int64 description: Number of those messages that were delivered. failed: type: integer format: int64 description: Number of those messages whose status is failed or expired. read: type: integer format: int64 description: Number of those messages that were read. clicks: type: integer format: int64 description: Total number of clicks recorded for this template on this date. Interpret zero together with analyticsStatus. uniqueReplies: type: integer format: int64 description: Number of unique replies recorded for this template on this date. This is mapped from Meta replied and is a Meta Template Insights metric. buttonClicks: type: array description: Button click breakdown for this template on this date. Empty when no details are available. items: $ref: '#/components/schemas/WhatsappTemplateAnalyticsButtonClick' WhatsappTemplateAnalyticsButtonClick: type: object required: [type, buttonContent, count] properties: type: type: string description: Type of button associated with the clicks. Values may include quick_reply_button, unique_url_button, or url_button. buttonContent: type: string description: Button content associated with the clicks. count: type: integer format: int64 description: Number of clicks for this button entry. WhatsappEchoMessageMedia: type: object description: Media metadata copied from a Meta Business Agent echo callback. properties: id: type: string description: Provider media ID, when supplied by the callback. link: type: string description: Provider media URL, when supplied by the callback. caption: type: string description: Media caption, when supplied by the callback. filename: type: string description: Original filename, when supplied by the callback. mime_type: type: string description: Provider MIME type copied from the callback. example: image/jpeg WhatsappEchoMessage: type: object description: |- WhatsApp outbound message subset emitted for Agent echo events. Fields are copied from the source echo or status callback; unavailable values are omitted. Agent, control, routing, pricing, and conversation fields are never included. required: - id properties: id: type: string description: YCloud message ID. Use it to correlate created and updated echo events. wamid: type: string description: The original message ID on WhatsApp's platform, when available. example: wamid.EXAMPLE wabaId: type: string description: WhatsApp Business Account ID from the source callback, when available. example: WABA_ID from: type: string description: Business sender number in E.164 format, when available. example: '+12025550123' to: type: string description: Recipient number in E.164 format when the callback identifies the customer by phone number. example: '+12025550124' recipientUserId: type: string description: Recipient WhatsApp Business-scoped user ID (BSUID), when supplied by the callback. example: GB.898232076600896 parentRecipientUserId: type: string description: Recipient parent WhatsApp Business-scoped user ID, when supplied by the callback. example: GB.ENT.898232076600896 type: type: string description: Message type copied from a supported provider callback. Current values include text, interactive, image, video, audio, document, sticker, location, contacts, and reaction. Clients should tolerate future values. example: text text: $ref: '#/components/schemas/WhatsappMessageText' image: $ref: '#/components/schemas/WhatsappEchoMessageMedia' video: $ref: '#/components/schemas/WhatsappEchoMessageMedia' audio: $ref: '#/components/schemas/WhatsappEchoMessageMedia' document: $ref: '#/components/schemas/WhatsappEchoMessageMedia' sticker: $ref: '#/components/schemas/WhatsappEchoMessageMedia' 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' status: $ref: '#/components/schemas/WhatsappMessageStatus' errorCode: type: string description: Source error code when status is failed and the provider supplied one. example: '131000' errorMessage: type: string description: Source error title when status is failed and the provider supplied one. example: Provider failure createTime: type: string format: date-time description: Source echo time for a created event, formatted in RFC 3339. example: '2026-09-09T02:00:00.000Z' updateTime: type: string format: date-time description: Source status time for an updated event, formatted in RFC 3339. example: '2026-09-09T02:00:01.000Z' sendTime: type: string format: date-time description: Source echo time on created events, or source status time when the current event reports sent. example: '2026-09-09T02:00:00.000Z' deliverTime: type: string format: date-time description: Source status time when the current event reports delivered. example: '2026-09-09T02:00:01.000Z' readTime: type: string format: date-time description: Source status time when the current event reports read. example: '2026-09-09T02:00:02.000Z' MetaBusinessAgentWebhook: type: object description: |- Payload for whatsapp.meta_business_agent.handover.updated. Currently emitted only for Agents onboarded through the Public REST API, not Console-created Agents. Null fields are omitted. properties: agentId: type: string description: YCloud Agent ID. Not a Meta Agent ID or an Inbox assignee ID. example: 00000000-0000-4000-8000-000000000001 metaAgentId: type: string description: Meta Agent ID, when available. example: META_AGENT_ID phoneNumberId: type: string description: Meta business phone number ID. Not an E.164 phone number. example: PHONE_NUMBER_ID wabaId: type: string description: WhatsApp Business Account ID from the source callback, when available. example: WABA_ID consumerPhoneNumber: type: string description: Consumer phone number from the handover callback, normalized to E.164 when available. This is not the business number or phoneNumberId. pattern: '^\+[1-9][0-9]{7,14}$' example: '+12025550124' controlState: type: string description: |- Present for handover events. Currently APP_CONTROL_TAKEN for Public REST API handover callbacks. Does not confirm an Inbox assignment or message delivery. example: APP_CONTROL_TAKEN actor: type: string description: |- Optional handover source actor. For a control_passed handoff this is the previous owner app ID, not the employee who receives the conversation. example: PREVIOUS_OWNER_APP_ID reason: type: string description: Optional provider handover reason or metadata, for example customer_request. Not a closed enum. example: customer_request timestamp: type: integer format: int64 description: Source event time in Unix milliseconds, or processing time if unavailable. example: 1788919204000 MessengerInboundMessage: type: object description: The current text of a persisted ordinary Messenger inbound message. Editing preserves its message IDs and original times. required: - id - metaMessageId - from - to - type - text - sendTime - createTime properties: id: type: string description: YCloud inbound message ID as a decimal string. metaMessageId: type: string description: Meta message ID. from: type: string description: Customer PSID scoped to the Facebook Page. to: type: string description: Facebook Page ID. type: type: string enum: - text text: $ref: '#/components/schemas/MessengerText' sendTime: type: string format: date-time description: Saved source event time in UTC RFC 3339 with millisecond precision. createTime: type: string format: date-time description: Local persistence time in UTC RFC 3339 with millisecond precision. editCount: type: integer description: Cumulative edit count supplied by Meta. Omitted before the first edit. editTime: type: string format: date-time description: Saved platform edit time in UTC RFC 3339 with millisecond precision. Omitted before the first edit. MessengerMessageReaction: type: object description: |- A customer reaction to a Messenger message, or its withdrawal. This is an interaction event, not a message or delivery status. The target Meta message may not have a local YCloud message record. No local message ID is supplied. required: - pageId - psid - metaMessageId - action properties: pageId: type: string description: Facebook Page ID that scopes this conversation. psid: type: string description: Page-scoped ID of the customer who reacted. metaMessageId: type: string description: Meta ID of the message being reacted to. action: type: string enum: - react - unreact description: Use react to apply a reaction and unreact to withdraw it. reaction: type: string description: Reaction name when provided by Meta. May be omitted, including on withdrawal. emoji: type: string description: Reaction emoji when provided by Meta. May be omitted, including on withdrawal. 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: description: The event type that identifies the kind of webhook event this is. Used for routing and handling different event types (e.g., message status updates, inbound messages, template reviews). See EventType enum for all possible values and their descriptions. $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' phase: type: integer format: int32 description: Included when `type` is `whatsapp.smb.history` and the event was generated from a Meta history chunk. Identifies the chunk's synchronization phase. example: 1 progress: type: integer format: int32 description: Included when `type` is `whatsapp.smb.history` and the event was generated from a Meta history chunk. Reports the chunk's synchronization progress. example: 73 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: description: Included when `type` is `whatsapp.inbound_message.received`, or when `type` is `whatsapp.smb.history` for an inbound history message. It is omitted for a metadata-only history chunk. allOf: - $ref: '#/components/schemas/WhatsappInboundMessage' whatsappMessage: description: Included when `type` is `whatsapp.message.updated`, `whatsapp.smb.message.created`, or when `type` is `whatsapp.smb.history` for an outbound history message. Also included for `whatsapp.echo_message.created` and `whatsapp.echo_message.updated`, where the Agent echo subset applies. It is omitted for a metadata-only history chunk. type: object whatsappMetaBusinessAgent: $ref: '#/components/schemas/MetaBusinessAgentWebhook' description: Included for whatsapp.meta_business_agent.handover.updated. Currently limited to Public REST API Agents. whatsappGroup: $ref: '#/components/schemas/WhatsappGroupWebhook' description: Included when `type` is `whatsapp.group.lifecycle_update`, `whatsapp.group.participants_update`, `whatsapp.group.settings_update`, `whatsapp.group.status_update`, or when `type` is `whatsapp.message.updated` for group message status updates. whatsappPhoneNumber: $ref: '#/components/schemas/WhatsappPhoneNumber' description: Included when `type` is `whatsapp.phone_number.deleted`, `whatsapp.phone_number.name_updated`, `whatsapp.phone_number.quality_updated`, or `whatsapp.phone_number.business_username_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`, `whatsapp.template.category_updated`, or `whatsapp.template.correct_category_detection`. callingConnect: description: Included when `type` is `whatsapp.call.connect`. allOf: - $ref: '#/components/schemas/CallingConnect' callingTerminate: description: Included when `type` is `whatsapp.call.terminate`. allOf: - $ref: '#/components/schemas/CallingTerminate' callingStatusUpdated: description: Included when `type` is `whatsapp.call.status.updated`. allOf: - $ref: '#/components/schemas/CallingStatusUpdated' flowChanges: description: Included when `type` is `whatsapp.flow.status_change`. allOf: - $ref: '#/components/schemas/WhatsappFlowStatusChange' contactAttributesChanged: $ref: '#/components/schemas/ContactAttributesChanged' description: Included when `type` is `contact.attributes_changed`. contactCreated: $ref: '#/components/schemas/ContactCreated' description: Included when `type` is `contact.created`. contactDeleted: $ref: '#/components/schemas/ContactDeleted' description: Included when `type` is `contact.deleted`. contactNote: $ref: '#/components/schemas/ContactNoteWebhookPayload' description: Included when `type` is `contact.note.created`, `contact.note.updated`, or `contact.note.deleted`. contactUnsubscribeCreated: $ref: '#/components/schemas/ContactUnsubscribeCreated' description: Included when `type` is `contact.unsubscribe.created`. contactUnsubscribeDeleted: $ref: '#/components/schemas/ContactUnsubscribeDeleted' description: Included when `type` is `contact.unsubscribe.deleted`. whatsappUserPreference: $ref: '#/components/schemas/WhatsappUserPreference' description: Included when `type` is `whatsapp.user.preferences`. callingRecording: $ref: '#/components/schemas/CallingMediaUpdated' description: Included when `type` is `whatsapp.call.recording.updated`. callingTranscription: $ref: '#/components/schemas/CallingMediaUpdated' description: Included when `type` is `whatsapp.call.transcription.updated`. messengerInboundMessage: $ref: '#/components/schemas/MessengerInboundMessage' description: Included when `type` is `messenger.inbound_message.received` or `messenger.inbound_message.updated`. Editing keeps the same message IDs and original times; event createTime is the edit time for updated events. messengerMessage: $ref: '#/components/schemas/MessengerMessage' description: Included when `type` is `messenger.message.updated`. messengerMessageReaction: $ref: '#/components/schemas/MessengerMessageReaction' description: Included when `type` is `messenger.message_reaction.updated`. Event createTime is the source interaction time. oneOf: - properties: type: enum: - whatsapp.echo_message.created - whatsapp.echo_message.updated whatsappMessage: $ref: '#/components/schemas/WhatsappEchoMessage' required: - whatsappMessage not: required: - whatsappMetaBusinessAgent - properties: type: enum: - whatsapp.meta_business_agent.handover.updated whatsappMetaBusinessAgent: $ref: '#/components/schemas/MetaBusinessAgentWebhook' required: - whatsappMetaBusinessAgent not: required: - whatsappMessage - properties: type: not: enum: - whatsapp.echo_message.created - whatsapp.echo_message.updated - whatsapp.meta_business_agent.handover.updated whatsappMessage: $ref: '#/components/schemas/WhatsappMessage' 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.group.lifecycle_update - whatsapp.group.participants_update - whatsapp.group.settings_update - whatsapp.group.status_update - whatsapp.smb.history - whatsapp.smb.message.created - whatsapp.phone_number.deleted - whatsapp.phone_number.name_updated - whatsapp.phone_number.quality_updated - whatsapp.phone_number.business_username_updated - whatsapp.template.category_updated - whatsapp.template.correct_category_detection - whatsapp.template.quality_updated - whatsapp.template.reviewed - whatsapp.call.connect - whatsapp.call.terminate - whatsapp.call.status.updated - whatsapp.call.recording.updated - whatsapp.call.transcription.updated - whatsapp.flow.status_change - whatsapp.payment.updated - contact.attributes_changed - contact.created - contact.deleted - contact.unsubscribe.created - contact.unsubscribe.deleted - whatsapp.user.preferences - whatsapp.smb.message.echoes - contact.note.created - contact.note.updated - contact.note.deleted - whatsapp.echo_message.created - whatsapp.echo_message.updated - whatsapp.meta_business_agent.handover.updated - messenger.inbound_message.received - messenger.inbound_message.updated - messenger.message.updated - messenger.message_reaction.updated 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 group is created or deleted, including successful and failed results. - Occurs when WhatsApp group participants or join requests are updated. - Occurs when WhatsApp group settings are updated, including successful and failed results. - Occurs when a WhatsApp group suspension status is updated. - Occurs when WhatsApp Business app sync history message. - Occurs when WhatsApp Business app send message. - 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 business phone number's Business Username is updated. - Occurs when a WhatsApp template category is updated. - Occurs when Meta detects non-utility content in Utility Direct Send. Subscribe through the webhook endpoint API. - 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`, `IN_APPEAL`, or `ARCHIVED`. - Occurs when a WhatsApp call is connected. - Occurs when a WhatsApp call is terminated. - Occurs when a WhatsApp call status is updated. - Occurs when an API-sourced WhatsApp call recording becomes available or permanently fails. - Occurs when an API-sourced WhatsApp call transcription becomes available or permanently fails. - Occurs when a WhatsApp flow status is updated. - Occurs when a WhatsApp payment transaction changes. - Occurs when a contact's attributes are changed. - Occurs when a contact is created. - Occurs when a contact is deleted. - Occurs when a contact unsubscribes from messages. - Occurs when a contact resumes subscription to messages. - Occurs when a WhatsApp user stops marketing messages or a WhatsApp user resumes marketing messages. - Occurs when WhatsApp Business app sends a message echo. - Occurs when a contact note is created. - Occurs when a contact note is updated. - Occurs when a contact note is independently deleted. Contact deletion does not emit this event for cascaded notes. - Occurs when an outbound echo message is recorded for a Public REST API Agent. - Occurs when an outbound echo status is received for a Public REST API Agent; late lower-ranked statuses can also be delivered. - Occurs when a supported handover callback transfers control away from a Public REST API Agent. Does not confirm Inbox assignment. - Occurs when an ordinary Messenger text message is received from a customer. - Occurs when a customer edits a saved Messenger inbound text message. - Occurs when a saved ordinary Messenger outbound message snapshot is available, including submission results and matched receipts. - Occurs when a customer reacts to or removes a reaction from a Messenger message. EventProperty: type: object description: |- Represents event property configuration for webhook endpoints. Specifies which properties should be included in the webhook payload for a specific event type. required: - event - properties properties: event: type: string description: |- The event type for which properties are configured. This field accepts any valid event type that supports property configuration. example: contact.attributes_changed properties: type: array description: |- A list of property names that should be included in the webhook payload for the specified event type. The available properties depend on the specific event type configured. items: type: string example: [ "attr1", "attr2" ] minItems: 1 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://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-basic-principles#sms-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 x-enum-descriptions: 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. 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 required: - code not: allOf: - not: required: - verificationId - not: required: - to 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: description: The channel through which the verification code will be sent. Supported channels are `sms` (text message), `voice` (phone call), `email_code` (email), and `whatsapp` (WhatsApp message). $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://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-features/sender-id) 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://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-features/sender-id) 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' source: type: string description: |- The source from which a customer resumed their subscription - `Whatsapp`: The customer resumed their subscription on the whatsapp client - `API`: You remove the customer from the unsubscribe list through the OpenAPI of YCloud - `Manual`: You remove the customer from the unsubscribe list on the Contact page of YCloud. enum: - Whatsapp - API - Manual example: "Whatsapp" 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: description: The type of unsubscriber identifier. Currently only `PHONE_NUMBER` is supported, indicating that the `customer` field contains a phone number in E.164 format. $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: description: The communication channel from which the customer is unsubscribing. Currently only `whatsapp` is supported, indicating the customer opts out of receiving WhatsApp messages from your business. $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 eventProperties: type: array description: |- Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types. When `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type. items: $ref: '#/components/schemas/EventProperty' example: - event: contact.attributes_changed properties: - attr1 - attr2 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' eventProperties: type: array description: |- Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types. When `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type. items: $ref: '#/components/schemas/EventProperty' example: - event: contact.attributes_changed properties: - attr1 - attr2 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' eventProperties: type: array description: |- Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types. When `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type. items: $ref: '#/components/schemas/EventProperty' example: - event: contact.attributes_changed properties: - attr1 - attr2 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 is_transient: type: boolean description: Whether the error is transient. example: false error_subcode: type: string description: Additional code about the error. example: 2388109 error_user_msg: type: string description: The message to display to the user. The language of the message is based on the locale of the API request. example: This message template cannot be created. error_user_title: type: string description: The title of the dialog, if shown. The language of the message is based on the locale of the API request. example: Message Cannot Be Submitted fbtrace_id: type: string description: Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging. example: AVGjJ7ia2zJkrHG error_data: description: |- Additional data about the error. A string or map. - For template APIs, this field is a string describing the reason for the error. - For message APIs, this field is a map with property `details` describing the reason for the error. oneOf: - type: string - type: object additionalProperties: true 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' businessId: type: string description: Business Portfolio ID. businessName: type: string description: Business Portfolio Name. businessStatus: type: string description: Business Portfolio Status,Default:APPROVED 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` or `DEFERRED`. 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 Meta's [Policy enforcement violations](https://developers.facebook.com/documentation/business-messaging/whatsapp/policy-enforcement-violations) for violation types and descriptions. Meta may update this list over time. For Utility Direct Send violation types and restriction details, see Meta's [Webhook for account restriction](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/integrity-and-content-guidelines#webhook-for-account-restriction). 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' maxPhoneNumbersPerBusiness: type: integer format: int32 description: Included in a `whatsapp.business_account.updated` webhook with `updateEvent=BUSINESS_CAPABILITY_UPDATE` when Meta reports the Business Portfolio phone-number registration limit. Meta currently reports this field separately from `maxPhoneNumbersPerWaba`, but consumers must process both if a future update includes them together. example: 20 maxPhoneNumbersPerWaba: type: integer format: int32 description: Included in a `whatsapp.business_account.updated` webhook with `updateEvent=BUSINESS_CAPABILITY_UPDATE` when Meta reports the WABA phone-number registration limit. Meta currently reports this field separately from `maxPhoneNumbersPerBusiness`, but consumers must process both if a future update includes them together. example: 25 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' whatsappBusinessManagerMessagingLimit: type: string description: |- The owning business portfolio's messaging limit. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio. See also [phone_number_quality_update webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update). - `TIER_NOT_SET`: The business phone number has not been used to send a message yet. - `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period. - `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period. - `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period. - `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period. - `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations. example: TIER_2K removedReason: type: string description: |- Raw reason from the WhatsApp Business Account deletion event. Known values include: - `ACCOUNT_DISCONNECTED`: The account was disconnected due to enforcement or because the WhatsApp account was explicitly deleted. - `BUSINESS_DOWNGRADE`: The phone number was registered with the consumer WhatsApp app. - `CHANGE_NUMBER`: The WhatsApp phone number was changed. - `COMPANION_INACTIVITY`: A companion device was inactive for approximately 30 days. - `PRIMARY_INACTIVITY`: A primary device was inactive for approximately 30 days. - `USER_RE_REGISTERED`: WhatsApp was re-registered on a new device. Unknown values are returned as received. example: ACCOUNT_DISCONNECTED removedInitiatedBy: type: string description: |- Raw initiator from the WhatsApp Business Account deletion event. Known values include: - `USER`: The removal was initiated by the WhatsApp user. - `SYSTEM`: The removal was initiated by the Meta system. Unknown values are returned as received. example: USER removedTime: type: string format: date-time description: The time when the WhatsApp Business Account deletion event was received, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2026-05-19T12:00:00.000Z`. example: '2026-05-19T12:00:00.000Z' WhatsappAutomaticCreativeOptimizationUpdateRequest: type: object required: - creativeOptimizationFeatures properties: creativeOptimizationFeatures: type: object description: |- A non-empty map of automatic creative optimization feature enrollment values. Only submitted features are updated. Supported feature keys: - `image_brightness_and_contrast` - `image_touchups` - `add_text_overlay` - `image_animation` - `image_background_gen` - `auto_promotion_tag` - `text_extraction_for_headline` - `text_extraction_for_tap_target` - `product_extensions` - `text_formatting_optimization` - `hyperlink_formatting` - `image_banner` - `image_end_card` - `dynamic_cta_text` minProperties: 1 properties: image_brightness_and_contrast: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' image_touchups: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' add_text_overlay: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' image_animation: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' image_background_gen: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' auto_promotion_tag: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' text_extraction_for_headline: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' text_extraction_for_tap_target: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' product_extensions: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' text_formatting_optimization: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' hyperlink_formatting: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' image_banner: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' image_end_card: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' dynamic_cta_text: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' additionalProperties: false example: image_brightness_and_contrast: OPT_IN image_touchups: OPT_OUT WhatsappAutomaticCreativeOptimizationUpdateResponse: type: object properties: wabaId: type: string description: WhatsApp Business Account ID returned by Meta. example: 'whatsapp-business-account-id' creativeOptimizationFeatures: type: object description: The submitted feature enrollment values for PATCH responses, or current feature enrollment values for GET responses. additionalProperties: $ref: '#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus' example: image_brightness_and_contrast: OPT_IN image_touchups: OPT_OUT WhatsappAutomaticCreativeOptimizationRetrieveResponse: type: object properties: wabaId: type: string description: WhatsApp Business Account ID returned by Meta. example: 'whatsapp-business-account-id' creativeOptimizationFeatures: type: object description: Current feature enrollment string values returned by Meta. REST returns fields and original string values from `creative_features_spec[0]` without feature-key filtering, status-value validation, or case normalization. additionalProperties: type: string example: image_brightness_and_contrast: OPT_IN image_touchups: opt_out future_meta_feature: UNKNOWN WhatsappAutomaticCreativeOptimizationEnrollStatus: type: string description: Automatic creative optimization feature enrollment status. enum: - OPT_IN - OPT_OUT 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 - RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES 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. - `PARTNER_REMOVED`: WhatsApp Business Account was removed from the partner connection. - `PARTNER_APP_UNINSTALLED`: WhatsApp Business Account partner app was uninstalled. - `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. - `BUSINESS_CAPABILITY_UPDATE`: Meta reported a change to the Business Portfolio or WABA phone-number registration limit. enum: - DISABLED_UPDATE - ACCOUNT_RESTRICTION - ACCOUNT_VIOLATION - PARTNER_REMOVED - PARTNER_APP_UNINSTALLED - AUTH_INTL_PRICE_ELIGIBILITY_UPDATE - BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE - BUSINESS_CAPABILITY_UPDATE WhatsappGroup: type: object description: WhatsApp group object. properties: groupId: type: string description: WhatsApp group ID. example: '120363345678901234@g.us' subject: type: string description: The group subject. maxLength: 128 example: New Purchase Inquiry description: type: string description: The group description. maxLength: 2048 example: Group for purchase inquiries. joinApprovalMode: $ref: '#/components/schemas/WhatsappGroupJoinApprovalMode' suspended: type: boolean description: Whether the group is suspended. example: false creationTimestamp: type: integer format: int64 description: Unix timestamp indicating when the group was created. example: 1739321024 totalParticipantCount: type: integer description: Total number of participants in the group. example: 3 participants: type: array description: Group participants. items: $ref: '#/components/schemas/WhatsappGroupParticipant' WhatsappGroupAsyncResponse: type: object description: Response for asynchronous WhatsApp group operations. properties: requestId: type: string description: The request ID for tracking the asynchronous operation in webhooks. example: REQ_1 status: type: string description: The asynchronous request status. enum: - pending example: pending WhatsappBlockUsersRequest: type: object description: |- Users to block or unblock. Provide at least one non-empty list of phone numbers or WhatsApp Business-scoped user IDs (BSUIDs). You can provide both lists. The combined number of entries in `users` and `userIds` must not exceed 100. anyOf: - required: - users properties: users: minItems: 1 - required: - userIds properties: userIds: minItems: 1 properties: users: type: array maxItems: 100 description: User phone numbers in E.164 format. These share the 100-entry request limit with `userIds`. items: type: string example: - '+12025550101' userIds: type: array maxItems: 100 description: |- WhatsApp Business-scoped user IDs (BSUIDs), including parent BSUIDs. Values are trimmed and normalized to uppercase. These share the 100-entry request limit with `users`. items: type: string example: - 'US.123456789012345' WhatsappBlockUsersResponse: type: object properties: messaging_product: type: string description: Messaging product used for the operation. example: whatsapp block_users: type: object properties: added_users: type: array description: Users successfully blocked. Returned for block operations. items: $ref: '#/components/schemas/WhatsappBlockUser' removed_users: type: array description: Users successfully unblocked. Returned for unblock operations. items: $ref: '#/components/schemas/WhatsappBlockUser' failed_users: type: array description: Users for whom the operation failed. items: type: object properties: input: type: string description: User identifier for the failed operation. errors: type: array description: WhatsApp errors for this user. items: $ref: '#/components/schemas/WhatsappApiError' errors: $ref: '#/components/schemas/WhatsappApiError' WhatsappBlockUser: type: object properties: input: type: string description: User identifier returned for the operation. example: '+12025550101' wa_id: type: string description: WhatsApp ID, when available. example: '12025550101' user_id: type: string description: WhatsApp Business-scoped user ID (BSUID), when available. example: 'US.123456789012345' WhatsappBlockedUsersPage: type: object properties: offset: type: integer description: Always 0 for this cursor-paginated endpoint. Use cursors to navigate. limit: type: integer description: Number of items per page. length: type: integer description: Actual number of items in this page. items: type: array description: Blocked users returned by Meta. items: $ref: '#/components/schemas/WhatsappBlockedUser' cursor: type: object properties: before: type: string description: Pass this value as `pageBefore` to request the previous page. after: type: string description: Pass this value as `pageAfter` to request the next page. WhatsappBlockedUser: type: object properties: phoneNumber: type: string description: User phone number in E.164 format. example: '+12025550101' waId: type: string description: WhatsApp ID. example: '12025550101' userId: type: string description: WhatsApp Business-scoped user ID (BSUID). example: 'US.123456789012345' parentUserId: type: string description: Parent WhatsApp Business-scoped user ID. example: 'US.ENT.123456789012345' WhatsappGroupCreateRequest: type: object required: - subject properties: subject: type: string description: The group subject. maxLength: 128 example: New Purchase Inquiry description: type: string description: The group description. maxLength: 2048 example: Group for purchase inquiries. joinApprovalMode: $ref: '#/components/schemas/WhatsappGroupJoinApprovalMode' description: Defaults to `auto_approve` when omitted. WhatsappGroupInviteLink: type: object description: WhatsApp group invite link object. properties: inviteLink: type: string description: The group invite link. example: 'https://chat.whatsapp.com/AbCdEfGhIjK' WhatsappGroupInviteLinkMessageRequest: type: object description: Provide at least one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored. not: allOf: - not: required: - to - not: required: - recipient required: - templateName - languageCode - parameters properties: to: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' recipient: type: string description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 templateName: type: string description: The name of the approved WhatsApp template. example: group_invite_link languageCode: type: string description: The template language code. example: en_US parameters: type: array description: |- Template body parameters in template variable order. Must include one group invite link parameter with `type=group_id` and `group_id=`. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameter' WhatsappGroupJoinApprovalMode: type: string description: |- WhatsApp group join approval mode. - `approval_required`: New members must be approved before joining. - `auto_approve`: New members can join without approval. enum: - approval_required - auto_approve example: auto_approve WhatsappGroupJoinRequest: type: object description: WhatsApp group join request object. properties: joinRequestId: type: string description: The join request ID. example: join-request-id waId: type: string description: WhatsApp user ID. example: '16315551111' userId: type: string description: Business-scoped user ID. example: US.1234 parentUserId: type: string description: Parent business-scoped user ID. example: US.parent123 username: type: string description: WhatsApp username. example: John creationTimestamp: type: integer format: int64 description: Unix timestamp indicating when the join request was created. example: 1739321024 WhatsappGroupJoinRequestActionRequest: type: object required: - joinRequests properties: joinRequests: type: array description: Join request IDs to approve or reject. items: type: string example: - join-request-id WhatsappGroupJoinRequestActionResponse: type: object description: Result of approving or rejecting group join requests. properties: approvedJoinRequests: type: array description: Approved join request IDs. items: type: string rejectedJoinRequests: type: array description: Rejected join request IDs. items: type: string failedJoinRequests: type: array description: Join requests that failed to be processed. items: $ref: '#/components/schemas/WhatsappGroupFailedJoinRequest' errors: type: array description: Errors returned by WhatsApp. items: type: object additionalProperties: true WhatsappGroupFailedJoinRequest: type: object properties: joinRequestId: type: string description: The join request ID. example: join-request-id errors: type: array description: Errors returned by WhatsApp for this join request. items: type: object additionalProperties: true WhatsappGroupJoinRequestListResponse: type: object description: Cursor-paginated WhatsApp group join request response. properties: data: type: array items: $ref: '#/components/schemas/WhatsappGroupJoinRequest' paging: $ref: '#/components/schemas/WhatsappGroupPaging' WhatsappGroupListItem: type: object description: WhatsApp group list item. properties: groupId: type: string description: WhatsApp group ID. example: '120363345678901234@g.us' subject: type: string description: The group subject. example: New Purchase Inquiry createdAt: type: integer format: int64 description: Unix timestamp indicating when the group was created. example: 1739321024 WhatsappGroupListResponse: type: object description: Cursor-paginated WhatsApp group list response. properties: data: type: array items: $ref: '#/components/schemas/WhatsappGroupListItem' paging: $ref: '#/components/schemas/WhatsappGroupPaging' WhatsappGroupPaging: type: object description: Cursor pagination information. properties: before: type: string description: Cursor for the previous page. example: eyJvIjoiYmVmb3JlIn0 after: type: string description: Cursor for the next page. example: eyJvIjoiYWZ0ZXIifQ WhatsappGroupParticipant: type: object description: WhatsApp group participant object. properties: waId: type: string description: WhatsApp user ID. example: '16315551111' userId: type: string description: Business-scoped user ID. example: US.1234 parentUserId: type: string description: Parent business-scoped user ID. example: US.parent123 username: type: string description: WhatsApp username. example: John WhatsappGroupRemoveParticipant: type: object description: Participant identifier for a group removal request. Provide exactly one of `user`, `fromUserId`, or its compatibility alias `userId`. allOf: - not: allOf: - not: required: - user - not: required: - fromUserId - not: required: - userId - not: anyOf: - required: - user - fromUserId - required: - user - userId - required: - fromUserId - userId properties: user: type: string description: WhatsApp user ID to remove. example: '16315551111' fromUserId: type: string description: Business-scoped user ID to remove. pattern: '^[A-Z]{2}\.[A-Za-z0-9]{1,128}$' example: US.1234 userId: type: string description: Compatibility alias of `fromUserId` for the business-scoped user ID to remove. pattern: '^[A-Z]{2}\.[A-Za-z0-9]{1,128}$' example: US.1234 WhatsappGroupRemoveParticipantsRequest: type: object required: - participants properties: participants: type: array description: Participants to remove. Up to 8 participants are supported in one request. maxItems: 8 items: $ref: '#/components/schemas/WhatsappGroupRemoveParticipant' example: participants: - user: '16315551111' WhatsappGroupUpdateSettingsRequest: type: object description: Contains the group settings to update. At least one of `subject` or `description` is required. not: allOf: - not: required: - subject - not: required: - description properties: subject: type: string description: The group subject. maxLength: 128 example: New Purchase Inquiry description: type: string description: The group description. maxLength: 2048 example: Group for purchase inquiries. WhatsappGroupWebhook: type: object description: WhatsApp group webhook payload. properties: wabaId: type: string description: WhatsApp Business Account ID. example: '123456789012345' displayPhoneNumber: type: string description: The display phone number from WhatsApp webhook metadata. example: '16315551111' phoneNumberId: type: string description: WhatsApp phone number ID. example: '1234567890123456' field: $ref: '#/components/schemas/WhatsappGroupWebhookField' type: $ref: '#/components/schemas/WhatsappGroupWebhookType' requestId: type: string description: The request ID returned by an asynchronous group API operation. example: REQ_1 status: $ref: '#/components/schemas/WhatsappGroupWebhookStatus' groupId: type: string description: WhatsApp group ID. example: '120363345678901234@g.us' messageId: type: string description: YCloud group-message ID. Present only when the status event is linked to a saved outbound group message. example: wam_group_01 inviteLink: type: string description: The group invite link. example: 'https://chat.whatsapp.com/AbCdEfGhIjK' reason: type: string description: The reason for a participant, join request, or removal event. example: invite_link initiatedBy: type: string description: Indicates who initiated a participant removal event. enum: - business - participant example: business joinRequestId: type: string description: The join request ID. example: join-request-id waId: type: string description: WhatsApp user ID for a single participant event. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID for a single participant event. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID for a single participant event. example: US.parent123 customerProfile: $ref: '#/components/schemas/WhatsappGroupCustomerProfile' subject: type: string description: The group subject. example: New Purchase Inquiry description: type: string description: The group description. example: Group for purchase inquiries. joinApprovalMode: $ref: '#/components/schemas/WhatsappGroupJoinApprovalMode' addedParticipants: type: array description: Participants added to the group. items: $ref: '#/components/schemas/WhatsappGroupWebhookParticipant' removedParticipants: type: array description: Participants removed from the group. items: $ref: '#/components/schemas/WhatsappGroupWebhookParticipant' failedParticipants: type: array description: Participants that failed to be added or removed. items: $ref: '#/components/schemas/WhatsappGroupWebhookParticipant' settings: type: array description: Group setting update details. items: $ref: '#/components/schemas/WhatsappGroupWebhookSetting' errors: type: array description: Errors returned by WhatsApp. items: type: object additionalProperties: true contacts: type: array description: Contacts included in group message status webhooks. items: $ref: '#/components/schemas/WhatsappGroupWebhookStatusContact' statuses: type: array description: Group message status details. items: $ref: '#/components/schemas/WhatsappGroupWebhookMessageStatus' webhookTime: type: string format: date-time description: The time at which WhatsApp triggered this webhook. example: '2026-05-13T00:00:00.000Z' dedupeKey: type: string description: Idempotency key for deduplicating group webhook events. example: WABA_ID|REQ_1|group_lifecycle_update|group_create|created WhatsappGroupCustomerProfile: type: object description: WhatsApp customer profile information. properties: name: type: string description: WhatsApp profile name. example: John Doe username: type: string description: WhatsApp username. example: john_doe WhatsappGroupWebhookConversation: type: object description: WhatsApp conversation object included in group message status webhooks. properties: id: type: string description: Conversation ID. example: conversation-id expirationTimestamp: type: integer format: int64 description: Unix timestamp indicating when the conversation expires. example: 1739321024 origin: $ref: '#/components/schemas/WhatsappGroupWebhookConversationOrigin' WhatsappGroupWebhookConversationOrigin: type: object properties: type: type: string description: Conversation origin type. example: service WhatsappGroupWebhookField: type: string description: WhatsApp webhook field that produced the group event. enum: - group_lifecycle_update - group_participants_update - group_settings_update - group_status_update - messages WhatsappGroupWebhookMessageStatus: type: object description: Group message status detail. properties: id: type: string description: WhatsApp message ID. example: wamid.1 status: type: string description: Message status. enum: - sent - delivered - read - failed - expired example: delivered timestamp: type: integer format: int64 description: Unix timestamp indicating when the message status was updated. example: 1739321024 recipientId: type: string description: Recipient group ID. example: '120363345678901234@g.us' recipientType: type: string description: Recipient type. enum: - group example: group recipientParticipantId: type: string description: WhatsApp user ID of the recipient participant. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID of the recipient participant. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID of the recipient participant. example: US.parent123 conversation: $ref: '#/components/schemas/WhatsappGroupWebhookConversation' pricing: $ref: '#/components/schemas/WhatsappGroupWebhookPricing' errors: type: array description: Errors returned by WhatsApp. items: type: object additionalProperties: true WhatsappGroupWebhookParticipant: type: object description: Participant information included in group webhook payloads. properties: input: type: string description: The original participant input. example: US.1234 waId: type: string description: WhatsApp user ID. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID. example: US.parent123 customerProfile: $ref: '#/components/schemas/WhatsappGroupCustomerProfile' errors: type: array description: Errors returned by WhatsApp for this participant. items: type: object additionalProperties: true WhatsappGroupWebhookPricing: type: object description: Pricing information included in group message status webhooks. properties: billable: type: boolean description: Whether the message is billable. example: true pricingModel: type: string description: Pricing model. example: PMP type: type: string description: Pricing type. example: regular category: type: string description: Raw group pricing category reported by Meta. YCloud does not expose the internal MM Lite mapping in this webhook field. enum: - group_marketing - group_utility - group_service example: group_service WhatsappGroupWebhookSetting: type: object description: Group setting update detail. properties: name: type: string description: Setting name. enum: - profile_picture - group_subject - group_description example: group_subject text: type: string description: Text value for subject or description updates. example: New Purchase Inquiry updateSuccessful: type: boolean description: Whether the setting update succeeded. example: true mimeType: type: string description: MIME type for profile picture updates. example: image/jpeg sha256: type: string description: SHA-256 hash for profile picture updates. example: 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae errors: type: array description: Errors returned by WhatsApp for this setting. items: type: object additionalProperties: true WhatsappGroupWebhookStatus: type: string description: WhatsApp group webhook status. enum: - created - failed - deleted - added - removed - left - requested - revoked - updated - suspended - suspend_cleared - sent - delivered - read - expired WhatsappGroupWebhookStatusContact: type: object description: Contact information included in group message status webhooks. properties: customerProfile: $ref: '#/components/schemas/WhatsappGroupCustomerProfile' waId: type: string description: WhatsApp user ID. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID. example: US.parent123 WhatsappGroupWebhookType: type: string description: Specific WhatsApp group event type. enum: - group_create - group_delete - group_participants_add - group_participants_remove - group_join_request_created - group_join_request_revoked - group_settings_update - group_suspend - group_suspend_cleared - message_status 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' fromUserId: type: string description: The customer's WhatsApp Business-scoped user ID (BSUID). example: US.1234 fromParentUserId: type: string description: The customer's parent WhatsApp Business-scoped user ID. example: US.parent123 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' groupId: type: string description: WhatsApp group ID. This field is included when the inbound message is sent in a WhatsApp group. example: '120363345678901234@g.us' 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. - `nfm_reply`: Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging). - `call_permission_reply`: Sent when a customer responds to a call permission request. enum: - button_reply - list_reply - nfm_reply - call_permission_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. nfm_reply: type: object description: Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging). Returned when `type` is `nfm_reply`. properties: name: type: string description: The name of the flow or form being replied to. example: "flow" response_json: type: string description: |- JSON string containing the user's responses to the flow. Contains form field values and flow token. example: '{"flow_token":"unused","screen_0_firstName_0":"王","screen_1_TextInput_1":"123","screen_1_TextInput_0":"11","screen_0_lastName_1":"TESTNAME"}' body: type: string description: The body content of the flow reply message. example: "Sent" call_permission_reply: type: object description: |- Sent when a customer responds to a call permission request. Returned when `type` is `call_permission_reply`. This occurs when WhatsApp prompts users to grant callback permissions after they call your business. properties: response: type: string description: |- The customer's response to the call permission request. - `accept`: User granted permission for business to call back - `reject`: User rejected permission for business to call back enum: - accept - reject example: "accept" expiration_timestamp: type: integer format: int64 description: |- The timestamp (in seconds) when the call permission expires. Only present when response is "accept" and is_permanent is false. example: 1672531200 is_permanent: type: boolean description: |- Whether the permission is permanent or temporary. - `true`: Permanent authorization (no expiration) - `false`: Temporary authorization (expires at expiration_timestamp) example: false response_source: type: string description: |- The source of this permission response. - `user_action`: User explicitly approved or rejected the permission - `automatic`: Automatic permission approval due to the WhatsApp user initiating the call enum: - user_action - automatic example: "user_action" 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. wa_id: type: string description: |- **Added to Webhooks for phone number updates.** New WhatsApp ID of the customer. user_id: type: string description: |- **Added to Webhooks for phone number updates.** The customer's new WhatsApp Business-scoped user ID (BSUID). This field keeps Meta's original snake_case name inside the `system` object. example: 'US.13491208655302741919' parent_user_id: type: string description: |- **Added to Webhooks for phone number updates when parent BSUIDs are enabled.** The customer's new parent WhatsApp Business-scoped user ID. This field keeps Meta's original snake_case name inside the `system` object. example: 'US.ENT.11815799212886844831' 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. new_wa_id: type: string description: |- **Added to Webhooks for phone number updates.** New WhatsApp 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 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' recipient: type: string description: The recipient value submitted in the request when a BSUID or parent BSUID was used. example: US.1234 recipientUserId: type: string description: The recipient's WhatsApp Business-scoped user ID (BSUID). example: US.1234 toUserId: type: string description: Alias of `recipientUserId` kept for compatibility. example: US.1234 parentRecipientUserId: type: string description: The recipient's parent WhatsApp Business-scoped user ID. example: US.ENT.1234 toParentUserId: type: string description: Alias of `parentRecipientUserId` kept for compatibility. example: US.ENT.1234 customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: The recipient's profile information, including WhatsApp username when available. 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. category: type: string description: The Direct Send category, such as `utility` or `authentication`, when applicable. example: utility ttlSeconds: type: integer description: The configured Direct Send message lifetime in seconds, when applicable. example: 600 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`.** pricingModel: $ref: '#/components/schemas/WhatsappPricingModel' description: |- The pricing model of the message. - `PMP`: Per-message pricing applies. - `CBP`: Conversation-based pricing applies. pricingType: $ref: '#/components/schemas/WhatsappPricingType' description: |- The pricing type of the message. This field is only available in PMP (Per-Message Pricing) mode. - `regular`: Indicates the message is billable. - `free_customer_service`: Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window. - `free_entry_point`: Indicates the message is free because it is part of a free-entry point conversation. 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' vcard: type: string description: Optional vCard supplied with the shared contact payload. readOnly: true origin: type: string description: Set to `contact_request` when the user shared the contact in response to a request-contact-info message. example: contact_request readOnly: true 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. required: - type - action properties: type: type: string description: |- **Required.** The type of interactive message you want to send. - `button`: Use for Reply Buttons. - `list`: Use for List Messages. - `cta_url`: Use for Call-To-Action (CTA) URL Button Messages. - `product`: Use for Single Product Messages. - `product_list`: Use for Multi-Product Messages. - `catalog_message`: Use for Catalog Messages. - `location_request_message`: Use for Location Request Messages. - `order_details`: Use for Order Details Messages. - `order_status`: Use for Order Status Messages. - `voice_call`: Use for Voice Call Messages. - `request_contact_info`: Ask the WhatsApp user to share their contact information. - `flow`: Use for Flow Messages. - `carousel`: Use for media carousel message. enum: - button - list - cta_url - product - product_list - catalog_message - location_request_message - order_details - order_status - voice_call - request_contact_info - flow - carousel action: $ref: '#/components/schemas/WhatsappMessageInteractiveAction' body: $ref: '#/components/schemas/WhatsappMessageInteractiveBody' header: $ref: '#/components/schemas/WhatsappMessageInteractiveHeader' footer: $ref: '#/components/schemas/WhatsappMessageInteractiveFooter' allOf: - not: allOf: - properties: type: enum: - button - properties: action: not: required: - buttons - not: allOf: - properties: type: enum: - list - properties: action: not: allOf: - required: - button - sections - properties: sections: items: required: - rows - not: allOf: - properties: type: enum: - cta_url - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - cta_url parameters: required: - display_text - url - not: allOf: - properties: type: enum: - product - properties: action: not: required: - catalog_id - product_retailer_id - not: allOf: - properties: type: enum: - product_list - properties: action: not: allOf: - required: - catalog_id - sections - properties: sections: items: required: - product_items - not: allOf: - properties: type: enum: - catalog_message - properties: action: not: allOf: - required: - name - properties: name: enum: - catalog_message - not: allOf: - properties: type: enum: - location_request_message - properties: action: not: allOf: - required: - name - properties: name: enum: - send_location - not: allOf: - properties: type: enum: - flow - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - flow parameters: required: - flow_message_version - flow_cta not: allOf: - not: required: - flow_id - not: required: - flow_name - not: allOf: - properties: type: enum: - order_details - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - review_and_pay parameters: required: - reference_id - type - currency - total_amount - order - payment_settings allOf: - not: allOf: - properties: type: enum: - physical-goods - not: required: - beneficiaries - not: allOf: - properties: type: enum: - order_status - properties: action: not: allOf: - required: - name - parameters - properties: name: enum: - review_order parameters: required: - reference_id - order - not: allOf: - properties: type: enum: - voice_call - properties: action: not: allOf: - required: - name - properties: name: enum: - voice_call - not: allOf: - properties: type: enum: - request_contact_info - properties: action: not: allOf: - required: - name - properties: name: enum: - request_contact_info - not: allOf: - properties: type: enum: - carousel - properties: action: not: required: - cards - not: allOf: - properties: type: enum: - button - list - cta_url - product_list - catalog_message - location_request_message - order_details - order_status - voice_call - request_contact_info - flow - carousel - properties: body: not: required: - text - not: allOf: - properties: type: enum: - product_list - properties: header: not: allOf: - required: - type - text - properties: type: enum: - text WhatsappMessageInteractiveAction: type: object description: |- **Required.** Action you want the user to perform after reading the `interactive` message. properties: buttons: type: array description: Required for Reply Buttons. You can have up to 3 buttons. minItems: 1 maxItems: 3 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionButton' button: type: string description: |- Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. maxLength: 20 catalog_id: type: string description: |- Required for Single Product Messages and Multi-Product Messages. Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via the [Meta Commerce Manager](https://business.facebook.com/commerce). product_retailer_id: type: string description: |- Required for Single Product Messages. Unique identifier of the product in a catalog. sections: type: array description: |- Required for List Messages and Multi-Product Messages. Array of section objects. Minimum of 1, maximum of 10. minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSection' name: type: string description: |- Action name. Required for Call-To-Action (CTA) buttons. - `cta_url`: Use for Call-To-Action (CTA) URL buttons. - `catalog_message`: Use for Catalog Messages. - `send_location`: Use for Location Request buttons. - `flow`: Use for Flow buttons. - `review_and_pay`: Use for Order Details buttons. - `review_order`: Use for Order Status buttons. - `voice_call`: Use for Voice Call buttons. - `request_contact_info`: Use for Request Contact Information buttons. enum: - cta_url - catalog_message - send_location - flow - review_and_pay - review_order - voice_call - request_contact_info parameters: $ref: '#/components/schemas/WhatsappMessageInteractiveActionParameters' cards: type: array description: |- Required for Carousel Messages. Array of card objects. Minimum of 2, maximum of 10. minItems: 2 maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCard' not: allOf: - not: required: - buttons - not: required: - button - sections - not: required: - catalog_id - product_retailer_id - not: required: - catalog_id - sections - not: required: - name - not: required: - cards WhatsappMessageInteractiveActionButton: type: object description: |- A button object in `interactive` messages. required: - type - reply properties: type: description: The button type. Only `reply` is supported for interactive reply buttons. type: string enum: - reply reply: type: object required: - id - title properties: title: type: string description: |- Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. maxLength: 20 id: type: string description: |- Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. You cannot have leading or trailing spaces when setting the ID. maxLength: 256 WhatsappMessageInteractiveActionCard: type: object description: |- A card object in `interactive` messages. All cards must have the same structure. required: - card_index - type - header - action properties: card_index: type: integer minimum: 0 maximum: 9 description: |- Card index. Unique index for each card (0-9). type: description: The card type. Must be `cta_url` for carousel cards with call-to-action URL buttons. type: string enum: - cta_url header: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardHeader' body: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardBody' action: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardAction' WhatsappMessageInteractiveActionCardAction: type: object description: |- A button object in `interactive` messages. Cards must include either one URL button, or one or more quick-reply buttons. Button types and numbers must match across all cards (for example, if you define a card with 2 quick-reply buttons, all cards must define exactly 2 quick-reply buttons). allOf: - not: allOf: - not: required: - name - parameters - not: required: - buttons - not: allOf: - required: - name - parameters - required: - buttons properties: name: type: string description: |- Required when card action is url button. Must be "cta_url". enum: - cta_url parameters: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardActionParameters' buttons: type: array description: Required when card action is quick reply button. minItems: 1 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionCardActionButton' WhatsappMessageInteractiveActionCardActionButton: type: object required: - type - quick_reply properties: type: description: The button type. Must be `quick_reply` for carousel card quick reply buttons. type: string enum: - quick_reply quick_reply: type: object required: - id - title properties: title: type: string description: |- Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. maxLength: 20 id: type: string description: |- Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 20 characters. You cannot have leading or trailing spaces when setting the ID. maxLength: 20 WhatsappMessageInteractiveActionCardActionParameters: type: object description: |- Required when card action is url button. Only support `display_text` and `url`. Button display text Max 20 chars. required: - display_text - url properties: display_text: type: string description: |- Text of the CTA URL button. Maximum length: 20 bytes. maxLength: 20 example: 'See Docs' url: type: string description: |- URL of the CTA URL button. example: 'https://developers.facebook.com/docs/whatsapp' WhatsappMessageInteractiveActionCardBody: type: object description: |- Optional for card. required: - text properties: text: type: string description: |- Max 160 chars, and up to 2 line breaks. maxLength: 160 WhatsappMessageInteractiveActionCardHeader: type: object required: - type properties: type: description: The media type for the carousel card header. Must be either `image` or `video`. type: string enum: - image - video image: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' video: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' allOf: - not: allOf: - properties: type: enum: - image - not: required: - image - not: allOf: - properties: type: enum: - video - not: required: - video WhatsappMessageInteractiveActionParameters: type: object description: |- Action parameters. Required for Call-To-Action (CTA) buttons. properties: display_text: type: string description: |- Text of the CTA URL button. Maximum length: 20 bytes. maxLength: 20 example: 'See Docs' url: type: string description: |- URL of the CTA URL button. example: 'https://developers.facebook.com/docs/whatsapp' thumbnail_product_retailer_id: type: string description: |- Item SKU number. Labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce). The thumbnail of this item will be used as the message's header image. flow_message_version: type: string description: |- Use for `flow` buttons. Value must be "3". enum: - '3' flow_token: type: string description: |- Use for `flow` buttons. Flow token that is generated by the business to serve as an identifier. Defaults to `unused`. flow_id: type: string description: Conditionally required for `flow` buttons. Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter. flow_name: type: string description: |- Conditionally required for `flow` buttons. The name of the Flow that you created. Cannot be used with the `flow_id` parameter. Changing the Flow name will require updating this parameter to match the new name. flow_cta: type: string description: |- Required for `flow` buttons. Text on the CTA button. For example: "Open flow!". Maximum length: 20 characters. maxLength: 20 example: 'Open flow!' flow_action: type: string description: |- Use for `flow` buttons. Either `navigate` or `data_exchange`. Defaults to `navigate`. enum: - navigate - data_exchange example: 'navigate' flow_action_payload: type: object description: |- Optional when `flow_action` is `navigate`. Use it to select an entry screen and provide initial screen data. If omitted, WhatsApp opens the Flow at its default entry screen. Omit this field for other actions. properties: screen: type: string description: |- The ID of the screen displayed first. It needs to be an **entry** screen. data: type: object description: |- Optional input data for the first screen of the Flow. reference_id: type: string description: |- Required for `review_and_pay` buttons. Unique identifier for the order provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The `reference_id` must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness. type: type: string description: |- Required for `review_and_pay` buttons. The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`. enum: - digital-goods - physical-goods beneficiaries: type: array description: |- Required for `physical-goods` orders sent with `review_and_pay` buttons. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. Beneficiary information isn't shown to users but is needed for legal and compliance reasons. items: $ref: '#/components/schemas/WhatsappMessageOrderBeneficiary' currency: type: string description: |- Required for `review_and_pay` buttons. The currency for this order. Currently the only supported value is `INR`. enum: - INR total_amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: |- Required for `review_and_pay` buttons. The total amount for this order. order: $ref: '#/components/schemas/WhatsappMessageOrderInfo' description: |- Required for `review_and_pay` or `review_order` buttons. For `review_and_pay` buttons, provides order `status`, `items`, `subtotal`, `tax`, etc. For `review_order` buttons, provides only order `status` and `description`. payment_settings: type: array description: |- Required for `review_and_pay` buttons. Payment settings for the order. items: $ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting' not: anyOf: - required: - flow_id - flow_name - allOf: - properties: flow_action: enum: - data_exchange - required: - flow_action - flow_action_payload WhatsappMessageInteractiveActionSection: type: object description: |- WhatsApp Message Interactive Section Object. properties: title: type: string description: |- **Required if the message has more than one section.** Title of the section. Maximum length: 24 characters. maxLength: 24 rows: type: array description: |- Contains a list of rows. You can have a total of 10 rows across your sections. Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional. maxItems: 10 minItems: 1 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSectionRow' product_items: type: array description: |- Required for Multi-Product Messages. Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections. minItems: 1 maxItems: 30 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSectionProductItem' WhatsappMessageInteractiveActionSectionProductItem: type: object required: - product_retailer_id properties: product_retailer_id: type: string description: |- Required for Multi-Product Messages. Unique identifier of the product in a catalog. WhatsappMessageInteractiveActionSectionRow: type: object required: - id - title properties: id: type: string description: |- Unique row ID. Maximum length: 200 characters. maxLength: 200 title: type: string description: |- Row title content. Maximum length: 24 characters. maxLength: 24 description: type: string description: |- Row description content. Maximum length: 72 characters. maxLength: 72 WhatsappMessageInteractiveBody: type: object description: |- Optional for type `product`. Required for other message types. required: - text properties: text: type: string description: |- The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. maxLength: 1024 WhatsappMessageInteractiveFooter: type: object description: |- Optional. An object with the footer of the message. required: - text properties: text: type: string description: |- The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters. maxLength: 60 WhatsappMessageInteractiveHeader: type: object description: |- Required for type `product_list`. Optional for other types. required: - type properties: type: description: The media type for the interactive message header. Determines which media field should be populated (text, image, video, or document). type: string enum: - text - image - video - document text: type: string description: Text for the header. Formatting allows emojis, but not markdown. maxLength: 60 image: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' video: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' document: $ref: '#/components/schemas/WhatsappMessageInteractiveMedia' allOf: - not: allOf: - properties: type: enum: - text - not: required: - text - not: allOf: - properties: type: enum: - image - not: required: - image - not: allOf: - properties: type: enum: - video - not: required: - video - not: allOf: - properties: type: enum: - document - not: required: - document 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. WhatsappMedia: type: object description: |- Represents a WhatsApp media object that has been uploaded via the media upload API. properties: id: type: string description: Unique identifier for the uploaded media. This ID can be used in subsequent message requests. WhatsappMessageInteractiveMedia: type: object description: Media used in an interactive message header. Requests must reference an HTTPS URL. Responses may include the uploaded WhatsApp media ID for compatibility. not: allOf: - not: required: - id - not: required: - link properties: id: type: string readOnly: true description: Uploaded WhatsApp media ID returned in message responses. This response-only field cannot be used to send an interactive message header. link: type: string format: uri pattern: '^https://' description: Publicly accessible HTTPS URL of the media resource. caption: type: string description: Optional media caption. filename: type: string description: Optional filename for document media. WhatsappMessageMedia: type: object description: |- Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). **Note**: Either `id` or `link` must be provided, but not both. These parameters are mutually exclusive. Reference: [WhatsApp Cloud API Media Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object) properties: id: type: string description: >- **Use this when media is uploaded to WhatsApp servers.** Provide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Note: Either `id` or `link` must be provided. Do not provide both. link: type: string description: >- **Use this when sending media directly from your server.** The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Note: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL. Note: Either `id` or `link` must be provided. Do not provide both. caption: type: string description: Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages. filename: type: string description: Describes the filename for the specific document. Use only with `document` media. voice: type: boolean description: >- Whether to send an `audio` message as a WhatsApp voice message. Set to `true` for a voice message. Set to `false`, or omit this field, to send the audio as a regular attachment. This field applies only when the enclosing message `type` is `audio`. allOf: - not: allOf: - not: required: - id - not: required: - link - not: required: - id - link 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: description: Set `type`, then choose the matching message schema branch below. Each branch shows the common fields plus the matching content field required for that message type. At least one of `to` or `recipient` is required. If both are provided, `to` takes precedence and `recipient` is ignored. not: allOf: - not: required: - to - not: required: - recipient oneOf: - $ref: "#/components/schemas/WhatsappMessageTemplateSendRequest" - $ref: "#/components/schemas/WhatsappMessageTextSendRequest" - $ref: "#/components/schemas/WhatsappMessageImageSendRequest" - $ref: "#/components/schemas/WhatsappMessageVideoSendRequest" - $ref: "#/components/schemas/WhatsappMessageAudioSendRequest" - $ref: "#/components/schemas/WhatsappMessageDocumentSendRequest" - $ref: "#/components/schemas/WhatsappMessageStickerSendRequest" - $ref: "#/components/schemas/WhatsappMessageLocationSendRequest" - $ref: "#/components/schemas/WhatsappMessageInteractiveSendRequest" - $ref: "#/components/schemas/WhatsappMessageContactsSendRequest" - $ref: "#/components/schemas/WhatsappMessageReactionSendRequest" discriminator: propertyName: type mapping: template: "#/components/schemas/WhatsappMessageTemplateSendRequest" text: "#/components/schemas/WhatsappMessageTextSendRequest" image: "#/components/schemas/WhatsappMessageImageSendRequest" video: "#/components/schemas/WhatsappMessageVideoSendRequest" audio: "#/components/schemas/WhatsappMessageAudioSendRequest" document: "#/components/schemas/WhatsappMessageDocumentSendRequest" sticker: "#/components/schemas/WhatsappMessageStickerSendRequest" location: "#/components/schemas/WhatsappMessageLocationSendRequest" interactive: "#/components/schemas/WhatsappMessageInteractiveSendRequest" contacts: "#/components/schemas/WhatsappMessageContactsSendRequest" reaction: "#/components/schemas/WhatsappMessageReactionSendRequest" WhatsappCallingConnectRequest: type: object description: Provide at least one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored. not: allOf: - not: required: - to - not: required: - recipient required: - from - sdpType - sdp properties: from: type: string description: The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+6283138205150' to: type: string description: The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+6281361905133' recipient: type: string description: The callee's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 sdpType: type: string description: The SDP type, must be "offer" for connection requests. enum: - offer example: offer sdp: type: string description: |- The Session Description Protocol (SDP) offer information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866). Contains media session parameters for establishing the WebRTC connection. example: "v=0\r o=- 4054442297240208280 2 IN IP4 127.0.0.1\r s=-\r t=0 0\r a=group:BUNDLE 0\r a=extmap-allow-mixed\r a=msid-semantic: WMS 6c364341-f90d-48e6-b497-76e047e3c31a\r m=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 13 110 126\r c=IN IP4 0.0.0.0\r a=rtcp:9 IN IP4 0.0.0.0\r a=ice-ufrag:Dpsa\r a=ice-pwd:oVuOd7HKhA8aWTvspLYACWJe\r a=ice-options:trickle\r a=fingerprint:sha-256 0A:A9:64:82:AD:D5:31:08:38:71:1C:C0:08:AA:CE:93:22:F4:17:2C:B6:F1:8\ F:F1:20:71:38:16:37:18:3F:FA\r a=setup:actpass\r a=mid:0\r a=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level\r a=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\r a=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensi\ ons-01\r a=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid\r a=sendrecv\r a=msid:6c364341-f90d-48e6-b497-76e047e3c31a fa42cdbe-8696-4ee8-bce0-0919d86a223f\r a=rtcp-mux\r a=rtcp-rsize\r a=rtpmap:111 opus/48000/2\r a=rtcp-fb:111 transport-cc\r a=fmtp:111 minptime=10;useinbandfec=1\r a=rtpmap:63 red/48000/2\r a=fmtp:63 111/111\r a=rtpmap:9 G722/8000\r a=rtpmap:0 PCMU/8000\r a=rtpmap:8 PCMA/8000\r a=rtpmap:13 CN/8000\r a=rtpmap:110 telephone-event/48000\r a=rtpmap:126 telephone-event/8000\r a=ssrc:3208712354 cname:bg/Ix8uTnsTsiMoe\r a=ssrc:3208712354 msid:6c364341-f90d-48e6-b497-76e047e3c31a fa42cdbe-8696-4ee8-bce0-0919d86a223f\r\n" WhatsappCallingRequest: type: object properties: phoneId: type: string description: The WhatsApp Business phone number ID. example: "436666719526789" from: type: string description: The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required for connect operations when phoneId is empty. example: '+16315551111' to: type: string description: The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required for outbound call connections. example: '+16315551112' wacid: type: string description: |- The WhatsApp call ID. Required for inbound call operations. This ID is received from the Call Connect webhook when a WhatsApp user initiates the call. example: "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh" sdpType: type: string description: The SDP type. For pre-accept and accept operations, must be "answer". enum: - offer - answer example: answer sdp: type: string description: |- The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866). Required for pre-accept and accept operations. Contains media session parameters for the WebRTC connection. example: "v=0\r o=- 123456789 987654321 IN IP4 192.168.1.1\r s=-\r t=0 0\r ..." WhatsappCallingPreAcceptRequest: type: object required: - phoneId - wacid - sdpType - sdp properties: phoneId: type: string description: The WhatsApp Business phone number ID. example: "461269257068832" wacid: type: string description: |- The WhatsApp call ID. Required for inbound call operations. This ID is received from the Call Connect webhook when a WhatsApp user initiates the call. example: "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIDhEMjc4NEY2QUU4NTA2MTgxNTBGNzQ3N0M\ 4QTBDMTU5HBgNNjI4MzEzODIwNTE1MBUCABUeAA==" sdpType: type: string description: The SDP type for pre-accept operations. Must be "answer". enum: - answer example: answer sdp: type: string description: |- The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866). Contains media session parameters for the WebRTC connection. example: "v=0\r o=- 2239925877841361960 2 IN IP4 127.0.0.1\r s=-\r t=0 0\r a=group:BUNDLE audio\r a=msid-semantic: WMS 0ed5100f-da68-4193-8865-146c1ac7a087\r m=audio 9 UDP/TLS/RTP/SAVPF 111 126\r c=IN IP4 0.0.0.0\r a=rtcp:9 IN IP4 0.0.0.0\r a=ice-ufrag:NCH6\r a=ice-pwd:ogUYxqJDPNn0C5RFif6UlLz6\r a=ice-options:trickle\r a=fingerprint:sha-256 5B:95:C4:E4:8B:2B:06:B6:DB:FB:2C:08:2F:FD:3B:C7:9C:8D:84:4C:97:8D:8\ 4:AC:B2:93:32:B8:20:5C:3C:85\r a=setup:active\r a=mid:audio\r a=sendrecv\r a=msid:0ed5100f-da68-4193-8865-146c1ac7a087 bc955459-4bae-4504-99c8-348944c12b6f\r a=rtcp-mux\r a=rtpmap:111 opus/48000/2\r a=rtcp-fb:111 transport-cc\r a=fmtp:111 minptime=10;useinbandfec=1\r a=rtpmap:126 telephone-event/8000\r a=ssrc:436995058 cname:BIzAP4IgR06SrZ1S\r\n" WhatsappCallingTerminateRequest: type: object required: - phoneId - wacid properties: phoneId: type: string description: The WhatsApp Business phone number ID. example: "461269257068832" wacid: type: string description: |- The WhatsApp call ID. Required for terminate operations. This ID is received from the Call Connect webhook when a WhatsApp user initiates the call. example: "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY\ 1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA==" WhatsappCallingResponse: type: object required: - success properties: wacid: type: string description: The WhatsApp call ID associated with this calling operation. example: "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY\ 1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA==" success: type: boolean description: Indicates whether the calling operation was successful. example: true CallingConnect: type: object description: |- Represents a WhatsApp call connect event. Contains information about the call connection including SDP details and participant information. required: - id - wacid properties: id: type: string description: Unique ID for the call event. example: "call_evt_123456789" wacid: type: string description: The WhatsApp call ID. This ID uniquely identifies the call session. example: "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh" phoneId: type: string description: The WhatsApp Business phone number ID. example: "436666719526789" from: type: string description: The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' fromUserId: type: string description: The caller's WhatsApp Business-scoped user ID (BSUID) for customer-initiated calls. example: US.1234 fromParentUserId: type: string description: The caller's parent WhatsApp Business-scoped user ID for customer-initiated calls. example: US.ENT.1234 to: type: string description: The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551112' toUserId: type: string description: The callee's WhatsApp Business-scoped user ID (BSUID) for business-initiated calls. example: US.1234 toParentUserId: type: string description: The callee's parent WhatsApp Business-scoped user ID for business-initiated calls. example: US.ENT.1234 customerProfile: description: The customer's profile information, including WhatsApp username when available. allOf: - $ref: '#/components/schemas/WhatsappProfile' direction: type: string description: |- The direction of the call. - `USER_INITIATED`: Call initiated by the customer to the business. - `BUSINESS_INITIATED`: Call initiated by the business to the customer. enum: - USER_INITIATED - BUSINESS_INITIATED example: USER_INITIATED sdpType: type: string description: The SDP type for the WebRTC connection. enum: - offer - answer example: offer sdp: type: string description: |- The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866). Contains media session parameters for the WebRTC connection. example: "v=0\r\no=- 123456789 987654321 IN IP4 192.168.1.1\r\ns=-\r\nt=0 0\r\n..." dialTime: type: integer format: int64 description: The time when the call was dialed, in Unix timestamp milliseconds. example: 1640995200000 CallingTerminate: type: object description: |- Represents a WhatsApp call terminate event. Contains information about the call termination including duration and status. required: - id - wacid properties: id: type: string description: Unique ID for the call event. example: "call_evt_123456789" wacid: type: string description: The WhatsApp call ID. This ID uniquely identifies the call session. example: "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh" phoneId: type: string description: The WhatsApp Business phone number ID. example: "436666719526789" from: type: string description: The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' fromUserId: type: string description: The caller's WhatsApp Business-scoped user ID (BSUID) for customer-initiated calls. example: US.1234 fromParentUserId: type: string description: The caller's parent WhatsApp Business-scoped user ID for customer-initiated calls. example: US.ENT.1234 to: type: string description: The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551112' toUserId: type: string description: The callee's WhatsApp Business-scoped user ID (BSUID) for business-initiated calls. example: US.1234 toParentUserId: type: string description: The callee's parent WhatsApp Business-scoped user ID for business-initiated calls. example: US.ENT.1234 customerProfile: description: The customer's profile information, including WhatsApp username when available. allOf: - $ref: '#/components/schemas/WhatsappProfile' direction: type: string description: |- The direction of the call. - `USER_INITIATED`: Call initiated by the customer to the business. - `BUSINESS_INITIATED`: Call initiated by the business to the customer. enum: - USER_INITIATED - BUSINESS_INITIATED example: USER_INITIATED startTime: type: integer format: int64 description: The time when the call started, in Unix timestamp milliseconds. example: 1640995200000 endTime: type: integer format: int64 description: The time when the call ended, in Unix timestamp milliseconds. example: 1640995320000 duration: type: integer format: int64 description: The duration of the call in seconds. example: 120 status: type: string description: |- The final status of the call. - `COMPLETED`: The call was successfully completed. - `FAILED`: The call failed due to an error. enum: - COMPLETED - FAILED example: COMPLETED errorCode: type: string description: Error code when the call status is `FAILED`. Numeric string representing the error. example: '131000' CallingStatusUpdated: type: object description: |- Represents a WhatsApp call status update event. Contains information about status changes during the call lifecycle. required: - wacid - status properties: id: type: string description: Unique ID for the call event (optional field, may not be present). example: "call_evt_123456789" wabaId: type: string description: WhatsApp Business Account ID. example: "188234691048809" wacid: type: string description: The WhatsApp call ID. This ID uniquely identifies the call session. example: "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE" phoneId: type: string description: The WhatsApp Business phone number ID (optional field, may not be present). example: "436666719526789" status: type: string description: |- The current status of the call. - `RINGING`: Business initiated call is ringing the user. - `ACCEPTED`: Business initiated call is accepted by the user. - `REJECTED`: Business initiated call is rejected by the user. enum: - RINGING - ACCEPTED - REJECTED example: RINGING recipientPhone: type: string description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+6281361905133' recipientUserId: type: string description: The recipient's WhatsApp Business-scoped user ID (BSUID). example: US.1234 parentRecipientUserId: type: string description: The recipient's parent WhatsApp Business-scoped user ID. example: US.ENT.1234 customerProfile: description: The customer's profile information, including WhatsApp username when available. allOf: - $ref: '#/components/schemas/WhatsappProfile' 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. example: en 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. required: - card_index 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`. - `gif`: Used when the template `HEADER` component is `GIF`. - `video`: Used when the template `HEADER` component is `VIDEO`. - `document`: Used when the template `HEADER` component is `DOCUMENT`. - `payload`: Used when the template component button type is `QUICK_REPLY`. - `coupon_code`: Used when the template component button type is `COPY_CODE`. - `limited_time_offer`: Used when the template component type is `LIMITED_TIME_OFFER`. - `action`: Used when the template component button type is `CATALOG`, `MPM`, `FLOW`, or `ORDER_DETAILS`. - `order_status`: Used when the template subcategory is `ORDER_STATUS`. - `location`: Used when the template `HEADER` component is `LOCATION`. - `group_id`: Used by WhatsApp group invite link templates. enum: - text - image - gif - video - document - payload - coupon_code - limited_time_offer - action - order_status - location - group_id 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`.** gif: $ref: '#/components/schemas/WhatsappMessageMedia' description: |- **Required when the template `HEADER` format is `GIF`.** 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`.** group_id: type: string description: |- **Required when `type` = `group_id`.** WhatsApp group ID used by group invite link templates. example: '120363345678901234@g.us' required: - type allOf: - not: allOf: - properties: type: enum: [text] - not: required: [text] - not: allOf: - properties: type: enum: [image] - not: required: [image] - not: allOf: - properties: type: enum: [gif] - not: required: [gif] - not: allOf: - properties: type: enum: [video] - not: required: [video] - not: allOf: - properties: type: enum: [document] - not: required: [document] - not: allOf: - properties: type: enum: [payload] - not: required: [payload] - not: allOf: - properties: type: enum: [coupon_code] - not: required: [coupon_code] - not: allOf: - properties: type: enum: [limited_time_offer] - not: required: [limited_time_offer] - not: allOf: - properties: type: enum: [action] - not: required: [action] - not: allOf: - properties: type: enum: [order_status] - not: required: [order_status] - not: allOf: - properties: type: enum: [location] - not: required: [location] - not: allOf: - properties: type: enum: [group_id] - not: required: [group_id] 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 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 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 required: - product_retailer_id 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. required: - expiration_time_ms 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: description: The current status of the payment transaction. Possible values are `pending` (payment initiated but not yet completed) and `captured` (payment successfully completed). $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 x-enum-descriptions: captured: Indicates the payment is successfully completed. pending: Indicates the user attempted but yet to receive success transactions signal. 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' businessUsername: type: string description: Active Business Username for this phone number. The value is a plain username without `@`. example: acme.support businessUsernameStatus: $ref: '#/components/schemas/WhatsappBusinessUsernameStatus' requestedBusinessUsername: type: string description: Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending. example: acme.help businessUsernameUpdatedAt: type: string format: date-time description: The time when the Business Username state was last updated. example: '2026-05-26T12:00:00.000Z' 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 whatsappBusinessManagerMessagingLimit: type: string description: |- The owning business portfolio's messaging limit. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio. See also [phone_number_quality_update webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update). - `TIER_NOT_SET`: The business phone number has not been used to send a message yet. - `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period. - `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period. - `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period. - `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period. - `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations. example: TIER_2K verifiedName: type: string description: Verified name. example: John's Cake Shop ycloudName: type: string readOnly: true description: Optional remark name assigned to this phone number in YCloud. It is populated by the phone-number list, retrieve, and profile GET APIs, and omitted when no remark name is set. example: Support line newName: type: string description: The modified name example: John's Cake 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` or `DEFERRED`. requestedVerifiedName: type: string description: Last requested verified name. rejectionReason: type: string description: Rejection reason. qualityUpdateEvent: $ref: '#/components/schemas/WhatsappPhoneNumberQualityUpdateEventEnum' updateEvent: type: string description: Account update event that triggered this phone number status change. enum: - ACCOUNT_RECONNECTED - ACCOUNT_OFFBOARDED example: ACCOUNT_OFFBOARDED throughputLevel: type: string description: |- Current Meta throughput level of the WhatsApp phone number. - `STANDARD`: Default Cloud API throughput level, currently up to 80 messages per second. - `HIGH`: Upgraded Cloud API throughput level, currently up to 1,000 messages per second, subject to Meta's current Cloud API throughput rules. - `NOT_APPLICABLE`: Throughput level is not applicable to this phone number. enum: - STANDARD - HIGH - NOT_APPLICABLE example: HIGH 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 WhatsappBusinessUsernameStatus: type: string description: |- Business Username state for a WhatsApp business phone number. - `not_set`: No active or pending Business Username exists. - `active`: A Business Username is active. - `reserved`: A requested Business Username is reserved by Meta and may still be under review. - `pending_review`: Legacy compatibility value for an under-review request. New writes use `reserved`. If an active username exists while a new request is reserved or under review, `businessUsernameStatus` is `reserved`, `businessUsername` contains the still-active username, and `requestedBusinessUsername` contains the requested username. enum: - not_set - active - pending_review - reserved WhatsappBusinessUsername: type: object description: Business Username state for a WhatsApp business phone number. properties: id: type: string description: Phone number ID. example: '1234567890123456' wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' 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' businessUsername: type: string description: Active Business Username. The value is a plain username without `@`. example: acme.support businessUsernameStatus: $ref: '#/components/schemas/WhatsappBusinessUsernameStatus' requestedBusinessUsername: type: string description: Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending. example: acme.help businessUsernameUpdatedAt: type: string format: date-time description: The time when the Business Username state was last updated. example: '2026-05-26T12:00:00.000Z' WhatsappBusinessUsernameUpdateRequest: type: object required: - username properties: username: type: string description: |- Business Username to request for the phone number. Send the plain username without `@`. YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission. The value must be 3-35 characters, contain only English letters, numbers, periods, and underscores, and contain at least one English letter. It must not start or end with a period, contain consecutive periods, start with `www`, or end with common domain suffixes such as `.com`, `.org`, `.net`, `.int`, `.edu`, `.gov`, `.mil`, `.us`, `.in`, or `.html`. minLength: 3 maxLength: 35 pattern: '^[A-Za-z0-9._]+$' example: acme.support WhatsappBusinessUsernameSuggestions: type: object description: Reserved Business Username suggestions. properties: data: type: array items: type: string example: - acme.support - acme.help WhatsappBusinessUsernameDeleteResult: type: object description: |- Business Username deletion result. Deleting the active username does not cancel a reserved Business Username request. If a reserved request still exists, the returned `businessUsernameStatus` is `reserved`; otherwise it is `not_set`. properties: success: type: boolean description: Whether the delete request was accepted. example: true id: type: string description: Phone number ID. example: '1234567890123456' wabaId: type: string description: WhatsApp Business Account ID. example: 'whatsapp-business-account-id' phoneNumber: type: string description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' businessUsernameStatus: $ref: '#/components/schemas/WhatsappBusinessUsernameStatus' businessUsernameUpdatedAt: type: string format: date-time description: The time when the Business Username state was last updated. example: '2026-05-26T12:00:00.000Z' WhatsappContactBookEntryDeleteResult: type: object description: Meta's contact book entry deletion result returned by YCloud. required: - success - deleted properties: success: type: boolean description: Always `true` in an HTTP 200 response. example: true deleted: type: boolean description: Meta's deletion result. `true` means Meta reports that it deleted a matching entry. `false` means Meta processed the request but found no matching entry to delete. example: true 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' WhatsappPhoneNumberSettings: type: object description: WhatsApp business phone number settings. properties: calling: type: object description: Calling feature settings for the phone number. properties: id: type: string description: Phone number ID. example: '19213232132' status: type: string description: |- Calling feature status: - `ENABLED`: Calling feature is enabled - `DISABLED`: Calling feature is disabled enum: - ENABLED - DISABLED example: ENABLED iconVisibility: type: string description: |- Calling icon display configuration: - `DEFAULT`: Show icon by default - `DISABLE_ALL`: Hide all calling icons enum: - DEFAULT - DISABLE_ALL example: DEFAULT capture: $ref: '#/components/schemas/CallingCaptureSettings' CallingCaptureSettings: type: object description: Phone-number-level recording and transcription capture settings used for new WhatsApp calls. required: - recordingEnabled - transcriptionEnabled properties: recordingEnabled: type: boolean description: Whether recording capture is enabled. transcriptionEnabled: type: boolean description: Whether transcription capture is enabled. purpose: type: string maxLength: 250 description: Customer-defined capture purpose passed to the Calling provider configuration. Required when either capture switch is enabled. example: quality_assurance announcementLanguage: type: string description: Meta-supported announcement language. Required when either capture switch is enabled. enum: - en - en_US - en_AU - en_CA - en_GB - en_IN - en_NZ - nl - fr - de - hi - it - kn - pt - es - es_ES - te - vi example: en_US CallingMediaUpdated: type: object additionalProperties: false description: Terminal recording or transcription state for an API-sourced WhatsApp call. required: - wacid - phoneId - mediaAssetId - status properties: wacid: type: string description: WhatsApp call ID. example: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE phoneId: type: string description: WhatsApp business phone number ID used for authorized-asset delivery. example: '461269257068832' mediaAssetId: type: string description: YCloud media asset ID used with the call media download API. example: 66b1f0c2e4b05c2d8f1a3b47 status: type: string enum: - AVAILABLE - FAILED example: AVAILABLE error: type: object additionalProperties: false description: Present only when `status` is `FAILED`. required: - code - retryable properties: code: type: string description: Stable failure code. example: CALLING_RECORDING_PROCESSING_FAILED retryable: type: boolean description: Whether retrying the upstream media operation may succeed. example: false 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 ycloudName: type: string readOnly: true description: Optional remark name assigned to this phone number in YCloud. It is populated by the profile GET API and omitted when no remark name is set. example: Support line verifiedName: type: string description: |- The verified name example: verifiedName nameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' newName: type: string description: The modified name example: John's Cake newNameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' 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' WhatsappPhoneNameUpdateRequest: type: object description: |- WhatsApp Phone Number Display Name properties: newName: type: string minLength: 3 maxLength: 150 description: |- The new name you want to modify example: newName WhatsappPhoneNameUpdateResponse: type: object description: |- WhatsApp Phone Number Display Name Modify Result properties: verifiedName: type: string minLength: 3 maxLength: 150 description: |- The verified name example: verifiedName nameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' newName: type: string minLength: 3 maxLength: 150 description: |- The new name you want to modify example: newName newNameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' 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 WhatsappPricingModel: type: string description: |- WhatsApp pricing model. - `PMP`: Per-message pricing applies. - `CBP`: Conversation-based pricing applies. enum: - PMP - CBP WhatsappPricingType: type: string description: |- WhatsApp pricing type. This field is only available in PMP (Per-Message Pricing) mode. - `regular`: Indicates the message is billable. - `free_customer_service`: Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window. - `free_entry_point`: Indicates the message is free because it is part of a free-entry point conversation. enum: - regular - free_customer_service - free_entry_point WhatsappProfile: type: object description: Represents the profile of a WhatsApp account. properties: name: type: string description: Name of the WhatsApp account. example: John username: type: string description: WhatsApp username. example: john_doe WhatsappReviewDecision: type: string description: Used if a decision about WhatsApp accounts or phone numbers has been made. enum: - APPROVED - REJECTED - DEFERRED WhatsappTemplate: type: object description: See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). required: - wabaId - name - language properties: officialTemplateId: type: string description: Official template ID assigned by WhatsApp. This ID is used to identify the template in WhatsApp's system. example: 'official-template-id' 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. example: en 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' ctaUrlLinkTrackingOptedOut: type: boolean description: Whether Meta CTA URL click tracking is disabled. Historical `null` values are returned as `true`. example: true 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' description: |- The WhatsApp template status update event that caused this webhook. For `ARCHIVED`, the template `status` is `ARCHIVED`. For `UNARCHIVED`, the template `status` is the current status returned by Meta, for example `APPROVED`; it does not represent a new approval review. 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 required: - type 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, gif, 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. - `CALL_PERMISSION_REQUEST`: Sending a template message allows you to initiate a user conversation with a call permission request. enum: - BODY - HEADER - FOOTER - BUTTONS - LIMITED_TIME_OFFER - CAROUSEL - CALL_PERMISSION_REQUEST format: &template_component_format type: string description: |- **Required for type `HEADER`.** enum: - TEXT - IMAGE - GIF - VIDEO - DOCUMENT - LOCATION text: &template_component_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: &template_component_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 minItems: 1 items: $ref: '#/components/schemas/WhatsappTemplateComponentButton' add_security_recommendation: &template_component_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: &template_component_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: &template_component_cards type: array description: |- **Required for type `CAROUSEL`.** Carousel templates support up to 10 carousel cards. maxItems: 10 minItems: 1 items: $ref: '#/components/schemas/WhatsappTemplateComponentCard' allOf: - not: allOf: - properties: type: enum: - HEADER - not: required: - format - not: allOf: - properties: type: enum: - BUTTONS - not: required: - buttons - not: allOf: - properties: type: enum: - LIMITED_TIME_OFFER - not: required: - limited_time_offer - not: allOf: - properties: type: enum: - CAROUSEL - not: required: - cards WhatsappTemplateComponentButton: type: object required: - type properties: type: description: The button type that determines the button's behavior when tapped. Supported types include `QUICK_REPLY` (sends predefined text), `URL` (opens a web link), `PHONE_NUMBER` (initiates a call), `COPY_CODE` (copies text to clipboard), `OTP` (one-time password authentication), `CATALOG` (displays product catalog), `MPM` (multi-product message), `FLOW` (WhatsApp Flow), `ORDER_DETAILS` (order review), `VOICE_CALL` (initiates WhatsApp call), and `REQUEST_CONTACT_INFO` (requests the user's contact information). $ref: '#/components/schemas/WhatsappTemplateComponentButtonType' text: type: string description: |- **Required for button type `PHONE_NUMBER` or `URL`.** Button text. **Required for button type `REQUEST_CONTACT_INFO`.** Set it to the fixed value `Share Contact Info`. 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: |- **Deprecated since 2025-07-23. Use `supported_apps` instead.** **One-tap and zero-tap buttons only.** Your Android app's package name. example: 'com.example.myapplication' deprecated: true signature_hash: type: string description: |- **Deprecated since 2025-07-23. Use `supported_apps` instead.** **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' deprecated: true supported_apps: type: array description: |- **One-tap and zero-tap buttons only.** List of supported apps. items: $ref: '#/components/schemas/WhatsappTemplateComponentButtonOtpSupportedApp' 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` is provided. Use either `flow_id` or `flow_name` when referencing an existing Flow. example: '1' flow_name: type: string description: >- **Conditionally required for button type `FLOW`.** The name of the Flow. Cannot be used if `flow_id` is provided. Use either `flow_id` or `flow_name` when referencing an existing Flow. 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. Used to pass Flow JSON content/parameters. flow_action: type: string description: |- **Use for button type `FLOW`.** Either `navigate` or `data_exchange`. Defaults to `navigate`. enum: - navigate - data_exchange 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' app_deep_link: $ref: '#/components/schemas/WhatsappTemplateComponentButtonAppDeepLink' allOf: - not: required: - flow_id - flow_name - not: required: - flow_id - flow_json - not: required: - flow_name - flow_json - not: allOf: - properties: type: enum: - PHONE_NUMBER - not: required: - text - phone_number - not: allOf: - properties: type: enum: - URL - not: required: - text - url - not: allOf: - properties: type: enum: - OTP - not: required: - otp_type - not: allOf: - properties: type: enum: - REQUEST_CONTACT_INFO - not: allOf: - required: - text - properties: text: enum: - Share Contact Info - not: allOf: - properties: type: enum: - FLOW - allOf: - not: required: - flow_id - not: required: - flow_name - not: required: - flow_json - not: allOf: - properties: type: enum: - FLOW flow_action: enum: - navigate - required: - flow_action - not: required: - navigate_screen WhatsappTemplateComponentButtonAppDeepLink: type: object properties: meta_app_id: type: string description: |- Required if using a URL button mapped to a deep link. APP ID. example: '2892949377516980' android_deep_link: type: string description: |- Required if using a URL button component mapped to a deep link.The WhatsApp client will attempt to load this URI if the WhatsApp user taps the button on an Android device. example: 'luckyshrub://deals/summer/' android_fallback_playstore_url: type: string description: |- Optional. URL of a website that the WhatsApp client will attempt to load in the device’s default web browser when the button is tapped but unable to load the Android deep link URI. example: 'https://www.luckyshrub.com/deals/summer/' WhatsappTemplateComponentButtonOtpSupportedApp: description: |- The supported_apps array allows you define pairs of app package names and signing key hashes for up to 5 apps. This can be useful if you have different app builds and want each of them to be able to initiate the handshake: type: object properties: package_name: type: string description: |- Your Android app's package name. example: 'com.example.myapplication' signature_hash: type: string description: |- 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' 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. - `REQUEST_CONTACT_INFO`: Requests that the WhatsApp user share their contact information. The button text is fixed as `Share Contact Info`. enum: - PHONE_NUMBER - URL - QUICK_REPLY - COPY_CODE - OTP - CATALOG - MPM - FLOW - ORDER_DETAILS - VOICE_CALL - REQUEST_CONTACT_INFO 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). required: - components properties: components: type: array minItems: 1 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 required: - type 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' allOf: - not: allOf: - properties: type: enum: - BODY - not: required: - text - not: allOf: - properties: type: enum: - HEADER - not: required: - format - not: allOf: - properties: type: enum: - BUTTONS - not: required: - buttons WhatsappTemplateComponentExample: type: object description: |- **Required** when: - `type` is `HEADER`, and `format` is one of `IMAGE`, `GIF`, `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`, `GIF`, `VIDEO`, or `DOCUMENT`. Supported types: - For `IMAGE`, the URL must end with one of `.jpg`, `.jpeg`, or `.png`, size limit is 5MB. - For `GIF`, the URL must end with `.mp4`, size limit is 3.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: |- **Required only for component type `LIMITED_TIME_OFFER`.** Omit this object for other component types. Its required fields apply only when you include this object. required: - text properties: text: type: string description: |- **Required when you include `limited_time_offer`.** 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. WhatsappTemplateComponentRequest: x-sdk-type-alias: WhatsappTemplateComponent # Request-only variants; response fields remain in WhatsappTemplateComponent. description: Select the component type to show its applicable fields. Only LIMITED_TIME_OFFER components include limited_time_offer. oneOf: - title: BODY type: object required: - type properties: type: type: string enum: - BODY example: BODY text: *template_component_text add_security_recommendation: *template_component_add_security_recommendation example: $ref: '#/components/schemas/WhatsappTemplateComponentExample' - title: HEADER type: object required: - type - format properties: type: type: string enum: - HEADER example: HEADER format: *template_component_format text: *template_component_text example: $ref: '#/components/schemas/WhatsappTemplateComponentExample' - title: FOOTER type: object required: - type properties: type: type: string enum: - FOOTER example: FOOTER text: *template_component_text code_expiration_minutes: *template_component_code_expiration_minutes - title: BUTTONS type: object required: - type - buttons properties: type: type: string enum: - BUTTONS example: BUTTONS buttons: *template_component_buttons - title: LIMITED_TIME_OFFER type: object required: - type - limited_time_offer properties: type: type: string enum: - LIMITED_TIME_OFFER example: LIMITED_TIME_OFFER limited_time_offer: $ref: '#/components/schemas/WhatsappTemplateComponentLimitedTimeOffer' - title: CAROUSEL type: object required: - type - cards properties: type: type: string enum: - CAROUSEL example: CAROUSEL cards: *template_component_cards - title: CALL_PERMISSION_REQUEST type: object required: - type properties: type: type: string enum: - CALL_PERMISSION_REQUEST example: CALL_PERMISSION_REQUEST 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/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. example: en category: description: The template category that determines message pricing and use case. Must be one of `AUTHENTICATION` (one-time passcodes), `MARKETING` (promotions and offers), or `UTILITY` (transactional updates and notifications). $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: description: Array of template components defining the structure and content of the template message. Must include at least a BODY component. May also include HEADER, FOOTER, BUTTONS, and other component types. See WhatsappTemplateComponent for detailed structure. type: array items: $ref: '#/components/schemas/WhatsappTemplateComponentRequest' ctaUrlLinkTrackingOptedOut: type: boolean description: |- **Optional.** Indicates if template button click tracking is disabled. Set to `true` to disable button click tracking on the template, or `false` to enable. You can disable button click tracking on an individual template by setting this field to `true`. Once disabled, button engagement/clicks will not be displayed in the WhatsApp Manager when viewing the template's insights. If not provided or set to `null`, this value defaults to `true`, which means button click tracking is disabled by default. example: true WhatsappTemplateEditRequest: type: object description: The request body to edit a WhatsApp template. required: - components properties: components: type: array items: $ref: '#/components/schemas/WhatsappTemplateComponentRequest' 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 ctaUrlLinkTrackingOptedOut: type: boolean description: |- **Optional.** Indicates if template button click tracking is disabled. Set to `true` to disable button click tracking on the template, or `false` to enable. You can disable button click tracking on an individual template by setting this field to `true`. Once disabled, button engagement/clicks will not be displayed in the WhatsApp Manager when viewing the template's insights. If not provided or set to `null`, this value defaults to `true`, which means button click tracking is disabled by default. example: true 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). - `ARCHIVED`: The template has been archived. Archived templates cannot be sent or edited. - `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 - ARCHIVED - 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). - `ARCHIVED`: Archived. The template status is updated to `ARCHIVED`. - `UNARCHIVED`: Unarchived. The template status is restored to the current status returned by Meta. If the status is `APPROVED`, this event still does not represent a new approval review. - `REINSTATED`: Reinstated. - `PENDING_DELETION`: Pending deletion. enum: - PENDING - APPROVED - REJECTED - IN_APPEAL - PAUSED - FLAGGED - DISABLED - ARCHIVED - UNARCHIVED - 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 WhatsappFlow: type: object description: Represents a WhatsApp Flow. properties: id: type: string description: Flow ID. example: 'flow-1' name: type: string description: Flow name. example: 'My first flow' status: $ref: '#/components/schemas/WhatsappFlowStatus' categories: type: array description: Flow categories. items: $ref: '#/components/schemas/WhatsappFlowCategory' whatsappBusinessAccount: type: object description: WhatsApp Business Account information. properties: id: type: string description: WhatsApp Business Account ID. example: '463056733559090' name: type: string description: WhatsApp Business Account name. example: 'Waba - Name' currency: type: string description: Currency used by the WhatsApp Business Account. example: 'EUR' validationErrors: type: array description: List of validation errors. items: $ref: '#/components/schemas/WhatsappFlowValidationError' jsonVersion: type: string description: Version of the Flow JSON structure. example: '3.0' dataApiVersion: type: string description: Version of the Data API. example: '3.0' endpointUri: type: string description: The endpoint URI for the Flow. example: 'https://example.com/flow-endpoint' WhatsappListFlowItem: type: object description: Represents a list item of WhatsApp Flows. properties: id: type: string description: Flow ID. example: 'flow-1' name: type: string description: Flow name. example: 'My first flow' status: $ref: '#/components/schemas/WhatsappFlowStatus' categories: type: array description: Flow categories. items: $ref: '#/components/schemas/WhatsappFlowCategory' validationErrors: type: array description: List of validation errors. items: $ref: '#/components/schemas/WhatsappFlowValidationError' WhatsappFlowStatus: type: string description: |- Status of the WhatsApp Flow. - `DRAFT`: The Flow is in draft state and can be modified. - `PUBLISHED`: The Flow is published and cannot be modified. - `DEPRECATED`: The Flow is deprecated and cannot be used. enum: - DRAFT - PUBLISHED - DEPRECATED WhatsappFlowCategory: type: string description: |- Category of the WhatsApp Flow. - `SIGN_UP`: For sign-up processes. - `SIGN_IN`: For sign-in processes. - `APPOINTMENT_BOOKING`: For booking appointments. - `LEAD_GENERATION`: For lead generation. - `CONTACT_US`: For contact forms. - `CUSTOMER_SUPPORT`: For customer support. - `SURVEY`: For surveys. - `OTHER`: For other purposes. enum: - SIGN_UP - SIGN_IN - APPOINTMENT_BOOKING - LEAD_GENERATION - CONTACT_US - CUSTOMER_SUPPORT - SURVEY - OTHER WhatsappFlowValidationError: type: object description: Represents a validation error in a WhatsApp Flow. properties: error: type: string description: Error code. example: 'INVALID_PROPERTY_VALUE' errorType: type: string description: Error type. example: 'FLOW_JSON_ERROR' message: type: string description: Error message. example: 'Invalid value found for property ''type''.' lineStart: type: integer description: Start line of the error. example: 10 lineEnd: type: integer description: End line of the error. example: 10 columnStart: type: integer description: Start column of the error. example: 21 columnEnd: type: integer description: End column of the error. example: 34 pointers: type: array description: List of pointers to the error location. items: type: object properties: lineStart: type: integer description: Start line of the error. example: 10 lineEnd: type: integer description: End line of the error. example: 10 columnStart: type: integer description: Start column of the error. example: 21 columnEnd: type: integer description: End column of the error. example: 34 path: type: string description: Path to the error location. example: 'screens[0].layout.children[0].type' WhatsappFlowPreviewUrl: properties: previewUrl: type: string description: The flow preview url example: https://business.facebook.com/wa/manage/flows/123456/preview/?token=xxxx expiresAt: type: string format: date-time example: '2022-03-01T12:00:00.000Z' WhatsappFlowStatusChange: type: object description: |- Represents a WhatsApp Flow status change event. Contains information about the Flow status change, including the Flow ID and the new status. required: - flowId - wabaId - newStatus properties: flowId: type: string description: The unique ID of the Flow. example: "1097420589034000" wabaId: type: string description: WhatsApp Business Account ID. example: "188234691048809" message: type: string description: A human-readable description of the Flow status change. example: "Flow Webhook 3 changed status from DRAFT to PUBLISHED" oldStatus: type: string description: The previous status of the Flow. example: DRAFT newStatus: type: string description: The new status of the Flow. example: PUBLISHED WhatsappUserPreference: properties: wabaId: type: string description: WhatsApp Business Account ID. example: 1234123123 businessPhoneNumber: type: string description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' businessPhoneId: type: string description: Phone number ID. example: '1234567890123456' contactName: type: string description: WhatsApp user name. example: 'John' contactPhoneNumber: type: string description: WhatsApp user phone number. Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' userId: type: string description: The WhatsApp user's Business-scoped user ID (BSUID). example: 'US.13491208655302741918' parentUserId: type: string description: The WhatsApp user's parent Business-scoped user ID. Omitted when parent BSUIDs are not enabled. example: 'US.ENT.11815799212886844830' detail: type: string description: Description of marketing message preference. example: 'User requested to stop marketing messages' category: type: string example: 'marketing_messages' value: type: string description: Marketing message preference. example: 'stop' timestamp: type: string description: Unix timestamp indicating when the webhook was triggered. example: '1739321024000' WhatsappMessageSamplesRequest: description: |- One representative Utility Direct Send sample. Supply the object matching `type`. Do not include `from`, `to`, or `category`. Text and interactive bodies support up to 1024 characters. Samples use text headers, with up to 60 characters in the header or footer. oneOf: - title: Text sample type: object required: - type - text properties: type: type: string enum: - text text: type: object required: - body properties: body: type: string minLength: 1 maxLength: 1024 description: Representative utility message content. URL previews are not supported. - title: Interactive sample type: object required: - type - interactive properties: type: type: string enum: - interactive interactive: description: Use one CTA URL button or up to three reply buttons. Button labels support up to 20 characters. allOf: - $ref: '#/components/schemas/WhatsappMessageInteractive' - type: object required: - body properties: type: type: string enum: - cta_url - button header: type: object required: - type - text properties: type: type: string enum: - text text: type: string maxLength: 60 WhatsappMessageSamplesResponse: type: object properties: success: type: boolean description: Whether Meta successfully processed the sample. example: true category: type: string description: The category Meta detected for the sample. Use utility content for Utility Direct Send. enum: - UTILITY - MARKETING - AUTHENTICATION example: UTILITY WhatsappMessageTemplateSendRequest: title: Template message type: object required: - from - type - template properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - template description: Must be `template` for this request body variant. example: template context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). An explicit value overrides the template TTL. If omitted, YCloud inherits a positive template TTL up to 43200 seconds; otherwise, Meta uses its default TTL. An inherited value below 30 seconds fails validation. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean template: description: The WhatsApp template message object containing the template name, language, and optional component parameters for variable substitution in the template. $ref: "#/components/schemas/WhatsappMessageTemplate" example: from: "+16315551111" to: "+16315551111" type: template template: name: sample_whatsapp_template language: code: en policy: deterministic WhatsappMessageTextSendRequest: title: Text message type: object required: - from - type - text properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - text description: Must be `text` for this request body variant. example: text context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean text: description: The text message object containing the message body text to send to the recipient. $ref: "#/components/schemas/WhatsappMessageText" example: from: "+16315551111" to: "+16315551111" type: text text: body: Hello from YCloud! WhatsappMessageImageSendRequest: title: Image message type: object required: - from - type - image properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - image description: Must be `image` for this request body variant. example: image context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean image: description: The image message object containing the media ID or link and optional caption for the image to send. $ref: "#/components/schemas/WhatsappMessageMedia" example: from: "+16315551111" to: "+16315551111" type: image image: id: MEDIA_ID caption: Product image WhatsappMessageVideoSendRequest: title: Video message type: object required: - from - type - video properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - video description: Must be `video` for this request body variant. example: video context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean video: description: The video message object containing the media ID or link and optional caption for the video to send. $ref: "#/components/schemas/WhatsappMessageMedia" example: from: "+16315551111" to: "+16315551111" type: video video: id: MEDIA_ID caption: Product video WhatsappMessageAudioSendRequest: title: Audio message type: object required: - from - type - audio properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - audio description: Must be `audio` for this request body variant. example: audio context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean audio: description: The audio message object containing the media ID or link for the audio file to send. $ref: "#/components/schemas/WhatsappMessageMedia" example: from: "+16315551111" to: "+16315551111" type: audio audio: id: MEDIA_ID WhatsappMessageDocumentSendRequest: title: Document message type: object required: - from - type - document properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - document description: Must be `document` for this request body variant. example: document context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean document: description: The document message object containing the media ID or link and optional filename and caption for the document to send. $ref: "#/components/schemas/WhatsappMessageMedia" example: from: "+16315551111" to: "+16315551111" type: document document: id: MEDIA_ID filename: invoice.pdf WhatsappMessageStickerSendRequest: title: Sticker message type: object required: - from - type - sticker properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - sticker description: Must be `sticker` for this request body variant. example: sticker context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean sticker: description: The sticker message object containing the media ID or link for the sticker to send. Only static and animated stickers in WebP format are supported. $ref: "#/components/schemas/WhatsappMessageMedia" example: from: "+16315551111" to: "+16315551111" type: sticker sticker: id: MEDIA_ID WhatsappMessageLocationSendRequest: title: Location message type: object required: - from - type - location properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - location description: Must be `location` for this request body variant. example: location context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean location: description: The location message object containing latitude, longitude, and optional name and address of the location to send. $ref: "#/components/schemas/WhatsappMessageLocation" example: from: "+16315551111" to: "+16315551111" type: location location: latitude: 37.422 longitude: -122.084 name: Googleplex address: 1600 Amphitheatre Pkwy, Mountain View, CA WhatsappMessageInteractiveSendRequest: title: Interactive message type: object required: - from - type - interactive properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - interactive description: Must be `interactive` for this request body variant. example: interactive context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean interactive: description: The interactive message object containing buttons, lists, or other interactive elements that allow recipients to respond with structured input. $ref: "#/components/schemas/WhatsappMessageInteractive" example: from: "+16315551111" to: "+16315551111" type: interactive interactive: type: button body: text: Do you want to continue? action: buttons: - type: reply reply: id: 'yes' title: 'Yes' WhatsappMessageContactsSendRequest: title: Contacts message type: object required: - from - type - contacts properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - contacts description: Must be `contacts` for this request body variant. example: contacts context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean contacts: description: Required when `type` is `contacts`. items: $ref: "#/components/schemas/WhatsappMessageContact" type: array example: from: "+16315551111" to: "+16315551111" type: contacts contacts: - name: formatted_name: John Smith phones: - phone: "+16315551111" type: CELL WhatsappMessageReactionSendRequest: title: Reaction message type: object required: - from - type - reaction properties: from: description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' type: string to: description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided. example: '+16315551111' type: string recipient: description: The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided. example: US.1234 type: string customerProfile: $ref: "#/components/schemas/WhatsappProfile" description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios. type: type: string enum: - reaction description: Must be `reaction` for this request body variant. example: reaction context: $ref: "#/components/schemas/WhatsappMessageContext" externalId: 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. type: string category: description: >- **Optional.** Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`. Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates. Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages. enum: - utility - authentication example: utility type: string ttlSeconds: description: >- **Optional.** Message time-to-live in seconds for Direct Send `utility` or `authentication` messages. The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used. example: 600 maximum: 43200 minimum: 30 type: integer useDirectSend: default: false description: >- **Optional.** Whether to send the message through Direct Send. Defaults to `false`. Set this to `true` to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See [Utility Direct Send](/en/api-reference/guides/whatsapp-platform/best-practices/direct-send). For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are: - Text messages - Interactive Call-to-Action URL button messages - Interactive reply button messages type: boolean templateName: type: string description: >- **Optional.** Business-defined template name for a Utility Direct Send message submitted through synchronous `POST /v2/whatsapp/messages/sendDirectly` or asynchronous `POST /v2/whatsapp/messages`. The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored. The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send. example: order_update_ds filterUnsubscribed: description: >- **Optional.** If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean filterBlocked: description: >- **Optional.** If set to `true`, the message will not be sent to users in your block list. Defaults to `false`. Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`. Not applicable to `POST /v2/whatsapp/messages/sendDirectly`. type: boolean reaction: description: The reaction message object containing the emoji and the message ID of the message to react to. $ref: "#/components/schemas/WhatsappMessageReaction" example: from: "+16315551111" to: "+16315551111" type: reaction reaction: message_id: wamid.BgNODYxN... emoji: 👍 ApiKeyDTO: type: object properties: headers: type: array items: $ref: '#/components/schemas/ApiKeyParamDTO' query_params: type: array items: $ref: '#/components/schemas/ApiKeyParamDTO' body_params: type: array items: $ref: '#/components/schemas/ApiKeyParamDTO' anyOf: - required: - headers properties: headers: minItems: 1 - required: - query_params properties: query_params: minItems: 1 - required: - body_params properties: body_params: minItems: 1 description: At least one item is required across headers, query_params, and body_params. additionalProperties: false ApiKeyParamDTO: type: object properties: field_name: type: string minLength: 1 value: type: string minLength: 1 writeOnly: true prefix: type: string required: - field_name - value additionalProperties: false BodyNodeDTO: type: object properties: type: type: string description: type: string required: type: array items: type: string properties: type: object additionalProperties: type: string items: type: string binding: $ref: '#/components/schemas/ParameterBindingDTO' additionalProperties: false ConnectionStatusDTO: type: object properties: status: type: string enum: - PENDING_OAUTH - ACTIVE - EXPIRED - ERROR error_message: type: string additionalProperties: false ConnectorAuthConfigDTO: type: object properties: oauth2_client_credentials: $ref: '#/components/schemas/OAuth2ClientCredentialsDTO' api_key: $ref: '#/components/schemas/ApiKeyDTO' additionalProperties: false ConnectorDTO: type: object properties: id: type: string name: type: string description: type: string base_url: type: string auth_type: type: string enum: - OAUTH2 - OAUTH2_CLIENT_CREDENTIALS - API_KEY - BASIC - CUSTOM - NONE auth_config: $ref: '#/components/schemas/ConnectorAuthConfigDTO' mtls_config: $ref: '#/components/schemas/MtlsConfigDTO' connection_status: $ref: '#/components/schemas/ConnectionStatusDTO' user_auth_injection_config: $ref: '#/components/schemas/UserAuthInjectionConfigDTO' connector_protocol: type: string enum: - HTTP - MCP description: Connector protocol. Omit on creation to use Meta’s HTTP default. The protocol cannot change after creation; omit on update to preserve it. nullable: true mcp_tool_sync: $ref: '#/components/schemas/ConnectorMcpToolSyncDTO' additionalProperties: false ConnectorLogStatsDTO: type: object properties: data: type: array items: $ref: '#/components/schemas/LogEntryDTO' stats: $ref: '#/components/schemas/StatsDTO' additionalProperties: false ConnectorMcpToolSyncDTO: type: object nullable: true required: - status properties: status: type: string enum: - ERROR - PENDING - READY description: Tool discovery state. ERROR indicates discovery failure even when the connector operation succeeds. last_attempted_at: type: integer format: int64 nullable: true description: Last discovery attempt, in Unix seconds. last_successful_at: type: integer format: int64 nullable: true description: Last successful discovery, in Unix seconds. fingerprint: type: string nullable: true tool_count: type: integer nullable: true additionalProperties: false ConnectorToolDTO: type: object properties: id: type: string name: type: string description: type: string request_definition: $ref: '#/components/schemas/ConnectorToolRequestDefinitionDTO' user_auth_required: type: boolean user_auth_action_config: $ref: '#/components/schemas/ConnectorToolUserAuthActionConfigDTO' transformation_spec: $ref: '#/components/schemas/ConnectorToolTransformationSpecDTO' additionalProperties: false ConnectorToolRequestDefinitionDTO: type: object properties: method: type: string minLength: 1 enum: - GET - POST - PUT - DELETE - PATCH path: type: string minLength: 1 path_parameters: type: object additionalProperties: $ref: '#/components/schemas/ParameterNodeDTO' query_parameters: type: object additionalProperties: $ref: '#/components/schemas/ParameterNodeDTO' headers: type: object additionalProperties: $ref: '#/components/schemas/ParameterNodeDTO' body: $ref: '#/components/schemas/RequestBodyDefinitionDTO' required: - method - path additionalProperties: false ConnectorToolRunResultDTO: type: object properties: output: type: string status: type: string additionalProperties: false ConnectorToolTransformationSpecDTO: type: object nullable: true required: - version - steps properties: version: type: integer enum: - 1 steps: type: array maxItems: 5 items: $ref: '#/components/schemas/ConnectorToolTransformationStepDTO' additionalProperties: false description: Ordered response transformation. On create, omission or null means no transformation. On update, omission preserves the current transformation, null deletes it, and an object sets it. Responses contain Meta’s returned configuration; absence does not confirm a submitted configuration. ConnectorToolTransformationStepDTO: type: object required: - kind properties: kind: type: string enum: - allowlist - case - catalog - decorate_url - dedupe - dehydrate - filter - first_nonempty - first_nonnull - first_nonzero - format - html_escape - lookup - math - proxy_image - reshape - shadow_allowlist - string_replace - truncate target: type: string nullable: true params: type: string nullable: true description: Kind-specific parameters as a JSON object encoded in a string. A math expression supports at most four nested levels. Parameters are forwarded without evaluation or rewriting. additionalProperties: false ConnectorToolUserAuthActionConfigDTO: type: object properties: user_action_tool_type: type: string minLength: 1 enum: - auth - refresh user_auth_token_path: type: string minLength: 1 refresh_token_path: type: string expires_at_path: type: string expires_at_type: type: string enum: - absolute - relative_seconds required: - user_action_tool_type - user_auth_token_path additionalProperties: false LogEntryDTO: type: object properties: event_time: type: string failure_code_name: type: string error_message: type: string tool_name: type: string occurrences: type: integer format: int32 last_seen: type: string additionalProperties: false MtlsConfigDTO: type: object properties: has_certificate: type: boolean fingerprint: type: string expires_at: type: integer format: int64 subject: type: string client_certificate: type: string ca_certificate: type: string additionalProperties: false OAuth2ClientCredentialsDTO: type: object properties: token_url: type: string minLength: 1 scopes_to_request: type: array items: type: string token_request_content_type: type: string enum: - application/x-www-form-urlencoded - application/json client_id: type: string minLength: 1 client_secret: type: string minLength: 1 writeOnly: true required: - token_url - scopes_to_request - client_id - client_secret additionalProperties: false ParameterBindingDTO: type: object properties: kind: type: string value: type: string macro: type: string enum: - WHATSAPP_PHONE_NUMBER - WHATSAPP_PHONE_NUMBER_NATIONAL - WHATSAPP_IDENTITY_HASH - WHATSAPP_CURRENT_STATUS_ID - WHATSAPP_BSUID - USER_MESSAGE - WHATSAPP_CONVERSATION_ID - WHATSAPP_MESSAGE_ID - INSTAGRAM_IGSID - INSTAGRAM_CONVERSATION_ID description: Official binding macro. Accepting an Instagram macro does not enable Instagram entities or guarantee its value for WhatsApp consumers. additionalProperties: false ParameterNodeDTO: type: object properties: type: type: string description: type: string required: type: boolean binding: $ref: '#/components/schemas/ParameterBindingDTO' additionalProperties: false PublicCreateConnectorRequest: type: object properties: name: type: string minLength: 1 description: type: string minLength: 1 base_url: type: string minLength: 1 auth_type: type: string minLength: 1 enum: - OAUTH2 - OAUTH2_CLIENT_CREDENTIALS - API_KEY - BASIC - CUSTOM - NONE auth_config: $ref: '#/components/schemas/ConnectorAuthConfigDTO' user_auth_injection_config: $ref: '#/components/schemas/UserAuthInjectionConfigDTO' requires_certificate: type: boolean connector_protocol: type: string enum: - HTTP - MCP description: Connector protocol. Omit on creation to use Meta’s HTTP default. The protocol cannot change after creation; omit on update to preserve it. required: - name - description - base_url - auth_type additionalProperties: false PublicCreateConnectorToolRequest: type: object properties: name: type: string minLength: 1 description: type: string minLength: 1 request_definition: $ref: '#/components/schemas/ConnectorToolRequestDefinitionDTO' user_auth_required: type: boolean user_auth_action_config: $ref: '#/components/schemas/ConnectorToolUserAuthActionConfigDTO' transformation_spec: $ref: '#/components/schemas/ConnectorToolTransformationSpecDTO' required: - name - description - request_definition - user_auth_required additionalProperties: false PublicRunConnectorToolRequest: type: object properties: input: type: string additionalProperties: false PublicUpdateConnectorRequest: type: object properties: name: type: string minLength: 1 description: type: string minLength: 1 base_url: type: string minLength: 1 auth_type: type: string minLength: 1 enum: - OAUTH2 - OAUTH2_CLIENT_CREDENTIALS - API_KEY - BASIC - CUSTOM - NONE auth_config: $ref: '#/components/schemas/ConnectorAuthConfigDTO' user_auth_injection_config: $ref: '#/components/schemas/UserAuthInjectionConfigDTO' requires_certificate: type: boolean connector_protocol: type: string enum: - HTTP - MCP description: Connector protocol. Omit on creation to use Meta’s HTTP default. The protocol cannot change after creation; omit on update to preserve it. required: - name - description - base_url - auth_type additionalProperties: false PublicUpdateConnectorToolRequest: type: object properties: name: type: string minLength: 1 description: type: string minLength: 1 request_definition: $ref: '#/components/schemas/ConnectorToolRequestDefinitionDTO' user_auth_required: type: boolean user_auth_action_config: $ref: '#/components/schemas/ConnectorToolUserAuthActionConfigDTO' transformation_spec: $ref: '#/components/schemas/ConnectorToolTransformationSpecDTO' required: - name - description - request_definition - user_auth_required additionalProperties: false PublicUpsertConnectorApiKeyRequest: type: object properties: api_key_config: $ref: '#/components/schemas/ApiKeyDTO' required: - api_key_config additionalProperties: false PublicUpsertConnectorCertificateRequest: type: object properties: client_certificate: type: string minLength: 1 client_key: type: string minLength: 1 ca_certificate: type: string required: - client_certificate - client_key additionalProperties: false PublicUpsertConnectorOAuthRequest: type: object properties: oauth_config: $ref: '#/components/schemas/OAuth2ClientCredentialsDTO' required: - oauth_config additionalProperties: false RequestBodyDefinitionDTO: type: object properties: content_type: type: string minLength: 1 enum: - application/json params: type: object additionalProperties: $ref: '#/components/schemas/BodyNodeDTO' required: type: array items: type: string required: - content_type - params additionalProperties: false StatsDTO: type: object properties: start_count: type: integer format: int32 success_count: type: integer format: int32 exception_count: type: integer format: int32 success_rate: type: number avg_latency_s: type: number p95_latency_s: type: number p99_latency_s: type: number time_window_seconds: type: integer format: int32 additionalProperties: false UserAuthInjectionConfigDTO: type: object properties: location: type: string minLength: 1 enum: - body - headers - path - query field_name: type: string minLength: 1 prefix: type: string minLength: 1 additionalProperties: false required: - location - field_name - prefix MetaBusinessAgentSettings: type: object properties: agent_id: type: string channel: type: string enum: [ email, instagram, line, messenger, sms, tiktok, unknown, webchat, whatsapp ] rollout: $ref: '#/components/schemas/MetaBusinessAgentSettingsRollout' handoff: $ref: '#/components/schemas/MetaBusinessAgentSettingsHandoff' followup: $ref: '#/components/schemas/MetaBusinessAgentSettingsFollowup' ai_audience: type: string enum: [ ALLOWLISTED_ONLY, EVERYONE ] MetaBusinessAgentSettingsReplaceRequest: type: object properties: agent_id: type: string rollout: $ref: '#/components/schemas/MetaBusinessAgentSettingsRollout' handoff: $ref: '#/components/schemas/MetaBusinessAgentSettingsHandoff' followup: $ref: '#/components/schemas/MetaBusinessAgentSettingsFollowup' ai_audience: type: string enum: [ ALLOWLISTED_ONLY, EVERYONE ] never_say_phrases: type: array description: Omit to preserve, send an empty array to clear, or send the complete replacement list. items: type: string MetaBusinessAgentSettingsRollout: type: object required: [ enabled ] properties: enabled: type: boolean MetaBusinessAgentSettingsHandoff: type: object required: [ enabled ] properties: enabled: type: boolean message_selection: type: string description: "`message` is required when this value is `CUSTOM`." enum: [ DEFAULT, AGENT, CUSTOM ] message: type: string MetaBusinessAgentSettingsFollowup: type: object required: [ enabled ] properties: enabled: type: boolean followup_interval_in_seconds: type: integer format: int32 enum: [ 0, 300, 900, 1800, 3600, 7200, 28800, 86400 ] description: Follow-up interval in seconds when follow-up is enabled. message: type: string MetaBusinessAgentBudgetResponse: type: object required: [ budgets ] properties: budgets: type: array description: The complete Budget collection. Each `(unit_type, time_window)` pair is unique. An empty array means unlimited usage. items: $ref: '#/components/schemas/MetaBusinessAgentBudget' MetaBusinessAgentBudgetReplaceRequest: type: object required: [ budgets ] properties: budgets: type: array description: The complete replacement collection. Each `(unit_type, time_window)` pair must be unique. An empty array removes all limits. items: $ref: '#/components/schemas/MetaBusinessAgentBudgetInput' MetaBusinessAgentBudget: allOf: - $ref: '#/components/schemas/MetaBusinessAgentBudgetInput' - type: object required: [ budget_id ] properties: budget_id: type: string minLength: 1 MetaBusinessAgentBudgetInput: type: object description: Within a Budget collection, each `(unit_type, time_window)` pair must be unique. required: [ unit_type, time_window, max_budget ] properties: budget_id: type: string description: Required when replacing an existing Budget; omit for a new Budget. unit_type: type: string enum: [ token, ai_turn ] time_window: type: string enum: [ one_day, seven_days, fourteen_days, thirty_days ] max_budget: type: integer format: int64 minimum: 1 MetaBusinessAgentConversationTurnPage: type: object required: [ data ] properties: data: type: array items: $ref: '#/components/schemas/MetaBusinessAgentConversationTurn' paging: $ref: '#/components/schemas/MetaBusinessAgentConversationTurnPaging' MetaBusinessAgentConversationTurn: type: object required: [ turn_id, conversation_id, steps ] properties: turn_id: type: string minLength: 1 conversation_id: type: string minLength: 1 description: App-scoped opaque identifier for the conversation containing this turn. message_id: type: string description: WhatsApp Cloud API message ID associated with this turn, when available. e2e_latency_ms: type: integer format: int64 minimum: 0 timestamp: type: integer format: int64 minimum: 0 description: Turn timestamp as Unix epoch milliseconds. steps: type: array items: $ref: '#/components/schemas/MetaBusinessAgentConversationTurnStep' MetaBusinessAgentConversationTurnStep: type: object required: [ type ] properties: type: type: string enum: [ LLM_CALL, TOOL_CALL ] latency_ms: type: integer format: int64 minimum: 0 status: type: string enum: [ SUCCESS, ERROR, TIMEOUT ] llm_output_preview: type: string tool_name: type: string tool_input: type: string tool_output: type: string MetaBusinessAgentConversationTurnPaging: type: object required: [ cursors ] properties: cursors: $ref: '#/components/schemas/MetaBusinessAgentConversationTurnCursors' previous: type: string next: type: string description: Present when another page is available, even if the current `data` array is empty. MetaBusinessAgentConversationTurnCursors: type: object properties: before: type: string after: type: string MetaBusinessAgentApiError: type: object description: Sanitized details from a failed Meta Business Agent upstream request. properties: title: type: string detail: type: string type: type: string status: type: integer format: int32 requestId: type: string