← Files YCloud Developer KitARCHIVED FILE
references/ycloud-api-v2.yaml
428 KB · Oct 5, 2026 · 18:33 UTC
# 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: WhatsApp Messages
- name: WhatsApp Groups
- name: WhatsApp Calling
- name: WhatsApp Phone Numbers
- name: WhatsApp Templates
- name: WhatsApp Flows
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 event.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomEventSendRequest'
required: true
responses:
200:
description: Successfully sent the event.
/emails:
post:
summary: Send an email
operationId: email-send
tags:
- Emails
description: Sends an outbound email message.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSendRequest'
required: true
responses:
200:
description: The request is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Email'
/sms:
post:
summary: Send an SMS
description: Sends an outbound text message.
operationId: sms-send
tags:
- SMS
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SmsSendRequest'
description: SMS request that needs to be sent.
required: true
responses:
200:
description: The request is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Sms'
get:
summary: List SMS records
tags:
- SMS
operationId: sms-list
description: Returns a paginated list of SMS messages you've previously sent.
x-group-parameters: true
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/includeTotal'
- $ref: '#/components/parameters/filter_createTime_gte-default_1d'
- $ref: '#/components/parameters/filter_createTime_lte'
- $ref: '#/components/parameters/filter_id'
responses:
200:
description: Successfully retrieved a paginated list of objects.
content:
application/json:
schema:
$ref: '#/components/schemas/SmsPage'
/unsubscribers:
post:
summary: Create an unsubscriber
description: |-
Creates an unsubscriber.
An unsubscriber is a configuration item representing that customers opt out of receiving messages from your business.
**A customer and a channel form a unique identifier for an unsubscriber.**
operationId: unsubscriber-create
tags:
- Unsubscribers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UnsubscriberCreateRequest'
required: true
responses:
200:
description: Successfully created an unsubscriber.
content:
application/json:
schema:
$ref: '#/components/schemas/Unsubscriber'
get:
summary: List unsubscribers
description: Returns a paginated list of unsubscribers.
operationId: unsubscriber-list
tags:
- Unsubscribers
x-group-parameters: true
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/includeTotal'
- $ref: '#/components/parameters/pageAfter'
- name: filter.customer
in: query
schema:
type: string
description: |-
The customer who has opted out.
example: '+16315551111'
- name: filter.channel
in: query
schema:
$ref: '#/components/schemas/UnsubscriberChannel'
- name: filter.regionCode
in: query
schema:
type: string
description: |-
Region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
responses:
200:
description: Successfully retrieved a paginated list of objects.
content:
application/json:
schema:
$ref: '#/components/schemas/UnsubscriberPage'
/unsubscribers/{customer}:
get:
summary: List all unsubscribers by customer
description: Returns all unsubscribers for the specified customer.
operationId: unsubscriber-list-all-by-customer
tags:
- Unsubscribers
parameters:
- $ref: '#/components/parameters/customer-in_path_for_unsubscriber'
responses:
200:
description: Successfully retrieved the unsubscribers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Unsubscriber'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/unsubscribers/{customer}/{channel}:
get:
summary: Retrieve an unsubscriber
description: Retrieves the unsubscriber for the specified customer and channel.
operationId: unsubscriber-retrieve-by-customer-and-channel
tags:
- Unsubscribers
parameters:
- $ref: '#/components/parameters/customer-in_path_for_unsubscriber'
- $ref: '#/components/parameters/channel-in_path_for_unsubscriber'
responses:
200:
description: Successfully retrieved the unsubscribers.
content:
application/json:
schema:
$ref: '#/components/schemas/Unsubscriber'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete an unsubscriber
description: Deletes the unsubscriber for the specified customer and channel.
operationId: unsubscriber-delete-by-customer-and-channel
tags:
- Unsubscribers
parameters:
- $ref: '#/components/parameters/customer-in_path_for_unsubscriber'
- $ref: '#/components/parameters/channel-in_path_for_unsubscriber'
responses:
200:
description: Successfully deleted the unsubscriber.
content:
application/json:
schema:
$ref: '#/components/schemas/Unsubscriber'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/verify/verifications:
post:
summary: Start a verification
description: |-
Starts a verification by sending an SMS, voice, or email message to the recipient.
This verification is charged once the message is sent successfully.
operationId: verification-send
tags:
- Verify
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationSendRequest'
description: Verification request that needs to be sent.
required: true
responses:
200:
description: The request is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Verification'
/verify/verificationChecks:
post:
summary: Check a verification
tags:
- Verify
operationId: verification-check
description: |-
Checks a verification with a phone number, an email address, or a verification ID.
A `pending` verification status changes to `approved` once you receive a response with the `valid` parameter is `true`. An approved verification cannot be checked anymore.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationCheckRequest'
required: true
responses:
200:
description: Successfully processed the verification check.
content:
application/json:
schema:
$ref: '#/components/schemas/VerificationCheck'
/voices:
post:
summary: Send a voice code
description: Sends an outbound voice call verification code.
operationId: voice-send
tags:
- Voices
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceSendRequest'
description: Voice call request that needs to be sent.
required: true
responses:
200:
description: The request is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Voice'
get:
summary: List voice records
description: Returns a paginated list of voice calls you've previously sent.
operationId: voice-list
tags:
- Voices
x-group-parameters: true
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/includeTotal'
- $ref: '#/components/parameters/filter_createTime_gte-default_1d'
- $ref: '#/components/parameters/filter_createTime_lte'
- $ref: '#/components/parameters/filter_id'
responses:
200:
description: Successfully retrieved a paginated list of objects.
content:
application/json:
schema:
$ref: '#/components/schemas/VoicePage'
/webhookEndpoints:
post:
summary: Create a webhook endpoint
tags:
- Webhook Endpoints
operationId: webhook_endpoint-create
description: Creates a webhook endpoint listening for specific events.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointCreateRequest'
required: true
responses:
200:
description: Successfully created a webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
get:
summary: List webhook endpoints
tags:
- Webhook Endpoints
operationId: webhook_endpoint-list
description: Returns a paginated list of webhook endpoints.
x-group-parameters: true
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/includeTotal'
responses:
200:
description: Successfully retrieved a paginated list of objects.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointPage'
/webhookEndpoints/{id}:
get:
summary: Retrieve a webhook endpoint
tags:
- Webhook Endpoints
operationId: webhook_endpoint-retrieve
description: Retrieves the webhook endpoint with the given ID.
parameters:
- $ref: '#/components/parameters/id-in_path_for_webhook_endpoint'
responses:
200:
description: Successfully retrieved the webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
patch:
summary: Update a webhook endpoint
tags:
- Webhook Endpoints
operationId: webhook_endpoint-update
description: Updates a webhook endpoint, such as url, events, status.
parameters:
- $ref: '#/components/parameters/id-in_path_for_webhook_endpoint'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointUpdateRequest'
required: true
responses:
200:
description: Successfully updated the webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete a webhook endpoint
tags:
- Webhook Endpoints
operationId: webhook_endpoint-delete
description: Deletes a webhook endpoint.
parameters:
- $ref: '#/components/parameters/id-in_path_for_webhook_endpoint'
responses:
200:
description: Successfully deleted the webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/webhookEndpoints/{id}/rotateSecret:
post:
summary: Rotate a webhook endpoint secret
tags:
- Webhook Endpoints
operationId: webhook_endpoint-rotate-secret
description: Generates a new secret for a webhook endpoint.
parameters:
- $ref: '#/components/parameters/id-in_path_for_webhook_endpoint'
responses:
200:
description: Successfully rotated the webhook endpoint secret.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsapp/businessAccounts:
get:
summary: List WABAs
tags:
- WhatsApp Business Accounts
operationId: whatsapp_business_account-list
description: Returns a paginated list of WhatsApp business accounts you've registered.
x-group-parameters: true
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/includeTotal'
- $ref: '#/components/parameters/filter_accountReviewStatus-WABA'
responses:
200:
description: Successfully retrieved a paginated list of objects.
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappBusinessAccountPage'
/whatsapp/businessAccounts/{id}:
get:
summary: Retrieve a WABA
tags:
- WhatsApp Business Accounts
operationId: whatsapp_business_account-retrieve
description: Retrieves a WABA you've registered.
parameters:
- name: id
in: path
description: WhatsApp Business Account ID.
required: true
schema:
type: string
example: 'whatsapp-business-account-id'
responses:
200:
description: Successfully retrieved the WABA.
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappBusinessAccount'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsapp/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'
/whatsapp/messages/sendDirectly:
post:
summary: Send a message directly
operationId: whatsapp_message-send-directly
tags:
- WhatsApp Messages
description: |-
Sends an outbound WhatsApp message directly.
The message is submitted to the WhatsApp Business API synchronously. Typically used for sending OTP and instant messages.
The response body field `error.whatsappApiError` is included if we tried to request the WhatsApp Business API and got an error response.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappMessageSendRequest'
required: true
responses:
200:
description: The request is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappMessage'
/whatsapp/messages:
post:
summary: Enqueue a message
operationId: whatsapp_message-send
tags:
- WhatsApp Messages
description: |-
Enqueues an outbound WhatsApp message for sending.
Queued messages will be submitted to the WhatsApp Business API asynchronously.
For WhatsApp `template` messages, the referenced template must be in `APPROVED` status. `ARCHIVED` templates cannot be sent.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappMessageSendRequest'
required: true
responses:
200:
description: The request is successfully accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappMessage'
/whatsapp/messages/{id}:
get:
summary: Retrieve a message
operationId: whatsapp_message-retrieve
tags:
- WhatsApp Messages
description: Retrieves a WhatsApp message you've previously sent.
parameters:
- $ref: '#/components/parameters/id-in_path'
responses:
200:
description: Successfully retrieved the object.
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappMessage'
404:
description: The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/whatsapp/{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.
parameters:
- $ref: '#/components/parameters/groupId-in_path'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappGroupRemoveParticipantsRequest'
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'
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.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappTemplateCreateRequest'
required: true
responses:
200:
description: Successfully created a WhatsApp template.
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappTemplate'
get:
summary: List templates
operationId: whatsapp_template-list
tags:
- WhatsApp Templates
description: |-
Returns a paginated list of WhatsApp templates you've previously created.
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'
components:
securitySchemes:
api_key:
type: apiKey
name: X-API-Key
in: header
parameters:
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}'
schemas:
Balance:
type: object
required:
- amount
- currency
properties:
amount:
type: number
format: double
description: Balance of current account.
example: 190.0765
currency:
type: string
description: |-
Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).
example: USD
Contact:
type: object
description: Represents a contact.
required:
- id
properties:
id:
type: string
description: Unique ID for the object.
example: 1693364594105000026
maxLength: 255
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"
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:
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"
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:
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
- TIME
- ARRAY
example: "BOOLEAN"
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.
required:
- eventName
properties:
eventName:
type: string
description: |-
Name of the event.
One of the custom event names you previously defined.
example: 'unique_event_name'
occurTime:
type: string
format: date-time
description: |-
The time at which the event occurred, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`,
if not provided, the current time will be used.
example: '2022-06-01T12:00:00.000Z'
objectId:
type: string
description: |-
ID of the object that the event is associated with.
For events defined with `objectType` as `CONTACT`, the `objectId` should be a `contact` ID. Alternatively, you can use the `contactPhoneNumber` field to specify the contact.
contactPhoneNumber:
type: string
description: |-
The phone number of the contact for events defined with `objectType` as `CONTACT`.
properties:
type: object
description: The properties of the custom event.
additionalProperties:
type: object
example:
property1: 'value1'
property2: 'value2'
Email:
type: object
required:
- id
properties:
id:
type: string
description: Unique ID for the object.
minLength: 6
maxLength: 128
from:
$ref: '#/components/schemas/Mailbox'
description: The sender's email address.
to:
type: array
description: The intended recipients' email addresses.
items:
$ref: '#/components/schemas/Mailbox'
cc:
type: array
description: Recipients who will receive a copy of the email.
items:
$ref: '#/components/schemas/Mailbox'
bcc:
type: array
description: Recipients who will receive a blind carbon copy of the email.
items:
$ref: '#/components/schemas/Mailbox'
replyTo:
type: array
description: If this field exists, then the reply should go to the addresses indicated in that field and not to the address(es) indicated in the `from` field.
items:
$ref: '#/components/schemas/Mailbox'
subject:
type: string
description: |-
The email subject, which contains a short string identifying the topic of the message.
maxLength: 255
summary:
type: string
description: |-
This is a summary of your email. Max length: 70.
example: This is a summary.
maxLength: 70
contentType:
$ref: '#/components/schemas/EmailContentType'
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
callbackUrl:
type: string
description: |-
Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api.
Note: We recommend configuring Webhook Endpoints instead.
example: https://httpbin.org/anything?tag=api-email
createTime:
type: string
format: date-time
description: The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
example: '2022-06-01T12:00:00.000Z'
totalRecipients:
type: integer
format: int32
description: Total recipients of this message, including `to`, `cc` and `bcc`.
example: 3
totalPrice:
type: number
format: double
description: Total price of this message.
example: 0.0085
currency:
type: string
description: |-
Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).
example: USD
EmailContentType:
type: string
description: The MIME type of the email content (`text/html` or `text/plain`). Be aware that We won't count click and open events for the type `text/plain`.
enum:
- text/html
- text/plain
x-enum-varnames:
- TEXT_HTML
- TEXT_PLAIN
EmailDelivery:
type: object
description: Represents an email delivery report.
required:
- emailId
- recipientAddress
properties:
emailId:
type: string
description: Unique ID for the related email you've previously sent.
minLength: 6
maxLength: 128
recipientAddress:
type: string
description: A recipient's email address.
example: tom@example.com
status:
type: string
description: |-
Delivery status of the email to the specific recipient address.
- `sending`: The messaging request is accepted by our system.
- `failed`: The message failed to be sent from our system.
- `sent`: The message has been sent from our system.
- `delivered`: Our system has received a delivery receipt indicating that message is delivered.
- `undelivered`: Our system has received a delivery receipt indicating that message is not delivered.
enum:
- sending
- failed
- sent
- delivered
- undelivered
example: failed
errorCode:
type: string
description: Error code when the email is undeliverable.
example: 402
errorMessage:
type: string
description: Error message when the email is undeliverable.
example: Unsubscribes
externalId:
type: string
description: The `externalId` you set when you sent the email.
bizType:
type: string
description: |-
This can be either empty or one of `email`, or `verify`. Defaults to `email`.
- `email`: Indicates that the message is sent via the **Email** product.
- `verify`: Indicates that the message is sent via the **Verify** product.
example: 'email'
verificationId:
type: string
description: |-
The verification ID. Included only when `bizType` is `verify`.
example: VERIFICATION-ID
EmailSendRequest:
type: object
required:
- from
- to
- subject
- content
properties:
from:
type: string
description: |-
- The sender's email. Its domain should be one that has been registered and activated in your account.
- The sender's email address is required while the sender's name is optional. For example, both `support@example.com` and `Sender<support@example.com>` work.
example: 'SupportTeam<support@example.com>'
to:
type: string
description: |-
- The intended recipients' email addresses.
- Supports a comma-separated list of one or more addresses. Max items: 100.
example: 'to1@example.com,Nick<to2@example.com>'
subject:
type: string
description: |-
The email subject, which contains a short string identifying the topic of the message. Max length: 255.
maxLength: 255
content:
type: string
description: |-
- The email body. Max size: 150 KB.
- Variables in the form of `#var_1#` are supported, they should be used together with the `variables` parameter. Variable keys only support letters, digits, and the underline character (`_`).
- You can use the [Test Templates](https://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<cc2@example.com>'
bcc:
type: string
description: Recipients who will receive a blind carbon copy of the email.
example: 'bcc1@example.com,Nick<bcc2@example.com>'
replyTo:
type: string
description: If this field exists, then the reply should go to the addresses indicated in that field and not to the address(es) indicated in the `from` field.
summary:
type: string
description: |-
This is a summary of your email. Max length: 70.
example: This is a summary.
maxLength: 70
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
callbackUrl:
type: string
description: |-
Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api.
Note: We recommend configuring Webhook Endpoints instead.
example: https://httpbin.org/anything?tag=api-email
Error:
type: object
required:
- status
- code
properties:
status:
type: integer
format: int32
pattern: '[45]\d{2}'
description: HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
example: 404
code:
type: string
description: One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
example: NOT_FOUND
message:
type: string
description: A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
example: The requested resource does not exist.
target:
type: string
description: The target of the error.
example: ''
docUrl:
type: string
description: A URL to more information about the error.
example: ''
requestId:
type: string
description: Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
example: 'req_1KjtKI80IKoaJNa6n6p'
whatsappApiError:
$ref: '#/components/schemas/WhatsappApiError'
description: |-
The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.
ErrorResponse:
type: object
required:
- error
properties:
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.
Event:
type: object
description: |-
Represents a webhook event payload.
Every event contains certain common properties: `id`, `type`, `apiVersion`, `createTime`.
Each event may also contain some properties unique to the event. For example, `sms` is returned when `type` is `sms.message.updated`.
required:
- id
- type
- apiVersion
- createTime
properties:
id:
type: string
description: Unique ID for the event.
minLength: 6
maxLength: 128
type:
$ref: '#/components/schemas/EventType'
apiVersion:
type: string
description: The API version used to render this event.
example: v2
createTime:
type: string
format: date-time
description: The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
example: '2022-06-01T12:00:00.000Z'
emailDelivery:
$ref: '#/components/schemas/EmailDelivery'
description: Included when `type` is `email.delivery.updated`.
sms:
$ref: '#/components/schemas/Sms'
description: Included when `type` is `sms.message.updated`.
smsInbound:
$ref: '#/components/schemas/SmsInbound'
description: Included when `type` is `sms.inbound.received`.
voice:
$ref: '#/components/schemas/Voice'
description: Included when `type` is `voice.message.updated`.
whatsappBusinessAccount:
$ref: '#/components/schemas/WhatsappBusinessAccount'
description: Included when `type` is `whatsapp.business_account.deleted`, `whatsapp.business_account.reviewed`, or `whatsapp.business_account.updated`.
whatsappInboundMessage:
$ref: '#/components/schemas/WhatsappInboundMessage'
description: Included when `type` is `whatsapp.inbound_message.received`.
whatsappMessage:
$ref: '#/components/schemas/WhatsappMessage'
description: Included when `type` is `whatsapp.message.updated`.
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`, or `whatsapp.template.category_updated`.
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`.
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.echoes
- 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.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.note.created
- contact.note.updated
- contact.note.deleted
- contact.unsubscribe.created
- contact.unsubscribe.deleted
- whatsapp.user.preferences
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 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 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 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.
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
errorCode:
type: string
description: Error code when the message is undeliverable.
createTime:
type: string
format: date-time
description: The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`.
example: '2022-03-01T12:00:00.000Z'
updateTime:
type: string
format: date-time
description: The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`.
example: '2022-03-01T12:00:00.000Z'
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
callbackUrl:
type: string
description: |-
Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api.
Note: We recommend configuring Webhook Endpoints instead.
example: https://httpbin.org/anything?tag=api-sms
bizType:
type: string
description: |-
This can be either empty or one of `sms`, or `verify`. Defaults to `sms`.
- `sms`: Indicates that the message is sent via the **SMS** product.
- `verify`: Indicates that the message is sent via the **Verify** product.
example: 'sms'
verificationId:
type: string
description: |-
The verification ID. Included only when `bizType` is `verify`.
example: VERIFICATION-ID
SmsInbound:
type: object
description: Represents an inbound SMS message, which means a user replies to your message.
properties:
id:
type: string
description: Unique ID of the message.
from:
type: string
description: The user's phone number who sent the message to your registered sender ID, formatted in [E.164](https://en.wikipedia.org/wiki/E.164) format.
example: '+16315551111'
to:
type: string
description: The receiver's phone number, which is one of your registered Sender IDs.
text:
type: string
description: The text of this message.
sendTime:
type: string
format: date-time
description: The time at which this message was sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
example: '2022-06-01T12:00:00.000Z'
SmsPage:
type: object
description: Represents a given page of SMS messages.
allOf:
- $ref: '#/components/schemas/Page'
properties:
items:
description: An array containing SMS objects.
type: array
items:
$ref: '#/components/schemas/Sms'
UnsubscriberPage:
type: object
description: Represents a given page of unsubscriber objects.
allOf:
- $ref: '#/components/schemas/Page'
properties:
items:
description: An array containing unsubscriber objects.
type: array
items:
$ref: '#/components/schemas/Unsubscriber'
cursor:
$ref: '#/components/schemas/PageCursor'
Verification:
type: object
required:
- id
properties:
id:
type: string
description: ID of the verification.
example: ve6j7n8i
status:
$ref: '#/components/schemas/VerificationStatus'
to:
type: string
description: Recipient of the verification.
example: '+16315551111'
channel:
$ref: '#/components/schemas/VerificationChannel'
sendTime:
type: string
format: date-time
description: The time at which this verification was sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
example: '2022-06-01T12:00:00.000Z'
totalPrice:
type: number
format: double
description: |-
Total price of this verification.
example: 0.0085
currency:
type: string
description: |-
Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).
example: USD
smsFallbackEnabled:
type: boolean
description: |-
Whether sms fallback is enabled or not.
Applicable when `channel` is `whatsapp`. If enabled, we will try to send the verification code via sms when the WhatsApp message is failed.
smsFallback:
$ref: '#/components/schemas/VerificationFallback'
description: Included when `smsFallbackEnabled` is `true`.
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
VerificationChannel:
type: string
description: |-
Supports several independent channels for verification:
- `sms`: Sends an SMS message with a verification code.
- `voice`: Makes a voice call with a verification code.
- `email_code`: Sends an email with a verification code.
- `whatsapp`: Sends a WhatsApp message with a verification code.
enum:
- sms
- voice
- email_code
- whatsapp
example: sms
VerificationCheck:
type: object
required:
- id
- valid
properties:
id:
type: string
description: ID of this verification check.
example: vc8f92c20
valid:
type: boolean
description: Whether the verification code is valid for this check.
example: false
status:
$ref: '#/components/schemas/VerificationStatus'
to:
type: string
description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format or email address.
example: '+16315551111'
channel:
$ref: '#/components/schemas/VerificationChannel'
VerificationCheckRequest:
type: object
properties:
verificationId:
type: string
description: ID of the verification to be checked. One of `verificationId` or `to` is required.
example: vid
to:
type: string
description: The recipient's phone number or email address. One of `verificationId` or `to` is required.
example: '+16315551111'
code:
type: string
description: The verification to be checked.
example: '123456'
VerificationFallback:
type: object
description: Contains information about verification fallback. For example, you can enable sms fallback for WhatsApp verification messages.
properties:
supported:
type: boolean
description: Whether this fallback you requested is supported. If `false` is returned, it means that there are errors for this fallback, and this fallback will not be triggered.
unsupportedReason:
type: string
description: The reason why the fallback is unsupported, e.g, `PARAM_INVALID`, `SMS_SIGNATURE_UNAVAILABLE`, `SENDER_ID_UNAVAILABLE`, or `MESSAGING_REGION_UNSUPPORTED`.
example: SENDER_ID_UNAVAILABLE
unsupportedDetail:
type: string
description: The detail message why the fallback is unsupported.
example: This Sender ID is not registered.
VerificationSendRequest:
type: object
required:
- channel
- to
properties:
channel:
$ref: '#/components/schemas/VerificationChannel'
to:
type: string
description: |-
The recipient's phone number or email address depending on `channel`.
- Phone number: In [E.164](https://en.wikipedia.org/wiki/E.164) format. Applicable when `channel` is `sms` or `voice`.
- Email address: For example, `tom@example.com`. Applicable when `channel` is `email_code`.
example: '+16315551111'
code:
type: string
description: Verification code to be sent. This field is optional. If not provided, we will automatically generate a code.
maxLength: 8
minLength: 4
example: '123456'
senderId:
type: string
description: |-
[Sender ID](https://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:
$ref: '#/components/schemas/UnsubscriberType'
customer:
type: string
description: |-
The customer who has opted out.
For `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
example: '+16315551111'
channel:
$ref: '#/components/schemas/UnsubscriberChannel'
regionCode:
type: string
description: |-
The customer's region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
example: 'US'
UnsubscriberChannel:
type: string
description: |-
Channel of unsubscriber.
- `whatsapp`: Indicates that the customer opts out of receiving WhatsApp messages from your business.
enum:
- whatsapp
UnsubscriberType:
type: string
description: |-
Type of unsubscriber.
- `PHONE_NUMBER`: Indicates that the `customer` is a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
enum:
- PHONE_NUMBER
Voice:
type: object
required:
- id
- to
properties:
id:
type: string
description: Unique ID for the object.
minLength: 6
maxLength: 128
to:
type: string
description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
example: '+16315551111'
verificationCode:
type: string
description: The verification code to be sent, 4 to 6 digits.
example: '123456'
language:
type: string
description: |-
[ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html).
example: 'en'
regionCode:
type: string
description: |-
[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
example: 'US'
totalSegments:
type: integer
format: int32
minimum: 1
description: Number of message segments. It's always 1 for voice calls.
example: 1
totalPrice:
type: number
format: double
description: Total price of this message.
example: 0.05
currency:
type: string
description: |-
Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).
example: USD
status:
type: string
description: |-
Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`.
- `accepted`: The messaging request is accepted by our system.
- `failed`: The message failed to be sent from our system.
- `sent`: The message has been sent from our system.
- `delivered`: Our system has received a delivery receipt indicating that message is delivered.
- `undelivered`: Our system has received a delivery receipt indicating that message is not delivered.
example: sent
enum:
- accepted
- failed
- sent
- delivered
- undelivered
errorCode:
type: string
description: Error code when the message is undeliverable.
createTime:
type: string
format: date-time
description: The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`.
example: '2022-03-01T12:00:00.000Z'
updateTime:
type: string
format: date-time
description: The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`.
example: '2022-03-01T12:00:00.000Z'
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
callbackUrl:
type: string
description: |-
Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api.
Note: We recommend configuring Webhook Endpoints instead.
example: https://httpbin.org/anything?tag=api-voice
bizType:
type: string
description: |-
This can be either empty or one of `voice`, or `verify`. Defaults to `voice`.
- `voice`: Indicates that the message is sent via the **Voice** product.
- `verify`: Indicates that the message is sent via **Verify** product.
example: 'voice'
verificationId:
type: string
description: |-
The verification ID. Included only when `bizType` is `verify`.
example: VERIFICATION-ID
VoicePage:
type: object
description: Represents a given page of Voice Calls.
allOf:
- $ref: '#/components/schemas/Page'
properties:
items:
description: An array containing Voice objects.
type: array
items:
$ref: '#/components/schemas/Voice'
VoiceSendRequest:
type: object
required:
- to
- verificationCode
properties:
to:
type: string
description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
example: '+16315551111'
verificationCode:
type: string
description: The verification code to be sent, 4 to 6 digits.
example: '123456'
language:
type: string
description: |-
[ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). If not specified, language will be set as `en` by default. Notably, in certain countries or regions, language will be automatically set as the local language due to the regional restrictions.
Applicable languages:
`ar`: Arabic
`de`: German
`en`: English
`es`: Spanish
`fr`: French
`id`: Indonesian
`it`: Italian
`pt`: Portuguese
`ru`: Russian
`tr`: Turkish
`vi`: Vietnamese
`zh`: Chinese
example: en
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
callbackUrl:
type: string
description: |-
Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api.
Note: We recommend configuring Webhook Endpoints instead.
example: https://httpbin.org/anything?tag=api-voice
WebhookEndpoint:
type: object
required:
- id
properties:
id:
type: string
description: Unique ID for the object.
example: wh627c8640675de8fc689ab9d9
url:
type: string
description: The URL of the webhook endpoint.
example: https://httpbin.org/anything?tag=api
enabledEvents:
type: array
description: The list of events to enable for this endpoint.
example: [ "whatsapp.message.updated", "whatsapp.inbound_message.received" ]
items:
type: string
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:
type: object
description: |-
Additional data about the error. A string or map.
- For template APIs, this field is a string describing the reason for the error.
- For message APIs, this field is a map with property `details` describing the reason for the error.
WhatsappAuthIntlRateEligibilityCountry:
type: object
description: |-
Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries:
- June 1, 2024 – Indonesia (country calling code +62, country code `ID`)
- July 1, 2024 – India (country calling code +91, country code `IN`)
See also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates).
properties:
countryCode:
type: string
description: |-
[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
example: 'IN'
startTime:
type: string
format: date-time
description: Date when newly-opened authentication conversations are subject to authentication-international rates, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2024-07-01T00:00:00.000Z`.
example: '2024-07-01T00:00:00.000Z'
WhatsappBusinessAccount:
type: object
description: |-
Represents a specific [WhatsApp Business Account (WABA)](https://developers.facebook.com/docs/whatsapp/overview/business-accounts).
properties:
id:
type: string
description: WhatApp Business Account ID.
name:
type: string
description: User-friendly name to differentiate WhatsApp Business Accounts.
currency:
type: string
description: The currency in which the payment transactions for the WhatsApp Business Account will be processed.
messageTemplateNamespace:
type: string
description: Namespace string for the message templates that belong to the WhatsApp Business Account.
accountReviewStatus:
$ref: '#/components/schemas/WhatsappBusinessAccountReviewStatus'
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 also [WhatsApp Business Platform Policy Violations](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/violations).
example: SCAM
restrictions:
type: array
description: Used to report restrictions imposed on the WABA, when that WABA violates [WhatsApp Business Platform policies](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement).
items:
$ref: '#/components/schemas/WhatsappBusinessAccountRestrictionInfo'
authIntlRateEligibilityCountries:
type: array
description: |-
Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries:
- June 1, 2024 – Indonesia (country calling code +62, country code `ID`)
- July 1, 2024 – India (country calling code +91, country code `IN`)
See also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates).
items:
$ref: '#/components/schemas/WhatsappAuthIntlRateEligibilityCountry'
primaryBusinessLocation:
type: string
description: |-
Your primary business location is the country where your business is based. It will appear in the Business Manager under the Primary Business Location field starting May 1, 2024.
[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
example: 'US'
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
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.
enum:
- DISABLED_UPDATE
- ACCOUNT_RESTRICTION
- ACCOUNT_VIOLATION
- PARTNER_REMOVED
- PARTNER_APP_UNINSTALLED
- AUTH_INTL_PRICE_ELIGIBILITY_UPDATE
- BUSINESS_PRIMARY_LOCATION_COUNTRY_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
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 exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.
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=<groupId>`.
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` or `fromUserId`.
properties:
user:
type: string
description: WhatsApp user ID to remove.
example: '16315551111'
fromUserId:
type: string
description: Business-scoped user ID to remove. Also accepts `userId` as an alias.
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'
WhatsappGroupUpdateSettingsRequest:
type: object
description: Contains the group settings to update. At least one of `subject` or `description` is required.
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'
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.
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: Pricing category.
example: 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
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.
new_wa_id:
type: string
description: |-
**Added to Webhooks for phone number updates.**
New WhatsApp ID of the customer.
type:
type: string
description: |-
Supported types are:
- `user_changed_number`: for a user changed number notification.
- `user_identity_changed`: for user identity changed notification.
user:
type: string
description: |-
**Added to Webhooks for identity updates.**
The new WhatsApp user ID of the customer.
WhatsappInboundMessageText:
type: object
description: |-
When the notification describes a text message, the text object provides the body of the text message.
properties:
body:
type: string
description: Message text.
WhatsappInboundMessageType:
type: string
description: |-
WhatsApp inbound message type.
See also [WhatsApp webhook messages object](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object).
enum:
- text
- image
- video
- audio
- document
- sticker
- contacts
- location
- interactive
- button
- reaction
- request_welcome
- order
- system
- unsupported
WhatsappMessage:
type: object
description: WhatsApp outbound message object.
required:
- id
- wabaId
- from
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.
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'
WhatsappMessageContactAddress:
type: object
description: |-
Full contact address(es) formatted as an addresses object.
properties:
street:
type: string
description: Street number and name.
city:
type: string
description: City name.
state:
type: string
description: State abbreviation.
zip:
type: string
description: ZIP code.
country:
type: string
description: Full country name.
country_code:
type: string
description: Two-letter country abbreviation.
type:
type: string
description: Standard values are `HOME` and `WORK`.
example: WORK
WhatsappMessageContactEmail:
type: object
description: |-
Contact email address(es) formatted as an emails object.
properties:
email:
type: string
description: Email address.
type:
type: string
description: Standard values are `HOME` and `WORK`.
example: WORK
WhatsappMessageContactName:
type: object
description: Full contact name formatted as a name object.
required:
- formatted_name
properties:
formatted_name:
type: string
description: Full name, as it normally appears.
first_name:
type: string
description: First name.
last_name:
type: string
description: Last name.
middle_name:
type: string
description: Middle name.
suffix:
type: string
description: Name suffix.
prefix:
type: string
description: Name prefix.
WhatsappMessageContactOrg:
type: object
description: Contact organization information formatted as an org object.
properties:
company:
type: string
description: Name of the contact's company.
department:
type: string
description: Name of the contact's department.
title:
type: string
description: Contact's business title.
WhatsappMessageContactPhone:
type: object
properties:
phone:
type: string
description: Automatically populated with the `wa_id` value as a formatted phone number.
type:
type: string
description: Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`.
wa_id:
type: string
description: WhatsApp ID.
WhatsappMessageContactUrl:
type: object
properties:
url:
type: string
description: URL.
type:
type: string
description: Standard values are `HOME` and `WORK`.
WhatsappMessageContext:
type: object
description: |-
Used to mention a specific message you are replying to. The reply can be any message type.
properties:
message_id:
type: string
description: Specifies the `wamid` of the message your are replying to. `wamid` is the original message ID on WhatsApp's platform.
example: 'wamid.BgNODYxN...'
WhatsappMessageInteractive:
type: object
description: |-
Use for `interactive` messages.
properties:
type:
type: string
description: |-
**Required.**
The type of interactive message you want to send.
- `button`: Use for Reply Buttons.
- `list`: Use for List Messages.
- `cta_url`: Use for Call-To-Action (CTA) URL Button Messages.
- `product`: Use for Single Product Messages.
- `product_list`: Use for Multi-Product Messages.
- `catalog_message`: Use for Catalog Messages.
- `location_request_message`: Use for Location Request Messages.
- `order_details`: Use for Order Details Messages.
- `order_status`: Use for Order Status Messages.
- `voice_call`: Use for Voice Call Messages.
- `flow`: Use for Flow Messages.
- `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
- flow
- carousel
action:
$ref: '#/components/schemas/WhatsappMessageInteractiveAction'
body:
$ref: '#/components/schemas/WhatsappMessageInteractiveBody'
header:
$ref: '#/components/schemas/WhatsappMessageInteractiveHeader'
footer:
$ref: '#/components/schemas/WhatsappMessageInteractiveFooter'
WhatsappMessageInteractiveAction:
type: object
description: |-
**Required.**
Action you want the user to perform after reading the `interactive` message.
properties:
buttons:
type: array
description: Required for Reply Buttons. You can have up to 3 buttons.
maxItems: 3
items:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionButton'
button:
type: string
description: |-
Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.
maxLength: 20
catalog_id:
type: string
description: |-
Required for Single Product Messages and Multi-Product Messages.
Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via the [Meta Commerce Manager](https://business.facebook.com/commerce).
product_retailer_id:
type: string
description: |-
Required for Single Product Messages and Multi-Product Messages.
Unique identifier of the product in a catalog.
sections:
type: array
description: |-
Required for List Messages and Multi-Product Messages.
Array of section objects. Minimum of 1, maximum of 10.
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionSection'
name:
type: string
description: |-
Action name.
Required for Call-To-Action (CTA) buttons.
- `cta_url`: Use for Call-To-Action (CTA) URL buttons.
- `send_location`: Use for Location Request buttons.
- `flow`: Use for Flow buttons.
- `review_and_pay`: Use for Order Details buttons.
- `review_order`: Use for Order Status buttons.
- `voice_call`: Use for Voice Call buttons.
enum:
- cta_url
- send_location
- flow
- review_and_pay
- review_order
- voice_call
parameters:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionParameters'
cards:
type: array
description: |-
Required for Carousel Messages.
Array of card objects. Minimum of 2, maximum of 10.
maxItems: 10
items:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionCard'
WhatsappMessageInteractiveActionButton:
type: object
description: |-
A button object in `interactive` messages.
properties:
type:
type: string
description: Only supported type is `reply` (for Reply Button).
enum:
- reply
reply:
type: object
properties:
title:
type: string
description: |-
Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.
maxLength: 20
id:
type: string
description: |-
Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. You cannot have leading or trailing spaces when setting the ID.
maxLength: 256
WhatsappMessageInteractiveActionCard:
type: object
description: |-
A card object in `interactive` messages. All cards must have the same structure.
properties:
card_index:
type: number
description: |-
Card index. Unique index for each card (0-9).
type:
type: string
description: |-
Must be "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).
properties:
name:
type: string
description: |-
Required when card action is url button. Must be "cta_url".
parameters:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionCardActionParameters'
buttons:
type: array
description:
Required when card action is quick reply button.
items:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionCardActionButton'
WhatsappMessageInteractiveActionCardActionButton:
type: object
properties:
type:
type: string
description: Must be "quick_reply".
quick_reply:
type: object
properties:
title:
type: string
description: |-
Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters.
maxLength: 20
id:
type: string
description: |-
Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 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.
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.
properties:
text:
type: string
description: |-
Max 160 chars, and up to 2 line breaks.
maxLength: 160
WhatsappMessageInteractiveActionCardHeader:
type: object
properties:
type:
type: string
description: |-
**Required.**
The header type you would like to use.
- `video`: Used for Reply Buttons.
- `image`: Used for Reply Buttons.
enum:
- image
- video
image:
$ref: '#/components/schemas/WhatsappMessageMedia'
video:
$ref: '#/components/schemas/WhatsappMessageMedia'
WhatsappMessageInteractiveActionParameters:
type: object
description: |-
Action parameters.
Required for Call-To-Action (CTA) buttons.
properties:
display_text:
type: string
description: |-
Text of the CTA URL button.
Maximum length: 20 bytes.
maxLength: 20
example: 'See Docs'
url:
type: string
description: |-
URL of the CTA URL button.
example: 'https://developers.facebook.com/docs/whatsapp'
thumbnail_product_retailer_id:
type: string
description: |-
Item SKU number. Labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce).
The thumbnail of this item will be used as the message's header image.
flow_message_version:
type: string
description: |-
Use for `flow` buttons.
Value must be "3".
flow_token:
type: string
description: |-
Use for `flow` buttons.
Flow token that is generated by the business to serve as an identifier. Defaults to `unused`.
flow_id:
type: string
description:
Conditionally required for `flow` buttons.
Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter.
flow_name:
type: string
description: |-
Conditionally required for `flow` buttons.
The name of the Flow that you created. Cannot be used with the `flow_id` parameter. Changing the Flow name will require updating this parameter to match the new name.
flow_cta:
type: string
description: |-
Required for `flow` buttons.
Text on the CTA button. For example: "Open flow!". Maximum length: 20 characters.
maxLength: 20
example: 'Open flow!'
flow_action:
type: string
description: |-
Use for `flow` buttons.
Either `navigate` or `data_exchange`. Defaults to `navigate`.
example: 'navigate'
flow_action_payload:
type: object
description: |-
Required if `flow_action` is `navigate`. Should be omitted otherwise.
properties:
screen:
type: string
description: |-
The ID of the screen displayed first. It needs to be an **entry** screen.
data:
type: object
description: |-
Optional input data for the first screen of the Flow. If provided, this must be a non-empty object.
additionalProperties:
type: object
reference_id:
type: string
description: |-
Required for `review_and_pay` buttons.
Unique identifier for the order provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters.
The `reference_id` must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness.
type:
type: string
description: |-
Required for `review_and_pay` buttons.
The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`.
beneficiaries:
type: array
description: |-
Required for `review_and_pay` buttons.
An array of beneficiaries for this order.
A beneficiary is an intended recipient for shipping the physical goods in the order.
Beneficiary information isn't shown to users but is needed for legal and compliance reasons.
items:
$ref: '#/components/schemas/WhatsappMessageOrderBeneficiary'
currency:
type: string
description: |-
Required for `review_and_pay` buttons.
The currency for this order.
Currently the only supported value is `INR`.
total_amount:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: |-
Required for `review_and_pay` buttons.
The total amount for this order.
order:
$ref: '#/components/schemas/WhatsappMessageOrderInfo'
description: |-
Required for `review_and_pay` or `review_order` buttons.
For `review_and_pay` buttons, provides order `status`, `items`, `subtotal`, `tax`, etc.
For `review_order` buttons, provides only order `status` and `description`.
payment_settings:
type: array
description: |-
Required for `review_and_pay` buttons.
Payment settings for the order.
items:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting'
WhatsappMessageInteractiveActionSection:
type: object
description: |-
WhatsApp Message Interactive Section Object.
properties:
title:
type: string
description: |-
**Required if the message has more than one section.**
Title of the section. Maximum length: 24 characters.
maxLength: 24
rows:
type: array
description: |-
Contains a list of rows. You can have a total of 10 rows across your sections.
Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional.
maxItems: 10
items:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionSectionRow'
product_items:
type: array
description: |-
Required for Multi-Product Messages.
Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.
minItems: 1
maxItems: 30
items:
$ref: '#/components/schemas/WhatsappMessageInteractiveActionSectionProductItem'
WhatsappMessageInteractiveActionSectionProductItem:
type: object
properties:
product_retailer_id:
type: string
description: |-
Required for Multi-Product Messages.
Unique identifier of the product in a catalog.
WhatsappMessageInteractiveActionSectionRow:
type: object
properties:
id:
type: string
description: |-
Unique row ID. Maximum length: 200 characters.
maxLength: 200
title:
type: string
description: |-
Row title content. Maximum length: 24 characters.
maxLength: 24
description:
type: string
description: |-
Row description content. Maximum length: 72 characters.
maxLength: 72
WhatsappMessageInteractiveBody:
type: object
description: |-
Optional for type `product`. Required for other message types.
properties:
text:
type: string
description: |-
The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.
maxLength: 1024
WhatsappMessageInteractiveFooter:
type: object
description: |-
Optional. An object with the footer of the message.
properties:
text:
type: string
description: |-
The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters.
maxLength: 60
WhatsappMessageInteractiveHeader:
type: object
description: |-
Required for type `product_list`. Optional for other types.
properties:
type:
type: string
description: |-
**Required.**
The header type you would like to use.
- `text`: Used for List Messages, Reply Buttons, and Multi-Product Messages.
- `video`: Used for Reply Buttons.
- `image`: Used for Reply Buttons.
- `document`: Used for Reply Buttons.
enum:
- text
- image
- video
- document
text:
type: string
description: Text for the header. Formatting allows emojis, but not markdown.
maxLength: 60
image:
$ref: '#/components/schemas/WhatsappMessageMedia'
video:
$ref: '#/components/schemas/WhatsappMessageMedia'
document:
$ref: '#/components/schemas/WhatsappMessageMedia'
WhatsappMessageLocation:
type: object
description: |-
Use for `location` messages.
required:
- latitude
- longitude
properties:
latitude:
type: number
format: double
description: Latitude of the location.
longitude:
type: number
format: double
description: Longitude of the location.
name:
type: string
description: Name of the location.
address:
type: string
description: Address of the location. Only displayed if `name` is present.
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.
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. If both are provided, `id` takes precedence.
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. If both are provided, `id` takes precedence and `link` will be ignored.
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.
WhatsappMessageOrderAmount:
type: object
description: |-
Represents the amount of an order.
required:
- offset
- value
properties:
offset:
type: integer
format: int32
description: Must be `100` for `INR`.
example: 100
value:
type: integer
format: int32
description: |-
Positive integer representing the amount value multiplied by offset.
For example, ₹12.34 has value 1234.
example: 1234
description:
type: string
description: |-
Use only for `tax`, `shipping`, or `discount`.
Description of the amount. Max character limit is 60 characters.
maxLength: 60
discount_program_name:
type: string
description: |-
Use only for `discount`.
Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters.
maxLength: 60
WhatsappMessageOrderBeneficiary:
type: object
description: |-
A beneficiary is an intended recipient for shipping the physical goods in the order.
Beneficiary information isn't shown to users but is needed for legal and compliance reasons.
required:
- name
- address_line1
- city
- state
- country
- postal_code
properties:
name:
type: string
description: |-
Name of the individual or business receiving the physical goods. Cannot exceed 200 characters.
maxLength: 200
address_line1:
type: string
description: Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters.
maxLength: 100
address_line2:
type: string
description: Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters.
maxLength: 100
city:
type: string
description: Name of the city.
state:
type: string
description: Name of the state.
country:
type: string
description: |-
Name of the country.
Currently the only supported value is `India`.
postal_code:
type: string
description: 6-digit zipcode of shipping address.
minLength: 6
maxLength: 6
WhatsappMessageOrderDetails:
type: object
description: |-
Contains the order details when sending a template message with a `order_details` button.
required:
- currency
- order
- reference_id
- total_amount
- type
- payment_settings
properties:
currency:
type: string
description: |-
The currency for this order.
Currently the only supported value is `INR`.
order:
$ref: '#/components/schemas/WhatsappMessageOrderInfo'
description: |-
Provides order `status`, `items`, `subtotal`, `tax`, etc.
reference_id:
type: string
description: |-
Unique identifier for the order provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters.
The `reference_id` must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness.
total_amount:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: |-
The total amount of the order.
type:
type: string
description: |-
The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`.
payment_settings:
type: array
description: |-
Payment settings for the order.
items:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting'
WhatsappMessageOrderExpiration:
type: object
description: |-
Expiration for this order.
required:
- timestamp
properties:
timestamp:
type: string
description: |-
A string of UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds.
example: '1727438564'
description:
type: string
description: Text explanation for expiration.
maxLength: 120
WhatsappMessageOrderInfo:
type: object
description: |-
Order info.
properties:
status:
$ref: '#/components/schemas/WhatsappMessageOrderStatusEnum'
type:
type: string
description: |-
Only supported value is `quick_pay`.
When this field is passed in we hide the "Review and Pay" button and only show the "Pay Now" button in the order details bubble.
catalog_id:
type: string
description: |-
Unique identifier of the Facebook catalog being used by the business.
If you do not provide this field, you must provide the following fields inside the items object: `country_of_origin`, `importer_name`, and `importer_address`.
items:
type: array
description: |-
Array of items in the order.
items:
$ref: '#/components/schemas/WhatsappMessageOrderItem'
subtotal:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: |-
The value **must be equal** to sum of `order.amount.value` * `order.amount.quantity`.
tax:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: The tax information for this order.
shipping:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: The shipping cost of the order.
discount:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: The discount amount for this order.
expiration:
$ref: '#/components/schemas/WhatsappMessageOrderExpiration'
description:
type: string
description: |-
**Optional.**
Text for sharing status related information. Could be useful while sending cancellation. Max character limit is 120 characters.
maxLength: 120
WhatsappMessageOrderItem:
type: object
required:
- name
- amount
- quantity
properties:
retailer_id:
type: string
description: Content ID for an item in the order from your catalog.
name:
type: string
description: The item's name to be displayed to the user. Cannot exceed 60 characters.
maxLength: 60
image:
$ref: '#/components/schemas/WhatsappMessageMedia'
description: Custom image for the item to be displayed to the user.
amount:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: The price per item.
sale_amount:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: |-
The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount.
quantity:
type: integer
format: int32
description: The number of items in the order.
country_of_origin:
type: string
description: |-
Required if `catalog_id` is not present.
The country of origin of the product.
importer_name:
type: string
description: |-
Required if `catalog_id` is not present.
Name of the importer company.
importer_address:
type: string
description: |-
Required if `catalog_id` is not present.
Address of importer company.
WhatsappMessageOrderPaymentGateway:
type: object
description: An object that describes payment account information.
required:
- type
- configuration_name
properties:
type:
type: string
description: |-
Payment type.
Must set this to `billdesk`, `razorpay`, `payu`, or `zaakpay`, if you have linked your BillDesk, Razorpay, PayU, or Zaakpay payment gateway to accept payments.
enum:
- billdesk
- razorpay
- payu
- zaakpay
configuration_name:
type: string
description: |-
The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters.
This value must match with a payment configuration set up on the WhatsApp Business Manager.
maxLength: 60
billdesk:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk'
payu:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayPayu'
razorpay:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay'
zaakpay:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay'
WhatsappMessageOrderPaymentSetting:
type: object
description: Payment settings for the order.
required:
- type
- payment_gateway
properties:
type:
type: string
description: Must be set to `payment_gateway`.
example: payment_gateway
payment_gateway:
$ref: '#/components/schemas/WhatsappMessageOrderPaymentGateway'
WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk:
type: object
description: |-
Additional info for BillDesk.
User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 120.
properties:
additional_info1:
type: string
additional_info2:
type: string
additional_info3:
type: string
additional_info4:
type: string
additional_info5:
type: string
additional_info6:
type: string
additional_info7:
type: string
WhatsappMessageOrderPaymentSettingPaymentGatewayPayu:
type: object
description: |-
Additional info for PayU.
User-defined fields (udf) are used to store any information corresponding to a particular order. Each UDF field has a maximum character limit of 255.
properties:
udf1:
type: string
udf2:
type: string
udf3:
type: string
udf4:
type: string
WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay:
type: object
description: Additional info for Razorpay.
properties:
receipt:
type: string
description: |-
Receipt number that corresponds to this order, set for your internal reference.
Maximum length of 40 characters supported with minimum length greater than 0 characters.
notes:
type: object
additionalProperties:
type: string
description: |-
The object can be key value pairs with maximum 15 keys and each value limits to 256 characters.
WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay:
type: object
description: |-
Additional info for Zaakpay.
User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 180.
properties:
extra1:
type: string
extra2:
type: string
WhatsappMessageOrderStatus:
type: object
properties:
reference_id:
type: string
description: |-
Unique identifier for the order provided by the business.
order:
$ref: '#/components/schemas/WhatsappMessageOrderInfo'
description: |-
Provides only `status` and `description` of this order for `order_status` messages.
WhatsappMessageOrderStatusEnum:
type: string
description: |-
Only supported value in the `order_details` message is `pending`.
In an `order_status` message, `status` can be: `pending`, `processing`, `partially_shipped`, `shipped`, `completed`, or `canceled`.
enum:
- pending
- processing
- partially_shipped
- shipped
- completed
- canceled
WhatsappMessageSendRequest:
type: object
description: Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.
required:
- from
- type
properties:
from:
type: string
description: The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
example: '+16315551111'
to:
type: string
description: The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. 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
customerProfile:
$ref: '#/components/schemas/WhatsappProfile'
description: The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios.
type:
$ref: '#/components/schemas/WhatsappMessageType'
template:
$ref: '#/components/schemas/WhatsappMessageTemplate'
description: Required when `type` is `template`.
text:
$ref: '#/components/schemas/WhatsappMessageText'
description: Required when `type` is `text`.
image:
$ref: '#/components/schemas/WhatsappMessageMedia'
description: Required when `type` is `image`.
video:
$ref: '#/components/schemas/WhatsappMessageMedia'
description: Required when `type` is `video`.
audio:
$ref: '#/components/schemas/WhatsappMessageMedia'
description: Required when `type` is `audio`.
document:
$ref: '#/components/schemas/WhatsappMessageMedia'
description: Required when `type` is `document`.
sticker:
$ref: '#/components/schemas/WhatsappMessageMedia'
description: Required when `type` is sticker.
location:
$ref: '#/components/schemas/WhatsappMessageLocation'
description: Required when `type` is `location`.
interactive:
$ref: '#/components/schemas/WhatsappMessageInteractive'
description: Required when `type` is `interactive`.
contacts:
type: array
description: Required when `type` is `contacts`.
items:
$ref: '#/components/schemas/WhatsappMessageContact'
reaction:
$ref: '#/components/schemas/WhatsappMessageReaction'
description: Required when `type` is `reaction`.
context:
$ref: '#/components/schemas/WhatsappMessageContext'
externalId:
type: string
description: |-
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
category:
type: string
description: |-
**Optional.**
Indicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`.
Use `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates.
Use `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages.
enum:
- utility
- authentication
example: utility
ttlSeconds:
type: integer
description: |-
**Optional.**
Message time-to-live in seconds for Direct Send `utility` or `authentication` messages.
The supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used.
minimum: 30
maximum: 43200
example: 600
useDirectSend:
type: boolean
description: |-
**Optional.**
Whether to send the message through Direct Send. Defaults to `false`.
Set this to `true` to send the message through Direct Send when the sender WABA is enabled for Direct Send.
For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are:
- Text messages
- Interactive Call-to-Action URL button messages
- Interactive reply button messages
default: false
filterUnsubscribed:
type: boolean
description: |-
**Optional.**
If set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`.
Only use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`.
Not applicable to `POST /v2/whatsapp/messages/sendDirectly`.
filterBlocked:
type: boolean
description: |-
**Optional.**
If set to `true`, the message will not be sent to users in your block list. Defaults to `false`.
Only use for `POST /v2/whatsapp/messages`. If the user is in your block list, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_IN_BLOCK_LIST`.
Not applicable to `POST /v2/whatsapp/messages/sendDirectly`.
WhatsappCallingConnectRequest:
type: object
description: Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.
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\no=- 4054442297240208280 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\na=msid-semantic: WMS 6c364341-f90d-48e6-b497-76e047e3c31a\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 63 9 0 8 13 110 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:Dpsa\r\na=ice-pwd:oVuOd7HKhA8aWTvspLYACWJe\r\na=ice-options:trickle\r\na=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:8F:F1:20:71:38:16:37:18:3F:FA\r\na=setup:actpass\r\na=mid:0\r\na=extmap:1 urn:ietf:params:rtp-hdrext:ssrc-audio-level\r\na=extmap:2 http://www.webrtc.org/experiments/rtp-hdrext/abs-send-time\r\na=extmap:3 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=extmap:4 urn:ietf:params:rtp-hdrext:sdes:mid\r\na=sendrecv\r\na=msid:6c364341-f90d-48e6-b497-76e047e3c31a fa42cdbe-8696-4ee8-bce0-0919d86a223f\r\na=rtcp-mux\r\na=rtcp-rsize\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 minptime=10;useinbandfec=1\r\na=rtpmap:63 red/48000/2\r\na=fmtp:63 111/111\r\na=rtpmap:9 G722/8000\r\na=rtpmap:0 PCMU/8000\r\na=rtpmap:8 PCMA/8000\r\na=rtpmap:13 CN/8000\r\na=rtpmap:110 telephone-event/48000\r\na=rtpmap:126 telephone-event/8000\r\na=ssrc:3208712354 cname:bg/Ix8uTnsTsiMoe\r\na=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\no=- 123456789 987654321 IN IP4 192.168.1.1\r\ns=-\r\nt=0 0\r\n..."
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.HBgNNjI4MTM2MTkwNTEzMxUCABIYIDhEMjc4NEY2QUU4NTA2MTgxNTBGNzQ3N0M4QTBDMTU5HBgNNjI4MzEzODIwNTE1MBUCABUeAA=="
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\no=- 2239925877841361960 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS 0ed5100f-da68-4193-8865-146c1ac7a087\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 0.0.0.0\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=ice-ufrag:NCH6\r\na=ice-pwd:ogUYxqJDPNn0C5RFif6UlLz6\r\na=ice-options:trickle\r\na=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:84:AC:B2:93:32:B8:20:5C:3C:85\r\na=setup:active\r\na=mid:audio\r\na=sendrecv\r\na=msid:0ed5100f-da68-4193-8865-146c1ac7a087 bc955459-4bae-4504-99c8-348944c12b6f\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 minptime=10;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=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.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA=="
WhatsappCallingResponse:
type: object
required:
- success
properties:
wacid:
type: string
description: The WhatsApp call ID associated with this calling operation.
example: "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA=="
success:
type: boolean
description: Indicates whether the calling operation was successful.
example: true
WhatsappMessageStatus:
type: string
description: |-
WhatsApp message status. One of `accepted`, `failed`, `sent`, `delivered`, `read`.
- `accepted`: The messaging request is accepted by our system.
- `failed`: A message sent by your business failed to send.
- `sent`: A message sent by your business is in transit within WhatsApp's systems.
- `delivered`: A message sent by your business was delivered to the user's device.
- `read`: A message sent by your business was read by the user.
enum:
- accepted
- failed
- sent
- delivered
- read
WhatsappMessageTemplate:
type: object
description: |-
Use for sending a WhatsApp `template` message.
required:
- name
- language
properties:
name:
type: string
description: Name of the template.
example: sample_whatsapp_template
language:
type: object
description: Contains a language object. Specifies the language the template may be rendered in.
properties:
code:
type: string
description: The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). See [Supported Languages](https://developers.facebook.com/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.
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'
WhatsappMessageTemplateComponentParameterAction:
type: object
description: |-
Required if template uses catalog or MPM (multi-product message) buttons.
properties:
thumbnail_product_retailer_id:
type: string
description: |-
**Optional.**
Use for catalog and MPM template messages.
Item SKU number. Labeled as Content ID in the Commerce Manager.
The thumbnail of this item will be used as the message's header image.
If the `parameters` object is omitted, the product image of the first item in your catalog will be used.
example: '2lc20305pt'
sections:
type: array
description: |-
Use for MPM templates.
Product sections. You can define up to 10 sections.
maxItems: 10
items:
$ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterActionSection'
flow_token:
type: string
description: |-
Use for `FLOW` buttons.
Flow token that is generated by the business to serve as an identifier. Defaults to `unused`.
flow_action_data:
type: object
additionalProperties:
type: object
description: |-
Use for `FLOW` buttons.
JSON object with the data payload for the first screen.
order_details:
$ref: '#/components/schemas/WhatsappMessageOrderDetails'
description: |-
Required for `order_details` buttons.
WhatsappMessageTemplateComponentParameterActionSection:
type: object
properties:
title:
type: string
description: |-
Section title text.
Maximum 24 characters. Markdown is not supported.
maxLength: 24
product_items:
type: array
description: |-
Array of product SKU numbers. There is a minimum of 1 product per section and a maximum of 30 products across all sections.
minItems: 1
maxItems: 30
items:
$ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterActionSectionProductItem'
WhatsappMessageTemplateComponentParameterActionSectionProductItem:
type: object
properties:
product_retailer_id:
type: string
description: |-
SKU number of the item you want to appear in the section.
SKU numbers are labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce).
WhatsappMessageTemplateComponentParameterLimitedTimeOffer:
type: object
description: |-
Required if template uses offer expiration details.
properties:
expiration_time_ms:
type: integer
format: int64
description: |-
**Required.**
Offer code expiration time as a UNIX timestamp in milliseconds.
example: '1698562800000'
WhatsappMessageText:
type: object
description: |-
WhatsApp Message Text Object.
required:
- body
properties:
body:
type: string
description: |-
Required for text messages.
The text of the text message which can contain URLs which begin with http:// or https:// and formatting. See available formatting options here.
If you include URLs in your text and want to include a preview box in text messages (preview_url: true), make sure the URL starts with http:// or https:// — https:// URLs are preferred. You must include a hostname, since IP addresses will not be matched.
Maximum length: 4096 characters.
maxLength: 4096
preview_url:
type: boolean
description: |-
By default, WhatsApp recognizes URLs and makes them clickable, but you can also include a preview box with more information about the link. Set this field to true if you want to include a URL preview box.
The majority of the time, the receiver will see a URL they can click on when you send an URL, set preview_url to true, and provide a body object with a http or https link.
URL previews are only rendered after one of the following has happened:
- The business has sent a message template to the user.
- The user initiates a conversation with a "click to chat" link.
- The user adds the business phone number to their address book and initiates a conversation.
Default: `false`.
WhatsappMessageType:
type: string
description: |-
WhatsApp outbound message type.
See also [WhatsApp messages](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages).
enum:
- template
- text
- image
- audio
- video
- document
- sticker
- location
- interactive
- contacts
- reaction
WhatsappPayment:
type: object
description: |-
Represents a payment object.
Businesses receive updates via webhooks when the status of the user-initiated transaction changes.
required:
- wabaId
- referenceId
- status
properties:
wabaId:
type: string
description: WhatsApp Business Account ID.
referenceId:
type: string
description: |-
Unique identifier for the payment provided by the business.
It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters.
status:
$ref: '#/components/schemas/WhatsappPaymentStatus'
transactions:
type: array
description: |-
Contains the latest transaction attempt for this payment.
items:
$ref: '#/components/schemas/WhatsappPaymentTransaction'
WhatsappPaymentStatus:
type: string
description: |-
Status of this payment.
- `captured`: Indicates the payment is successfully completed.
- `pending`: Indicates the user attempted but yet to receive success transactions signal.
enum:
- captured
- pending
WhatsappPaymentTransaction:
type: object
description: |-
Represents a transaction attempt for a payment.
required:
- id
- type
- status
- createdTimestamp
- updatedTimestamp
- amount
- currency
properties:
id:
type: string
description: Transaction ID.
type:
type: string
description: |-
The payment type for this transactions. One of `billdesk`, `razorpay`, `payu`, or `zaakpay`.
enum:
- billdesk
- razorpay
- payu
- zaakpay
status:
type: string
description: |-
The status of the transaction. One of `pending`, `success` or `failed`.
enum:
- pending
- success
- failed
createdTimestamp:
type: integer
format: int64
description: |-
Time when transaction was created in epoch milliseconds.
updatedTimestamp:
type: integer
format: int64
description: |-
Time when transaction was last updated in epoch milliseconds.
amount:
$ref: '#/components/schemas/WhatsappMessageOrderAmount'
description: Total amount that user has paid.
currency:
type: string
description: |-
The currency for this payment.
Currently the only supported value is `INR`.
methodType:
type: string
description: |-
Describes the type of payment method used by consumer to pay for the order. Can be one of `upi`, `card`, `wallet`, or `netbanking`.
The payment method information might not be available for failed payments.
example: 'upi'
error:
type: object
description: |-
The payment error details might not be available for all payments attempts.
required:
- code
- reason
properties:
code:
type: string
description: |-
Describes the payment failure reason that generated by payment gateway and Meta transmits this to partners.
reason:
type: string
description: |-
Describes the payment failure reason in plain text that is generated by payment gateway and Meta transmits this to partners.
WhatsappPhoneNumber:
type: object
description: |-
See [WhatsApp Business Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers)
properties:
id:
type: string
description: Phone number ID.
example: '1234567890123456'
phoneNumber:
type: string
description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
example: '+16315551111'
displayPhoneNumber:
type: string
description: Display phone number.
example: '+1 631-555-1111'
wabaId:
type: string
description: WhatsApp Business Account ID.
example: 'whatsapp-business-account-id'
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.
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
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:
type: string
description: |-
**Required for type `HEADER`.**
enum:
- TEXT
- IMAGE
- GIF
- VIDEO
- DOCUMENT
- LOCATION
text:
type: string
description: |-
For body text (type = `BODY`), maximum 1024 characters.
For header text (type = `HEADER`, format = `TEXT`), maximum 60 characters.
For footer text (type = `FOOTER`), maximum 60 characters.
For card body text (`CAROUSEL` card component type = `BODY`), maximum 160 characters.
maxLength: 1024
buttons:
type: array
description: |-
**Required for type `BUTTONS`.**
Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits.
If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a **See all options** button. Tapping the **See all options** button reveals the remaining buttons.
maxItems: 10
items:
$ref: '#/components/schemas/WhatsappTemplateComponentButton'
add_security_recommendation:
type: boolean
description: |-
**Optional. Only applicable in the `BODY` component of an AUTHENTICATION template.**
Set to `true` if you want the template to include the string, *For your security, do not share this code.* Set to `false` to exclude the string.
code_expiration_minutes:
type: integer
format: int32
description: |-
**Optional. Only applicable in the `FOOTER` component of an AUTHENTICATION template.**
Indicates number of minutes the password or code is valid.
If omitted, the code expiration warning will not be displayed in the delivered message.
Minimum 1, maximum 90.
maximum: 90
minimum: 1
example: 5
limited_time_offer:
$ref: '#/components/schemas/WhatsappTemplateComponentLimitedTimeOffer'
example:
$ref: '#/components/schemas/WhatsappTemplateComponentExample'
cards:
type: array
description: |-
**Required for type `CAROUSEL`.**
Carousel templates support up to 10 carousel cards.
maxItems: 10
items:
$ref: '#/components/schemas/WhatsappTemplateComponentCard'
WhatsappTemplateComponentButton:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/WhatsappTemplateComponentButtonType'
text:
type: string
description: |-
**Required for button type `PHONE_NUMBER` or `URL`.** Button text.
For `CODE_CODE` buttons, the text is a pre-set value and cannot be customized.
For `OTP` buttons, if omitted, the text will default to a pre-set value localized to the template's language. For example, `Copy Code` for English (US). If your template is using a one-tap autofill button and you supply this value, the authentication template message will display a copy code button with this text if we are unable to validate your [handshake](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/autofill-button-authentication-templates#handshake). Maximum 25 characters.
maxLength: 25
url:
type: string
description: |-
**Required for button type `URL`.** URL of website.
There can be at most 1 variable at the end of the URL. Example: `https://www.luckyshrub.com/shop?promo={{1}}`.
2000 characters maximum.
maxLength: 2000
phone_number:
type: string
description: |-
**Required for button type `PHONE_NUMBER`.**
Alphanumeric string. Business phone number to be (display phone number) called when the user taps the button.
20 characters maximum.
maxLength: 20
example: 15550051310
otp_type:
$ref: '#/components/schemas/WhatsappTemplateComponentButtonOtpType'
description: |-
**Required for button type `OTP`.**
Indicates button OTP type.
Set to `COPY_CODE` if you want the template to use a copy code button, `ONE_TAP` to have it use a one-tap autofill button, or `ZERO_TAP` to have no button at all.
autofill_text:
type: string
description: |-
**One-tap and zero-tap buttons only.**
One-tap button text.
Maximum 25 characters.
maxLength: 25
example: 'Autofill'
package_name:
type: string
description: |-
**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` or `flow_json` parameters are provided. Only one of these parameters is allowed.
example: '1'
flow_name:
type: string
description: |-
**Conditionally required for button type `FLOW`.**
The name of the Flow. Cannot be used if `flow_id` or `flow_json` parameters are provided. Only one of these parameters is allowed. The Flow ID is stored in the message template, not the name, so changing the Flow name will not affect existing message templates.
flow_json:
type: string
description: |-
**Conditionally required for button type `FLOW`.**
The Flow JSON encoded as string with escaping. The Flow JSON specifies the content of the Flow. Cannot be used if `flow_id` or `flow_name` parameters are provided. Only one of these parameters is allowed.
flow_action:
type: string
description: |-
**Use for button type `FLOW`.**
Either `navigate` or `data_exchange`. Defaults to `navigate`.
example: 'navigate'
navigate_screen:
type: string
description: |-
**Required if `flow_action` is `navigate`.**
The unique ID of the Screen in the Flow.
example: 'WELCOME_SCREEN'
app_deep_link:
$ref: '#/components/schemas/WhatsappTemplateComponentButtonAppDeepLink'
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.
enum:
- PHONE_NUMBER
- URL
- QUICK_REPLY
- COPY_CODE
- OTP
- CATALOG
- MPM
- FLOW
- ORDER_DETAILS
- VOICE_CALL
WhatsappTemplateComponentCard:
type: object
description: |-
Carousel templates support up to 10 carousel cards. Cards must have a media header (image or video) and can optionally include body text and up to 2 quick reply buttons, phone number buttons, or URL buttons (button types can be mixed).
properties:
components:
type: array
description: |-
**Required.**
Card components.
items:
$ref: '#/components/schemas/WhatsappTemplateComponentCardComponent'
description: |-
Cards must have a media header (image or video) and can optionally include body text and up to 2 quick reply buttons, phone number buttons, or URL buttons (button types can be mixed).
WhatsappTemplateComponentCardComponent:
type: object
properties:
type:
type: string
description: |-
**Required.**
Card component type.
- `BODY`: Body components are text-only components. Cards must have body text.
- `HEADER`: Cards must have a media header (image or video).
- `BUTTONS`: Buttons are interactive components that perform specific actions when tapped. Cards must have at least one button, up to 2 buttons.
enum:
- BODY
- HEADER
- BUTTONS
format:
type: string
description: |-
**Required for type `HEADER`.**
Cards must have a media header (image or video).
enum:
- IMAGE
- VIDEO
text:
type: string
description: |-
**Required for type `BODY`.**
Card body text supports variables. Maximum 160 characters.
maxLength: 160
buttons:
type: array
description: |-
**Required for type `BUTTONS`.**
Cards must have at least one button. Supports 2 buttons. Buttons can be the same or a mix of quick reply buttons, phone number buttons, or URL buttons.
minItems: 1
maxItems: 2
items:
$ref: '#/components/schemas/WhatsappTemplateComponentButton'
example:
$ref: '#/components/schemas/WhatsappTemplateComponentExample'
WhatsappTemplateComponentExample:
type: object
description: |-
**Required** when:
- `type` is `HEADER`, and `format` is one of `IMAGE`, `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: |-
Use for `LIMITED_TIME_OFFER` components.
properties:
text:
type: string
description: |-
**Required.**
Offer details text.
Maximum 16 characters.
maxLength: 16
example: 'Expiring offer!'
has_expiration:
type: boolean
description: |-
**Optional.**
Set to `true` to have the [offer expiration details](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/limited-time-offer-templates#offer-expiration-details) appear in the delivered message.
If set to `true`, the copy code button component must be included in the `buttons` array, and must appear first in the array.
If set to `false`, offer expiration details will not appear in the delivered message and the copy code button component is optional. If including the copy code button, it must appear first in the `buttons` array.
WhatsappTemplateCreateRequest:
type: object
description: See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates).
required:
- wabaId
- name
- language
- category
- components
properties:
wabaId:
type: string
description: WhatsApp Business Account ID.
example: 'whatsapp-business-account-id'
name:
type: string
description: Name of the template.
maxLength: 512
pattern: '[a-z0-9_]{1,512}'
example: sample_whatsapp_template
language:
type: string
description: Language code of the template. See [Supported Languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes.
example: en
category:
$ref: '#/components/schemas/WhatsappTemplateCategory'
subCategory:
$ref: '#/components/schemas/WhatsappTemplateSubCategory'
messageSendTtlSeconds:
type: integer
format: int32
description: |-
If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message.
By default, messages that use an authentication template have a default TTL of **10 minutes**, and messages that use a utility or marketing template have a default TTL of **30 days**.
Set its value between `30` and `900` seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or `30` and `43200` seconds (i.e., 30 seconds to 12 hours) for utility templates, or `43200` and `2592000` seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to `-1`, which will set a custom TTL of 30 days for either type of template.
We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable.
Authentication templates created before October 23, 2024, have a default TTL of 30 days.
example: 600
components:
type: array
items:
$ref: '#/components/schemas/WhatsappTemplateComponent'
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/WhatsappTemplateComponent'
messageSendTtlSeconds:
type: integer
format: int32
description: |-
If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message.
By default, messages that use an authentication template have a default TTL of **10 minutes**, and messages that use a utility or marketing template have a default TTL of **30 days**.
Set its value between `30` and `900` seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or `30` and `43200` seconds (i.e., 30 seconds to 12 hours) for utility templates, or `43200` and `2592000` seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to `-1`, which will set a custom TTL of 30 days for either type of template.
We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable.
Authentication templates created before October 23, 2024, have a default TTL of 30 days.
example: 600
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'
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'
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'
SHA-256: 8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81