{ "components": { "parameters": { "businessPhoneNumber-in_path": { "description": "The WhatsApp business phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "businessPhoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } }, "channel-in_path_for_unsubscriber": { "in": "path", "name": "channel", "required": true, "schema": { "$ref": "#/components/schemas/UnsubscriberChannel" } }, "contactIdentifier-in_path_for_contact_note": { "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 `+`.\nUsernames 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.", "in": "path", "name": "contactIdentifier", "required": true, "schema": { "example": "alice_01", "maxLength": 255, "type": "string" } }, "contactPageAfter": { "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.\nThe 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`.", "in": "query", "name": "pageAfter", "required": false, "schema": { "example": "0", "pattern": "^[0-9]+$", "type": "string" } }, "customer-in_path_for_unsubscriber": { "description": "The customer who has opted out.", "in": "path", "name": "customer", "required": true, "schema": { "example": "+16315551111", "type": "string" } }, "filter_accountReviewStatus-WABA": { "description": "WhatsApp Business Account review status.", "in": "query", "name": "filter.accountReviewStatus", "required": false, "schema": { "example": "APPROVED", "type": "string" } }, "filter_createTime_gte-default_1d": { "description": "Return results where the `createTime` field is greater than or equal to this value. Default: One day ago from now.", "in": "query", "name": "filter.createTime.gte", "required": false, "schema": { "example": "2022-03-01T12:00:00.000Z", "format": "date-time", "type": "string" } }, "filter_createTime_lte": { "description": "Return results where the `createTime` field is less than or equal to this value.", "in": "query", "name": "filter.createTime.lte", "required": false, "schema": { "example": "2022-03-31T12:00:00.000Z", "format": "date-time", "type": "string" } }, "filter_id": { "description": "Unique object ID on our side. Other filter parameters will be ignored if this parameter is present.", "in": "query", "name": "filter.id", "required": false, "schema": { "type": "string" } }, "filter_wabaId": { "description": "**Required if you have more than 100 WABAs.**\nWhatsApp Business Account ID.", "in": "query", "name": "filter.wabaId", "required": false, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, "groupAfter": { "description": "A cursor to fetch the next page.", "in": "query", "name": "after", "required": false, "schema": { "example": "eyJvIjoiYWZ0ZXIifQ", "type": "string" } }, "groupBefore": { "description": "A cursor to fetch the previous page.", "in": "query", "name": "before", "required": false, "schema": { "example": "eyJvIjoiYmVmb3JlIn0", "type": "string" } }, "groupId-in_path": { "description": "WhatsApp group ID.", "in": "path", "name": "groupId", "required": true, "schema": { "example": "120363345678901234@g.us", "type": "string" } }, "groupLimit": { "description": "A limit on the number of results to be returned, between 1 and 1024. Defaults to 25.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "format": "int32", "maximum": 1024, "minimum": 1, "type": "integer" } }, "id-in_path": { "description": "ID of the object.", "in": "path", "name": "id", "required": true, "schema": { "example": "627c8640675de8fc689ab9d9", "type": "string" } }, "id-in_path_for_contact": { "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 `@`.\nA 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.", "in": "path", "name": "id", "required": true, "schema": { "example": "alice_01", "maxLength": 255, "type": "string" } }, "id-in_path_for_webhook_endpoint": { "description": "ID of the webhook endpoint.", "in": "path", "name": "id", "required": true, "schema": { "example": "wh627c8640675de8fc689ab9d9", "type": "string" } }, "includeTotal": { "description": "Return results inside an object that contains the total result count or not.", "in": "query", "name": "includeTotal", "required": false, "schema": { "default": false, "type": "boolean" } }, "limit": { "description": "A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, "name-in_path_for_custom_event": { "description": "Name of the custom event.", "in": "path", "name": "name", "required": true, "schema": { "example": "unique_event_name", "pattern": "[a-z0-9_]{1,50}", "type": "string" } }, "name-in_path_for_custom_event_property": { "description": "Name of the custom event property.", "in": "path", "name": "propertyName", "required": true, "schema": { "example": "unique_property_name", "pattern": "[a-z0-9_]{1,50}", "type": "string" } }, "noteId-in_path_for_contact_note": { "description": "The 24-character ObjectId of the contact note.", "in": "path", "name": "noteId", "required": true, "schema": { "example": "6a3de646e18f344f743aaa4d", "maxLength": 24, "minLength": 24, "pattern": "^[0-9a-fA-F]{24}$", "type": "string" } }, "page": { "description": "Page number of the results to be returned, 1-based.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, "pageAfter": { "description": "A cursor to fetch the next page in cursor pagination.\nFor 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.", "in": "query", "name": "pageAfter", "required": false, "schema": { "example": "id:foo", "type": "string" } }, "wabaId-in_path": { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } } }, "schemas": { "AttributeChangeAction": { "description": "Represents a single change action performed on an attribute.\nFor tag attributes, includes additional id and value fields.", "properties": { "action": { "description": "The type of change action performed.", "enum": [ "ADDED", "REMOVED", "CHANGED" ], "example": "ADDED", "type": "string" }, "id": { "description": "The ID of the item when the attribute is 'tags'.\nThis field is only present for tag-related changes.", "example": "686dd294334be8606a5bfxxx", "type": "string" }, "value": { "description": "The value of the item when the attribute is 'tags'.\nThis field is only present for tag-related changes.", "example": "tag1", "type": "string" } }, "required": [ "action" ], "type": "object" }, "Balance": { "properties": { "amount": { "description": "Balance of current account.", "example": 190.0765, "format": "double", "type": "number" }, "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "CallingCaptureSettings": { "description": "Phone-number-level recording and transcription capture settings used for new WhatsApp calls.", "properties": { "announcementLanguage": { "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", "type": "string" }, "purpose": { "description": "Customer-defined capture purpose passed to the Calling provider configuration. Required when either capture switch is enabled.", "example": "quality_assurance", "maxLength": 250, "type": "string" }, "recordingEnabled": { "description": "Whether recording capture is enabled.", "type": "boolean" }, "transcriptionEnabled": { "description": "Whether transcription capture is enabled.", "type": "boolean" } }, "type": "object" }, "CallingMediaUpdated": { "additionalProperties": false, "description": "Terminal recording or transcription state for an API-sourced WhatsApp call.", "properties": { "error": { "additionalProperties": false, "description": "Present only when `status` is `FAILED`.", "properties": { "code": { "description": "Stable failure code.", "example": "CALLING_RECORDING_PROCESSING_FAILED", "type": "string" }, "retryable": { "description": "Whether retrying the upstream media operation may succeed.", "example": false, "type": "boolean" } }, "required": [ "code", "retryable" ], "type": "object" }, "mediaAssetId": { "description": "YCloud media asset ID used with the call media download API.", "example": "66b1f0c2e4b05c2d8f1a3b47", "type": "string" }, "phoneId": { "description": "WhatsApp business phone number ID used for authorized-asset delivery.", "example": "461269257068832", "type": "string" }, "status": { "enum": [ "AVAILABLE", "FAILED" ], "example": "AVAILABLE", "type": "string" }, "wacid": { "description": "WhatsApp call ID.", "example": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE", "type": "string" } }, "required": [ "wacid", "phoneId", "mediaAssetId", "status" ], "type": "object" }, "Contact": { "description": "Represents a contact.", "properties": { "countryCode": { "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", "type": "string" }, "countryName": { "description": "Full country name.", "type": "string" }, "createTime": { "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", "format": "date-time", "type": "string" }, "customAttributes": { "description": "Contact's custom attributes.", "items": { "$ref": "#/components/schemas/ContactCustomAttribute" }, "type": "array" }, "email": { "description": "The contact's email address.\nIf present, the email address must be unique.", "example": "support@example.com", "type": "string" }, "id": { "description": "Unique ID for the object.", "example": 1693364594105000026, "maxLength": 255, "type": "string" }, "lastMessageToPhoneNumber": { "description": "The business phone number that the contact last sent a message to.", "example": "+16315551111", "type": "string" }, "lastSeen": { "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", "format": "date-time", "type": "string" }, "metaUsername": { "description": "The read-only Meta username associated with the contact, without the leading `@`.", "example": "alice_01", "type": "string" }, "nickname": { "description": "The read-only nickname obtained from WhatsApp.", "example": "nickname", "type": "string" }, "ownerEmail": { "description": "The email address of the contact's owner.", "example": "support@example.com", "maxLength": 250, "type": "string" }, "phoneNumber": { "description": "Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "remarkName": { "description": "The business-managed remark name for the contact.", "example": "Priority customer", "maxLength": 250, "type": "string" }, "sourceId": { "description": "Source identifier. A unique identifier related to the contact creation source.", "example": "batch_import_123", "maxLength": 255, "type": "string" }, "sourceType": { "$ref": "#/components/schemas/ContactSourceType", "description": "The source type of the contact. Indicates how the contact was created." }, "sourceUrl": { "description": "Source URL. The source link address where the contact was created.", "example": "https://example.com/signup", "maxLength": 500, "type": "string" }, "tags": { "description": "Contact's tags.", "items": { "maxLength": 50, "type": "string" }, "maxItems": 50, "type": "array" } }, "required": [ "id" ], "type": "object" }, "ContactAttribute": { "description": "Represents a contact attribute configuration.\nContains information about the attribute's metadata and available values.", "example": { "desc": "", "id": "6865e6c17c3854485be550b0", "key": "blocked", "name": "Blocked", "type": "BOOLEAN", "values": [] }, "properties": { "desc": { "description": "Description of the contact attribute.", "example": "", "type": "string" }, "id": { "description": "Unique identifier for the contact attribute.", "example": "6865e6c17c3854485be550b0", "type": "string" }, "key": { "description": "Key name used to reference this attribute.", "example": "blocked", "type": "string" }, "name": { "description": "Display name of the contact attribute.", "example": "Blocked", "type": "string" }, "type": { "description": "Data type of the contact attribute.", "enum": [ "BOOLEAN", "TEXT", "TIME", "ARRAY" ], "example": "BOOLEAN", "type": "string" }, "values": { "description": "Array of possible values for this attribute.\nOnly present when type is \"ARRAY\".", "example": [ "a1", "wa", "a3" ], "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "key", "type" ], "type": "object" }, "ContactAttributeChange": { "description": "Represents a single attribute change, containing the old value, new value, and change actions.", "properties": { "extra": { "description": "An array of change actions that describe what operations were performed on this attribute.", "items": { "$ref": "#/components/schemas/AttributeChangeAction" }, "type": "array" }, "newValue": { "description": "The new value of the attribute after the change.\nCan be a string, number, array, or boolean depending on the attribute type.\nThis field is not included when the value is null.", "example": [ "tag1", "tag2" ] }, "oldValue": { "description": "The previous value of the attribute before the change.\nCan be a string, number, array, or boolean depending on the attribute type.\nThis field is not included when the value is null.", "example": "previous_value" } }, "type": "object" }, "ContactAttributesChanged": { "description": "Represents a contact attributes changed event.\nContains information about which contact attributes were modified and their old/new values.\nThis event is emitted only when at least one persisted contact field actually changes;\nnote-only and contact no-op updates do not emit it.", "properties": { "changedAttributes": { "additionalProperties": { "$ref": "#/components/schemas/ContactAttributeChange" }, "description": "An object containing the changed attributes. Each key represents the name of the changed attribute,\nand the value contains the old value, new value, and change actions.", "example": { "age": { "extra": [ { "action": "CHANGED" } ], "newValue": 26, "oldValue": 25 }, "is_verified": { "extra": [ { "action": "CHANGED" } ], "newValue": true, "oldValue": false }, "remark_name": { "extra": [ { "action": "CHANGED" } ], "newValue": "Priority customer", "oldValue": "Standard customer" }, "tags": { "extra": [ { "action": "ADDED", "id": "686dd294334be8606a5bfxxx", "value": "customer" } ], "newValue": [ "customer", "vip" ] }, "waba_id": { "extra": [ { "action": "CHANGED" } ], "newValue": "wabaId2", "oldValue": "wabaId1" } }, "type": "object" }, "id": { "description": "The ID of the contact whose attributes were changed.", "example": "182426659410206xxxx", "type": "string" }, "phoneNumber": { "description": "The contact's phone number in E.164 format.", "example": "+16315551111", "type": "string" }, "updateTime": { "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", "format": "date-time", "type": "string" } }, "required": [ "id", "updateTime", "changedAttributes" ], "type": "object" }, "ContactCreateRequest": { "description": "Contains the properties of the contact to be created.", "properties": { "countryCode": { "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", "type": "string" }, "customAttributes": { "description": "Contact's custom attributes.", "items": { "$ref": "#/components/schemas/ContactCustomAttribute" }, "type": "array" }, "email": { "description": "Contact's email address.\nIf present, the email address must be unique.", "example": "support@example.com", "maxLength": 250, "type": "string" }, "nickname": { "deprecated": true, "description": "Deprecated compatibility alias for `remarkName`.\nWhen `remarkName` is absent, this value is saved as the contact's remark name. It does not update the read-only WhatsApp nickname.\nMaximum length: 250 characters.", "example": "remark name", "maxLength": 250, "type": "string" }, "notes": { "description": "Optional notes created atomically with the contact. The response remains the Contact schema;\nuse the List Contact Notes endpoint to retrieve generated note IDs.", "items": { "$ref": "#/components/schemas/ContactNoteCreateInput" }, "maxItems": 50, "type": "array" }, "ownerEmail": { "description": "The email address of the contact's owner.", "example": "support@example.com", "maxLength": 250, "type": "string" }, "phoneNumber": { "description": "Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "remarkName": { "description": "Contact's remark name. Maximum length: 250 characters.", "example": "remark name", "maxLength": 250, "type": "string" }, "tags": { "description": "Contact's tags. Max items: 50. Max characters per tag: 50.", "items": { "description": "Tag. Maximum length: 50 characters.", "maxLength": 50, "type": "string" }, "maxItems": 50, "type": "array" } }, "required": [ "phoneNumber" ], "type": "object" }, "ContactCreated": { "description": "Represents a contact created event.\nContains the full contact information that was created.", "properties": { "blocked": { "description": "Whether the contact is blocked.", "example": false, "type": "boolean" }, "countryCode": { "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", "type": "string" }, "countryName": { "description": "Full country name.", "example": "United States", "type": "string" }, "createTime": { "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", "format": "date-time", "type": "string" }, "customAttributes": { "additionalProperties": { "type": "object" }, "description": "Contact's custom attributes as key-value pairs.", "example": { "age": 25, "company": "YCloud Inc", "preferences": { "newsletter": true } }, "type": "object" }, "email": { "description": "The contact's email address.\nIf present, the email address must be unique.", "example": "john.doe@example.com", "type": "string" }, "id": { "description": "Unique ID for the object.", "example": "1824266594102064128", "type": "string" }, "lastConnectedNumber": { "description": "The business phone number that the contact last connected to.", "example": "+16315551111", "type": "string" }, "lastSeen": { "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", "format": "date-time", "type": "string" }, "nickName": { "description": "Contact's nickname.", "example": "John Doe", "type": "string" }, "ownerEmail": { "description": "The email address of the contact's owner.", "example": "support@example.com", "type": "string" }, "phoneNumber": { "description": "Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "realName": { "description": "Contact's real name.", "example": "John Smith", "type": "string" }, "remarkName": { "description": "The business-managed remark name for the contact.", "example": "Priority customer", "type": "string" }, "sourceId": { "description": "The source ID where the contact was created.", "example": "import_batch_123", "type": "string" }, "sourceType": { "description": "The source type where the contact was created.", "example": "api", "type": "string" }, "sourceUrl": { "description": "The source URL where the contact was created.", "example": "https://example.com/signup", "type": "string" }, "tags": { "description": "Contact's tags.", "example": [ "customer", "vip" ], "items": { "type": "string" }, "type": "array" }, "updateTime": { "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", "format": "date-time", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ContactCustomAttribute": { "properties": { "name": { "description": "Name of the attribute that you've previously defined.", "type": "string" }, "value": { "description": "Value of the attribute.\nIts data type depends on the format of the attribute you defined:\nFor Text, the `value` is a string with a maximum length of 250.\nFor Array, the `value` is an array of strings with a maximum length of 250.\nFor Number, the `value` is a signed decimal number.\nFor Boolean, the `value` is either `true` or `false`.\nFor Time, the `value` is a Unix timestamp in milliseconds.\nFor Long Text, the `value` is a string with a maximum length of 5000.", "type": "object" } }, "type": "object" }, "ContactDeleted": { "description": "Represents a contact deleted event.\nContains the contact information that was deleted.", "properties": { "id": { "description": "Contact ID", "example": "1824266594102064129", "type": "string" }, "nickName": { "description": "Contact's nickname.", "example": "Jane Smith", "type": "string" }, "phoneNumber": { "description": "Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16475551234", "type": "string" }, "remarkName": { "description": "The business-managed remark name from the deleted contact snapshot.", "example": "Former customer", "type": "string" }, "updateTime": { "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", "format": "date-time", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ContactNote": { "description": "Represents an internal note attached to a contact.", "properties": { "contactId": { "description": "Unique ID of the contact that owns this note.", "example": 1693364594105000026, "type": "string" }, "content": { "description": "Note content.", "example": "Customer prefers follow-up in the morning.", "maxLength": 500, "type": "string" }, "createTime": { "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", "format": "date-time", "type": "string" }, "id": { "description": "Unique 24-character ObjectId for the contact note. IDs remain unchanged after storage migration.", "example": "6a3de646e18f344f743aaa4d", "maxLength": 24, "minLength": 24, "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "operatorId": { "description": "ID of the actor who created the note.", "example": "user_123", "type": "string" }, "updateOperatorId": { "description": "ID of the actor who last updated the note.", "example": "user_123", "type": "string" }, "updateTime": { "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", "format": "date-time", "type": "string" } }, "required": [ "id", "contactId", "content" ], "type": "object" }, "ContactNoteCreateInput": { "description": "A contact note to create together with a contact.", "properties": { "content": { "description": "Note content. Leading and trailing whitespace is removed before validation and storage.", "example": "Customer prefers follow-up in the morning.", "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" }, "ContactNoteMutationInput": { "description": "An incremental note mutation for a contact update. When `id` is absent, a new note is created.\nWhen `id` is present, the owned note is updated. Notes omitted from the array remain unchanged.", "properties": { "content": { "description": "Note content. Leading and trailing whitespace is removed before validation and storage.", "example": "Customer now prefers afternoon follow-up.", "maxLength": 500, "minLength": 1, "type": "string" }, "id": { "description": "Existing note ID. Omit to create a new note.", "example": "6a3de646e18f344f743aaa4d", "maxLength": 24, "minLength": 24, "pattern": "^[0-9a-fA-F]{24}$", "type": "string" } }, "required": [ "content" ], "type": "object" }, "ContactNoteWebhookPayload": { "description": "Customer-facing Contact Note webhook snapshot. Internal operator identifiers are not exposed.", "properties": { "contactId": { "description": "Unique ID of the contact that owns this note.", "example": 1693364594105000026, "type": "string" }, "content": { "description": "Note content.", "example": "Customer prefers follow-up in the morning.", "maxLength": 500, "type": "string" }, "createTime": { "description": "The time at which the note was created, formatted in RFC 3339.", "example": "2022-06-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "description": "Unique 24-character ObjectId for the contact note. IDs remain unchanged after storage migration.", "example": "6a3de646e18f344f743aaa4d", "maxLength": 24, "minLength": 24, "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "phoneNumber": { "description": "Phone number of the contact that owns this note in E.164 format.", "example": "+16315551111", "nullable": true, "type": "string" }, "updateTime": { "description": "The time at which the note was last updated, formatted in RFC 3339.", "example": "2022-06-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "username": { "description": "Username of the contact that owns this note, without the leading `@`.", "example": "alice_01", "nullable": true, "type": "string" } }, "required": [ "id", "contactId", "username", "phoneNumber", "content", "createTime", "updateTime" ], "type": "object" }, "ContactNoteWriteRequest": { "description": "Request body for creating or updating one contact note.", "properties": { "content": { "description": "Note content. Leading and trailing whitespace is removed before validation and storage.", "example": "Customer now prefers afternoon follow-up.", "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" }, "ContactPage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "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.", "properties": { "cursor": { "$ref": "#/components/schemas/ContactPageCursor" }, "items": { "description": "An array containing contact objects.", "items": { "$ref": "#/components/schemas/Contact" }, "type": "array" } }, "type": "object" }, "ContactPageCursor": { "description": "Position of the next Contact page. This object is returned only when another page exists.", "properties": { "after": { "description": "Contact ID of the last public item in this page. Pass this value unchanged as `pageAfter` to fetch the next page.", "example": "1866762588313988096", "pattern": "^[1-9][0-9]{0,18}$", "type": "string" } }, "required": [ "after" ], "type": "object" }, "ContactSourceType": { "description": "Contact source type enumeration values. These are internal type identifiers, not the display names shown on the contact page.\nEach enumeration value corresponds to the following display names:\n- WHATSAPP: \"Inbound message\"\n- GROWTH_TOOL: \"Link/QR Code\"\n- MANUALLY_ADDED: \"Manually added\"\n- FILE_IMPORT: \"File import\"\n- SHOPIFY: \"Shopify\"\n- API: \"API added\"\n- AD: \"AD\"\n- POST: \"Post\"\n- CALLING: \"Calling\"\n- SMB: \"Whatsapp Business App\"\n- UNKNOWN: \"Unknown\"", "enum": [ "WHATSAPP", "GROWTH_TOOL", "MANUALLY_ADDED", "FILE_IMPORT", "SHOPIFY", "API", "AD", "POST", "CALLING", "SMB", "UNKNOWN" ], "example": "API", "type": "string" }, "ContactUnsubscribeCreated": { "description": "Represents a customer initiates an unsubscribe event.", "properties": { "phoneNumber": { "description": "Unique Customer Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16475551234", "type": "string" }, "source": { "description": "The source from which a customer initiates an unsubscribe.\n- `Whatsapp`: The customer initiated an unsubscribe on the whatsapp client.\n- `Inbox`:You added a customer to the unsubscribe list on the Inbox page of YCloud.\n- `Chatbot`: The message sent by the customer triggered the unsubscribe keyword configured by the Chatbot.\n- `API`: You add customers to the unsubscribe list through YCloud's OpenAPI.\n- `Manual`: You added a customer to the unsubscribe list on the Contact page of YCloud.", "enum": [ "Whatsapp", "Inbox", "Chatbot", "API", "Manual" ], "example": "Whatsapp", "type": "string" }, "updateTime": { "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", "format": "date-time", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ContactUnsubscribeDeleted": { "description": "Represents a customer resumed their subscription event.", "properties": { "phoneNumber": { "description": "Unique Customer Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16475551234", "type": "string" }, "source": { "description": "The source from which a customer resumed their subscription\n- `Whatsapp`: The customer resumed their subscription on the whatsapp client\n- `API`: You remove the customer from the unsubscribe list through the OpenAPI of YCloud\n- `Manual`: You remove the customer from the unsubscribe list on the Contact page of YCloud.", "enum": [ "Whatsapp", "API", "Manual" ], "example": "Whatsapp", "type": "string" }, "updateTime": { "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", "format": "date-time", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ContactUpdateRequest": { "description": "Contains the properties of the contact to be updated.", "properties": { "countryCode": { "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", "type": "string" }, "customAttributes": { "description": "Contact's custom attributes.\nIf present (i.e., not `null`), all previous attributes of this contact will be replaced.", "items": { "$ref": "#/components/schemas/ContactCustomAttribute" }, "type": "array" }, "email": { "description": "The contact's email address.\nIf present, the email address must be unique.", "example": "support@example.com", "maxLength": 250, "type": "string" }, "nickname": { "deprecated": true, "description": "Deprecated compatibility alias for `remarkName`.\nWhen `remarkName` is absent, this value is saved as the contact's remark name. It does not update the read-only WhatsApp nickname.\nMaximum length: 250 characters.", "example": "remark name", "maxLength": 250, "type": "string" }, "notes": { "description": "Optional incremental note mutations. An empty array changes nothing. Items without `id` create notes;\nitems with `id` update owned notes. Notes not listed remain unchanged. Delete notes with the dedicated endpoint.", "items": { "$ref": "#/components/schemas/ContactNoteMutationInput" }, "maxItems": 50, "type": "array" }, "ownerEmail": { "description": "The email address of the contact's owner.", "example": "support@example.com", "maxLength": 250, "type": "string" }, "phoneNumber": { "description": "Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "remarkName": { "description": "Contact's remark name. Maximum length: 250 characters.", "example": "remark name", "maxLength": 250, "type": "string" }, "tags": { "description": "Contact's tags. Maximum items: 50.", "items": { "description": "Tag. Maximum length: 50 characters.", "maxLength": 50, "type": "string" }, "maxItems": 50, "type": "array" } }, "type": "object" }, "CustomEventDefinition": { "description": "Represents a custom event definition.", "properties": { "createTime": { "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", "format": "date-time", "type": "string" }, "description": { "description": "The description of the event definition.", "example": "Describes this property", "type": "string" }, "label": { "description": "The label of the event definition, used for display purposes.", "example": "Property Label", "maxLength": 50, "type": "string" }, "name": { "description": "The name of the custom event definition.", "example": "propertyName", "type": "string" }, "objectType": { "description": "Type of the object that the event will be associated with.\n- `CONTACT`: Indicates that the object is a `contact`.", "enum": [ "CONTACT" ], "example": "CONTACT", "type": "string" }, "properties": { "description": "The list of property definitions for the event definition.", "items": { "$ref": "#/components/schemas/CustomEventDefinitionProperty" }, "type": "array" } }, "type": "object" }, "CustomEventDefinitionCreateRequest": { "description": "Contains the properties of the custom event definition to be created.", "properties": { "description": { "description": "The description of the event.", "example": "Describes this event", "maxLength": 200, "type": "string" }, "label": { "description": "The label of the custom event.", "example": "My event label", "type": "string" }, "name": { "description": "The unique name of the custom event.", "example": "unique_event_name", "maxLength": 50, "pattern": "^[a-z0-9_]{1,50}", "type": "string" }, "objectType": { "description": "Type of the object that the event will be associated with.\n- `CONTACT`: Indicates that the object is a `contact`.", "enum": [ "CONTACT" ], "example": "CONTACT", "type": "string" }, "properties": { "description": "A list of property definitions for the event.", "items": { "$ref": "#/components/schemas/CustomEventDefinitionPropertyCreateRequest" }, "type": "array" } }, "required": [ "name", "label", "objectType" ], "type": "object" }, "CustomEventDefinitionProperty": { "description": "Represents a custom property of a custom event definition.", "properties": { "createTime": { "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", "format": "date-time", "type": "string" }, "description": { "description": "The description of the property.", "example": "Describes this property", "type": "string" }, "label": { "description": "The label of the property, used for display purposes.", "example": "Property Label", "maxLength": 50, "type": "string" }, "name": { "description": "The name of the custom property.", "example": "propertyName", "type": "string" }, "type": { "description": "The data type of the property.\n- `STRING`: Indicates a property that receives plain text strings.\n- `NUMBER`: Indicates a property that receives numeric values with up to one decimal.\n- `TIMESTAMP`: Indicates a property that receives epoch millisecond.\n- `URL`: Indicates a property that receives URLs, formatted as strings starting with `http://` or `https://`.", "enum": [ "STRING", "NUMBER", "TIMESTAMP", "URL" ], "type": "string" } }, "type": "object" }, "CustomEventDefinitionPropertyCreateRequest": { "description": "Contains the properties of the custom event property definition to be created.", "properties": { "description": { "description": "The description of the property.", "example": "Describes this property", "type": "string" }, "label": { "description": "The label of the property.", "example": "Property Label", "maxLength": 50, "type": "string" }, "name": { "description": "The unique name of the custom property.", "example": "unique_property_name", "maxLength": 50, "pattern": "^[a-z][a-z0-9_]{1,50}$", "type": "string" }, "type": { "description": "Type of the property.\n- `STRING`: Indicates a property that receives plain text strings.\n- `NUMBER`: Indicates a property that receives numeric values with up to one decimal.\n- `TIMESTAMP`: Indicates a property that receives epoch millisecond.\n- `URL`: Indicates a property that receives URLs, formatted as strings starting with `http://` or `https://`.", "enum": [ "STRING", "NUMBER", "TIMESTAMP", "URL" ], "example": "STRING", "type": "string" } }, "required": [ "name", "label", "type" ], "type": "object" }, "CustomEventDefinitionPropertyUpdateRequest": { "description": "Contains the properties of the event property definition to be updated.", "properties": { "description": { "description": "The description of the event property definition.", "example": "Describes the event property", "type": "string" }, "label": { "description": "The label of the event property definition.", "example": "New label", "type": "string" } }, "type": "object" }, "CustomEventDefinitionUpdateRequest": { "description": "Contains the properties of the custom event definition to be updated.", "properties": { "description": { "description": "The description of the event definition.", "example": "Describes the event definition", "type": "string" }, "label": { "description": "The label of the event definition.", "example": "New Label", "type": "string" } }, "type": "object" }, "CustomEventSendRequest": { "description": "Contains the properties of the custom event data to be sent.", "properties": { "contactPhoneNumber": { "description": "The phone number of the contact for events defined with `objectType` as `CONTACT`.", "type": "string" }, "eventName": { "description": "Name of the event.\nOne of the custom event names you previously defined.", "example": "unique_event_name", "type": "string" }, "objectId": { "description": "ID of the object that the event is associated with.\nFor events defined with `objectType` as `CONTACT`, the `objectId` should be a `contact` ID. Alternatively, you can use the `contactPhoneNumber` field to specify the contact.", "type": "string" }, "occurTime": { "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`,\nif not provided, the current time will be used.", "example": "2022-06-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "properties": { "additionalProperties": { "type": "object" }, "description": "The properties of the custom event.", "example": { "property1": "value1", "property2": "value2" }, "type": "object" } }, "required": [ "eventName" ], "type": "object" }, "Email": { "properties": { "bcc": { "description": "Recipients who will receive a blind carbon copy of the email.", "items": { "$ref": "#/components/schemas/Mailbox" }, "type": "array" }, "callbackUrl": { "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.\nNote: We recommend configuring Webhook Endpoints instead.", "example": "https://httpbin.org/anything?tag=api-email", "type": "string" }, "cc": { "description": "Recipients who will receive a copy of the email.", "items": { "$ref": "#/components/schemas/Mailbox" }, "type": "array" }, "contentType": { "$ref": "#/components/schemas/EmailContentType" }, "createTime": { "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", "format": "date-time", "type": "string" }, "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "from": { "$ref": "#/components/schemas/Mailbox", "description": "The sender's email address." }, "id": { "description": "Unique ID for the object.", "maxLength": 128, "minLength": 6, "type": "string" }, "replyTo": { "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" }, "type": "array" }, "subject": { "description": "The email subject, which contains a short string identifying the topic of the message.", "maxLength": 255, "type": "string" }, "summary": { "description": "This is a summary of your email. Max length: 70.", "example": "This is a summary.", "maxLength": 70, "type": "string" }, "to": { "description": "The intended recipients' email addresses.", "items": { "$ref": "#/components/schemas/Mailbox" }, "type": "array" }, "totalPrice": { "description": "Total price of this message.", "example": 0.0085, "format": "double", "type": "number" }, "totalRecipients": { "description": "Total recipients of this message, including `to`, `cc` and `bcc`.", "example": 3, "format": "int32", "type": "integer" } }, "required": [ "id" ], "type": "object" }, "EmailContentType": { "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" ], "type": "string", "x-enum-varnames": [ "TEXT_HTML", "TEXT_PLAIN" ] }, "EmailDelivery": { "description": "Represents an email delivery report.", "properties": { "bizType": { "description": "This can be either empty or one of `email`, or `verify`. Defaults to `email`.\n- `email`: Indicates that the message is sent via the **Email** product.\n- `verify`: Indicates that the message is sent via the **Verify** product.", "example": "email", "type": "string" }, "emailId": { "description": "Unique ID for the related email you've previously sent.", "maxLength": 128, "minLength": 6, "type": "string" }, "errorCode": { "description": "Error code when the email is undeliverable.", "example": 402, "type": "string" }, "errorMessage": { "description": "Error message when the email is undeliverable.", "example": "Unsubscribes", "type": "string" }, "externalId": { "description": "The `externalId` you set when you sent the email.", "type": "string" }, "recipientAddress": { "description": "A recipient's email address.", "example": "tom@example.com", "type": "string" }, "status": { "description": "Delivery status of the email to the specific recipient address.\n- `sending`: The messaging request is accepted by our system.\n- `failed`: The message failed to be sent from our system.\n- `sent`: The message has been sent from our system.\n- `delivered`: Our system has received a delivery receipt indicating that message is delivered.\n- `undelivered`: Our system has received a delivery receipt indicating that message is not delivered.", "enum": [ "sending", "failed", "sent", "delivered", "undelivered" ], "example": "failed", "type": "string" }, "verificationId": { "description": "The verification ID. Included only when `bizType` is `verify`.", "example": "VERIFICATION-ID", "type": "string" } }, "required": [ "emailId", "recipientAddress" ], "type": "object" }, "EmailSendRequest": { "properties": { "bcc": { "description": "Recipients who will receive a blind carbon copy of the email.", "example": "bcc1@example.com,Nick", "type": "string" }, "callbackUrl": { "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.\nNote: We recommend configuring Webhook Endpoints instead.", "example": "https://httpbin.org/anything?tag=api-email", "type": "string" }, "cc": { "description": "Recipients who will receive a copy of the email.", "example": "cc1@example.com,Nick", "type": "string" }, "content": { "description": "- The email body. Max size: 150 KB.\n- 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 (`_`).\n- 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#.", "type": "string" }, "contentType": { "$ref": "#/components/schemas/EmailContentType" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "from": { "description": "- The sender's email. Its domain should be one that has been registered and activated in your account.\n- The sender's email address is required while the sender's name is optional. For example, both `support@example.com` and `Sender` work.", "example": "SupportTeam", "type": "string" }, "replyTo": { "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.", "type": "string" }, "subject": { "description": "The email subject, which contains a short string identifying the topic of the message. Max length: 255.", "maxLength": 255, "type": "string" }, "summary": { "description": "This is a summary of your email. Max length: 70.", "example": "This is a summary.", "maxLength": 70, "type": "string" }, "to": { "description": "- The intended recipients' email addresses.\n- Supports a comma-separated list of one or more addresses. Max items: 100.", "example": "to1@example.com,Nick", "type": "string" }, "variables": { "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.\n- 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.\n- This parameter's size will be calculated together with the parameter `content`. The whole size must not exceed 150 KB.", "items": { "additionalProperties": { "type": "string" }, "description": "Variable key-value pair.", "type": "object" }, "type": "array" } }, "required": [ "from", "to", "subject", "content" ], "type": "object" }, "Error": { "properties": { "code": { "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", "type": "string" }, "docUrl": { "description": "A URL to more information about the error.", "example": "", "type": "string" }, "message": { "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.", "type": "string" }, "requestId": { "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", "type": "string" }, "status": { "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, "format": "int32", "pattern": "[45]\\d{2}", "type": "integer" }, "target": { "description": "The target of the error.", "example": "", "type": "string" }, "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).\n\nNote: This field is returned if we tried to request the WhatsApp Business API and got an error response." } }, "required": [ "status", "code" ], "type": "object" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "type": "object" }, "Event": { "description": "Represents a webhook event payload.\nEvery event contains certain common properties: `id`, `type`, `apiVersion`, `createTime`.\nEach event may also contain some properties unique to the event. For example, `sms` is returned when `type` is `sms.message.updated`.", "properties": { "apiVersion": { "description": "The API version used to render this event.", "example": "v2", "type": "string" }, "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`." }, "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`." }, "createTime": { "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", "format": "date-time", "type": "string" }, "emailDelivery": { "$ref": "#/components/schemas/EmailDelivery", "description": "Included when `type` is `email.delivery.updated`." }, "id": { "description": "Unique ID for the event.", "maxLength": 128, "minLength": 6, "type": "string" }, "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`." }, "type": { "$ref": "#/components/schemas/EventType" }, "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`." }, "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." }, "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`." }, "whatsappPayment": { "$ref": "#/components/schemas/WhatsappPayment", "description": "Included when `type` is `whatsapp.payment.updated`." }, "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`." }, "whatsappTemplate": { "$ref": "#/components/schemas/WhatsappTemplate", "description": "Included when `type` is `whatsapp.template.reviewed`, `whatsapp.template.quality_updated`, or `whatsapp.template.category_updated`." }, "whatsappUserPreference": { "$ref": "#/components/schemas/WhatsappUserPreference", "description": "Included when `type` is `whatsapp.user.preferences`." } }, "required": [ "id", "type", "apiVersion", "createTime" ], "type": "object" }, "EventProperty": { "description": "Represents event property configuration for webhook endpoints.\nSpecifies which properties should be included in the webhook payload for a specific event type.", "properties": { "event": { "description": "The event type for which properties are configured.\nThis field accepts any valid event type that supports property configuration.", "example": "contact.attributes_changed", "type": "string" }, "properties": { "description": "A list of property names that should be included in the webhook payload for the specified event type.\nThe available properties depend on the specific event type configured.", "example": [ "attr1", "attr2" ], "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "event", "properties" ], "type": "object" }, "EventType": { "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" ], "type": "string", "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." ] }, "Mailbox": { "description": "Represents a mailbox.", "properties": { "address": { "description": "Address of the mailbox.", "example": "team@example.com", "type": "string" }, "name": { "description": "Name of the mailbox.", "example": "Support Team", "type": "string" } }, "type": "object" }, "MetaBusinessAccountVerificationStatus": { "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" ], "type": "string" }, "Page": { "description": "Represents a given page of items.", "properties": { "items": { "items": { "type": "object" }, "type": "array" }, "length": { "description": "The actual number of items in the page.", "format": "int32", "minimum": 0, "type": "integer" }, "limit": { "description": "A limit on the number of items to be returned, between 1 and 100, defaults to 10.", "format": "int32", "minimum": 1, "type": "integer" }, "offset": { "description": "The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10.", "format": "int32", "minimum": 0, "type": "integer" }, "total": { "description": "The total number of items. This field is returned only when the request parameter `includeTotal` is set to `true`.", "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "offset", "limit", "length" ], "type": "object" }, "PageCursor": { "description": "A cursor object is returned only if the endpoint you requested supports cursor pagination.", "properties": { "after": { "description": "A cursor to fetch the next page in cursor pagination.\nFor 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.\nThis field is returned only if there are more items in the list.", "example": "id:foo", "type": "string" } }, "type": "object" }, "Sms": { "properties": { "bizType": { "description": "This can be either empty or one of `sms`, or `verify`. Defaults to `sms`.\n- `sms`: Indicates that the message is sent via the **SMS** product.\n- `verify`: Indicates that the message is sent via the **Verify** product.", "example": "sms", "type": "string" }, "callbackUrl": { "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.\nNote: We recommend configuring Webhook Endpoints instead.", "example": "https://httpbin.org/anything?tag=api-sms", "type": "string" }, "createTime": { "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", "format": "date-time", "type": "string" }, "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" }, "errorCode": { "description": "Error code when the message is undeliverable.", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "id": { "description": "Unique ID for the object.", "maxLength": 128, "minLength": 6, "type": "string" }, "regionCode": { "description": "[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)", "example": "US", "type": "string" }, "senderId": { "description": "Sender ID to be used.", "example": "Brand", "type": "string" }, "status": { "description": "Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`.\n- `accepted`: The messaging request is accepted by our system.\n- `failed`: The message failed to be sent from our system.\n- `sent`: The message has been sent from our system.\n- `delivered`: Our system has received a delivery receipt indicating that message is delivered.\n- `undelivered`: Our system has received a delivery receipt indicating that message is not delivered.", "enum": [ "accepted", "failed", "sent", "delivered", "undelivered" ], "example": "sent", "type": "string" }, "text": { "description": "The text of this message.", "example": "Your verification code is 123456.", "type": "string" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "totalPrice": { "description": "Total price of this message.", "example": 0.0085, "format": "double", "type": "number" }, "totalSegments": { "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, "format": "int32", "minimum": 1, "type": "integer" }, "updateTime": { "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", "format": "date-time", "type": "string" }, "verificationId": { "description": "The verification ID. Included only when `bizType` is `verify`.", "example": "VERIFICATION-ID", "type": "string" } }, "required": [ "id", "to" ], "type": "object" }, "SmsInbound": { "description": "Represents an inbound SMS message, which means a user replies to your message.", "properties": { "from": { "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", "type": "string" }, "id": { "description": "Unique ID of the message.", "type": "string" }, "sendTime": { "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", "format": "date-time", "type": "string" }, "text": { "description": "The text of this message.", "type": "string" }, "to": { "description": "The receiver's phone number, which is one of your registered Sender IDs.", "type": "string" } }, "type": "object" }, "SmsPage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of SMS messages.", "properties": { "items": { "description": "An array containing SMS objects.", "items": { "$ref": "#/components/schemas/Sms" }, "type": "array" } }, "type": "object" }, "SmsSendRequest": { "properties": { "callbackUrl": { "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.\nNote: We recommend configuring Webhook Endpoints instead.", "example": "https://httpbin.org/anything?tag=api-sms", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "senderId": { "description": "[Sender ID](https://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-features/sender-id) to be used.", "example": "Brand", "type": "string" }, "signature": { "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", "type": "string" }, "text": { "description": "The text of this message.", "example": "Your verification code is 123456.", "type": "string" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" } }, "required": [ "to", "text" ], "type": "object" }, "Unsubscriber": { "description": "An unsubscriber is a configuration item representing that customers opt out of receiving messages from your business.\n**A customer and a channel form a unique identifier for an unsubscriber.**", "properties": { "channel": { "$ref": "#/components/schemas/UnsubscriberChannel" }, "createTime": { "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", "format": "date-time", "type": "string" }, "customer": { "description": "The customer who has opted out.\nFor `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "regionCode": { "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", "type": "string" }, "source": { "description": "The source from which a customer resumed their subscription\n- `Whatsapp`: The customer resumed their subscription on the whatsapp client\n- `API`: You remove the customer from the unsubscribe list through the OpenAPI of YCloud\n- `Manual`: You remove the customer from the unsubscribe list on the Contact page of YCloud.", "enum": [ "Whatsapp", "API", "Manual" ], "example": "Whatsapp", "type": "string" }, "type": { "$ref": "#/components/schemas/UnsubscriberType" } }, "type": "object" }, "UnsubscriberChannel": { "description": "Channel of unsubscriber.\n- `whatsapp`: Indicates that the customer opts out of receiving WhatsApp messages from your business.", "enum": [ "whatsapp" ], "type": "string" }, "UnsubscriberCreateRequest": { "properties": { "channel": { "$ref": "#/components/schemas/UnsubscriberChannel" }, "customer": { "description": "The customer who has opted out.\nFor `type=PHONE_NUMBER`, it should be a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "regionCode": { "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", "type": "string" }, "type": { "$ref": "#/components/schemas/UnsubscriberType" } }, "required": [ "type", "customer", "channel" ], "type": "object" }, "UnsubscriberPage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of unsubscriber objects.", "properties": { "cursor": { "$ref": "#/components/schemas/PageCursor" }, "items": { "description": "An array containing unsubscriber objects.", "items": { "$ref": "#/components/schemas/Unsubscriber" }, "type": "array" } }, "type": "object" }, "UnsubscriberType": { "description": "Type of unsubscriber.\n- `PHONE_NUMBER`: Indicates that the `customer` is a phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "enum": [ "PHONE_NUMBER" ], "type": "string" }, "Verification": { "properties": { "channel": { "$ref": "#/components/schemas/VerificationChannel" }, "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "id": { "description": "ID of the verification.", "example": "ve6j7n8i", "type": "string" }, "sendTime": { "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", "format": "date-time", "type": "string" }, "smsFallback": { "$ref": "#/components/schemas/VerificationFallback", "description": "Included when `smsFallbackEnabled` is `true`." }, "smsFallbackEnabled": { "description": "Whether sms fallback is enabled or not.\nApplicable when `channel` is `whatsapp`. If enabled, we will try to send the verification code via sms when the WhatsApp message is failed.", "type": "boolean" }, "status": { "$ref": "#/components/schemas/VerificationStatus" }, "to": { "description": "Recipient of the verification.", "example": "+16315551111", "type": "string" }, "totalPrice": { "description": "Total price of this verification.", "example": 0.0085, "format": "double", "type": "number" } }, "required": [ "id" ], "type": "object" }, "VerificationChannel": { "description": "Supports several independent channels for verification:\n- `sms`: Sends an SMS message with a verification code.\n- `voice`: Makes a voice call with a verification code.\n- `email_code`: Sends an email with a verification code.\n- `whatsapp`: Sends a WhatsApp message with a verification code.", "enum": [ "sms", "voice", "email_code", "whatsapp" ], "example": "sms", "type": "string" }, "VerificationCheck": { "properties": { "channel": { "$ref": "#/components/schemas/VerificationChannel" }, "id": { "description": "ID of this verification check.", "example": "vc8f92c20", "type": "string" }, "status": { "$ref": "#/components/schemas/VerificationStatus" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format or email address.", "example": "+16315551111", "type": "string" }, "valid": { "description": "Whether the verification code is valid for this check.", "example": false, "type": "boolean" } }, "required": [ "id", "valid" ], "type": "object" }, "VerificationCheckRequest": { "properties": { "code": { "description": "The verification to be checked.", "example": "123456", "type": "string" }, "to": { "description": "The recipient's phone number or email address. One of `verificationId` or `to` is required.", "example": "+16315551111", "type": "string" }, "verificationId": { "description": "ID of the verification to be checked. One of `verificationId` or `to` is required.", "example": "vid", "type": "string" } }, "type": "object" }, "VerificationFallback": { "description": "Contains information about verification fallback. For example, you can enable sms fallback for WhatsApp verification messages.", "properties": { "supported": { "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.", "type": "boolean" }, "unsupportedDetail": { "description": "The detail message why the fallback is unsupported.", "example": "This Sender ID is not registered.", "type": "string" }, "unsupportedReason": { "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", "type": "string" } }, "type": "object" }, "VerificationSendRequest": { "properties": { "channel": { "$ref": "#/components/schemas/VerificationChannel" }, "code": { "description": "Verification code to be sent. This field is optional. If not provided, we will automatically generate a code.", "example": "123456", "maxLength": 8, "minLength": 4, "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.\nIf present, this value will also be attached to the `externalId` of message objects.", "type": "string" }, "language": { "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.\nApplicable languages:\n`ar`: Arabic\n`de`: German\n`en`: English\n`es`: Spanish\n`fr`: French\n`id`: Indonesian\n`it`: Italian\n`pt_BR`: Portuguese\n`ru`: Russian\n`tr`: Turkish\n`vi`: Vietnamese\n`zh_CN`: Simplified Chinese\n`zh_HK`: Traditional Chinese", "example": "en", "type": "string" }, "senderId": { "description": "[Sender ID](https://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-features/sender-id) to be used.", "example": "Brand", "type": "string" }, "signature": { "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", "type": "string" }, "to": { "description": "The recipient's phone number or email address depending on `channel`.\n- Phone number: In [E.164](https://en.wikipedia.org/wiki/E.164) format. Applicable when `channel` is `sms` or `voice`.\n- Email address: For example, `tom@example.com`. Applicable when `channel` is `email_code`.", "example": "+16315551111", "type": "string" } }, "required": [ "channel", "to" ], "type": "object" }, "VerificationStatus": { "description": "Status of the verification.\n- `pending`: The verification message (SMS, Voice, etc.) is sent, waiting to be checked. This happens when you call the 'Start a verification' API successfully.\n- `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.\n- `blocked`: The verification is blocked by user-defined rules such as denylist, and geographical permission restrictions. A blocked verification cannot be checked.\n- `expired`: The verification has expired and cannot be checked anymore.\n- `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" ], "type": "string" }, "Voice": { "properties": { "bizType": { "description": "This can be either empty or one of `voice`, or `verify`. Defaults to `voice`.\n- `voice`: Indicates that the message is sent via the **Voice** product.\n- `verify`: Indicates that the message is sent via **Verify** product.", "example": "voice", "type": "string" }, "callbackUrl": { "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.\nNote: We recommend configuring Webhook Endpoints instead.", "example": "https://httpbin.org/anything?tag=api-voice", "type": "string" }, "createTime": { "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", "format": "date-time", "type": "string" }, "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" }, "errorCode": { "description": "Error code when the message is undeliverable.", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "id": { "description": "Unique ID for the object.", "maxLength": 128, "minLength": 6, "type": "string" }, "language": { "description": "[ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html).", "example": "en", "type": "string" }, "regionCode": { "description": "[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "US", "type": "string" }, "status": { "description": "Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`.\n- `accepted`: The messaging request is accepted by our system.\n- `failed`: The message failed to be sent from our system.\n- `sent`: The message has been sent from our system.\n- `delivered`: Our system has received a delivery receipt indicating that message is delivered.\n- `undelivered`: Our system has received a delivery receipt indicating that message is not delivered.", "enum": [ "accepted", "failed", "sent", "delivered", "undelivered" ], "example": "sent", "type": "string" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "totalPrice": { "description": "Total price of this message.", "example": 0.05, "format": "double", "type": "number" }, "totalSegments": { "description": "Number of message segments. It's always 1 for voice calls.", "example": 1, "format": "int32", "minimum": 1, "type": "integer" }, "updateTime": { "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", "format": "date-time", "type": "string" }, "verificationCode": { "description": "The verification code to be sent, 4 to 6 digits.", "example": "123456", "type": "string" }, "verificationId": { "description": "The verification ID. Included only when `bizType` is `verify`.", "example": "VERIFICATION-ID", "type": "string" } }, "required": [ "id", "to" ], "type": "object" }, "VoicePage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of Voice Calls.", "properties": { "items": { "description": "An array containing Voice objects.", "items": { "$ref": "#/components/schemas/Voice" }, "type": "array" } }, "type": "object" }, "VoiceSendRequest": { "properties": { "callbackUrl": { "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.\nNote: We recommend configuring Webhook Endpoints instead.", "example": "https://httpbin.org/anything?tag=api-voice", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "language": { "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.\nApplicable languages:\n`ar`: Arabic\n`de`: German\n`en`: English\n`es`: Spanish\n`fr`: French\n`id`: Indonesian\n`it`: Italian\n`pt`: Portuguese\n`ru`: Russian\n`tr`: Turkish\n`vi`: Vietnamese\n`zh`: Chinese", "example": "en", "type": "string" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "verificationCode": { "description": "The verification code to be sent, 4 to 6 digits.", "example": "123456", "type": "string" } }, "required": [ "to", "verificationCode" ], "type": "object" }, "WebhookEndpoint": { "properties": { "createTime": { "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", "format": "date-time", "type": "string" }, "description": { "description": "An optional description of what the webhook is used for.", "example": "My first webhook endpoint.", "type": "string" }, "enabledEvents": { "description": "The list of events to enable for this endpoint.", "example": [ "whatsapp.message.updated", "whatsapp.inbound_message.received" ], "items": { "type": "string" }, "type": "array" }, "eventProperties": { "description": "Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types.\nWhen `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type.", "example": [ { "event": "contact.attributes_changed", "properties": [ "attr1", "attr2" ] } ], "items": { "$ref": "#/components/schemas/EventProperty" }, "type": "array" }, "id": { "description": "Unique ID for the object.", "example": "wh627c8640675de8fc689ab9d9", "type": "string" }, "secret": { "description": "The endpoint's secret, used to generate webhook signatures.", "example": "whsec_abc4147651944f02baf3be1eb45d33f1", "type": "string" }, "status": { "$ref": "#/components/schemas/WebhookEndpointStatus" }, "updateTime": { "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", "format": "date-time", "type": "string" }, "url": { "description": "The URL of the webhook endpoint.", "example": "https://httpbin.org/anything?tag=api", "type": "string" } }, "required": [ "id" ], "type": "object" }, "WebhookEndpointCreateRequest": { "properties": { "description": { "description": "An optional description of what the webhook is used for.", "example": "My first webhook endpoint.", "maxLength": 400, "type": "string" }, "enabledEvents": { "description": "The list of events to enable for this endpoint.", "items": { "$ref": "#/components/schemas/EventType" }, "type": "array" }, "eventProperties": { "description": "Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types.\nWhen `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type.", "example": [ { "event": "contact.attributes_changed", "properties": [ "attr1", "attr2" ] } ], "items": { "$ref": "#/components/schemas/EventProperty" }, "type": "array" }, "status": { "$ref": "#/components/schemas/WebhookEndpointStatus" }, "url": { "description": "The URL of the webhook endpoint.", "example": "https://httpbin.org/anything?tag=api", "maxLength": 500, "type": "string" } }, "required": [ "url", "enabledEvents" ], "type": "object" }, "WebhookEndpointPage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of webhook endpoints.", "properties": { "items": { "description": "An array containing webhook endpoint objects.", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" } }, "type": "object" }, "WebhookEndpointStatus": { "description": "Webhook endpoint status.\n- `active`: Indicates that the webhook endpoint is active, and will receive notifications of events monitored.\n- `disabled`: Indicates that the webhook endpoint is disabled, and will not receive notifications.\n- `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" ], "type": "string" }, "WebhookEndpointUpdateRequest": { "properties": { "description": { "description": "An optional description of what the webhook is used for.", "example": "My first webhook endpoint.", "maxLength": 400, "type": "string" }, "enabledEvents": { "description": "The list of events to enable for this endpoint.", "items": { "$ref": "#/components/schemas/EventType" }, "type": "array" }, "eventProperties": { "description": "Optional configuration for event properties in webhook payloads. Specifies which properties should be included for specific event types.\nWhen `enabledEvents` contains `contact.attributes_changed`, this field is required and must contain at least one event property configuration for that event type.", "example": [ { "event": "contact.attributes_changed", "properties": [ "attr1", "attr2" ] } ], "items": { "$ref": "#/components/schemas/EventProperty" }, "type": "array" }, "status": { "$ref": "#/components/schemas/WebhookEndpointStatus" }, "url": { "description": "The URL of the webhook endpoint.", "example": "https://httpbin.org/anything?tag=api", "maxLength": 500, "type": "string" } }, "type": "object" }, "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).", "properties": { "code": { "description": "An error code.", "example": 200002, "type": "string" }, "error_data": { "description": "Additional data about the error. A string or map.\n- For template APIs, this field is a string describing the reason for the error.\n- For message APIs, this field is a map with property `details` describing the reason for the error.", "type": "object" }, "error_subcode": { "description": "Additional code about the error.", "example": 2388109, "type": "string" }, "error_user_msg": { "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.", "type": "string" }, "error_user_title": { "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", "type": "string" }, "fbtrace_id": { "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", "type": "string" }, "is_transient": { "description": "Whether the error is transient.", "example": false, "type": "boolean" }, "message": { "description": "A human-readable description of the error.", "example": "HSM Template creation failed", "type": "string" }, "type": { "description": "Error type.", "example": "OAuthException", "type": "string" } }, "required": [ "message", "code" ], "type": "object" }, "WhatsappAuthIntlRateEligibilityCountry": { "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:\n- June 1, 2024 – Indonesia (country calling code +62, country code `ID`)\n- July 1, 2024 – India (country calling code +91, country code `IN`)\n\nSee also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates).", "properties": { "countryCode": { "description": "[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "IN", "type": "string" }, "startTime": { "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", "format": "date-time", "type": "string" } }, "type": "object" }, "WhatsappAutomaticCreativeOptimizationEnrollStatus": { "description": "Automatic creative optimization feature enrollment status.", "enum": [ "OPT_IN", "OPT_OUT" ], "type": "string" }, "WhatsappAutomaticCreativeOptimizationRetrieveResponse": { "properties": { "creativeOptimizationFeatures": { "additionalProperties": { "type": "string" }, "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.", "example": { "future_meta_feature": "UNKNOWN", "image_brightness_and_contrast": "OPT_IN", "image_touchups": "opt_out" }, "type": "object" }, "wabaId": { "description": "WhatsApp Business Account ID returned by Meta.", "example": "whatsapp-business-account-id", "type": "string" } }, "type": "object" }, "WhatsappAutomaticCreativeOptimizationUpdateRequest": { "properties": { "creativeOptimizationFeatures": { "additionalProperties": false, "description": "A non-empty map of automatic creative optimization feature enrollment values. Only submitted features are updated.\n\nSupported feature keys:\n- `image_brightness_and_contrast`\n- `image_touchups`\n- `add_text_overlay`\n- `image_animation`\n- `image_background_gen`\n- `auto_promotion_tag`\n- `text_extraction_for_headline`\n- `text_extraction_for_tap_target`\n- `product_extensions`\n- `text_formatting_optimization`\n- `hyperlink_formatting`\n- `image_banner`\n- `image_end_card`\n- `dynamic_cta_text`", "example": { "image_brightness_and_contrast": "OPT_IN", "image_touchups": "OPT_OUT" }, "minProperties": 1, "properties": { "add_text_overlay": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "auto_promotion_tag": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "dynamic_cta_text": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "hyperlink_formatting": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "image_animation": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "image_background_gen": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "image_banner": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "image_brightness_and_contrast": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "image_end_card": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "image_touchups": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "product_extensions": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "text_extraction_for_headline": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "text_extraction_for_tap_target": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "text_formatting_optimization": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" } }, "type": "object" } }, "required": [ "creativeOptimizationFeatures" ], "type": "object" }, "WhatsappAutomaticCreativeOptimizationUpdateResponse": { "properties": { "creativeOptimizationFeatures": { "additionalProperties": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationEnrollStatus" }, "description": "The submitted feature enrollment values for PATCH responses, or current feature enrollment values for GET responses.", "example": { "image_brightness_and_contrast": "OPT_IN", "image_touchups": "OPT_OUT" }, "type": "object" }, "wabaId": { "description": "WhatsApp Business Account ID returned by Meta.", "example": "whatsapp-business-account-id", "type": "string" } }, "type": "object" }, "WhatsappBusinessAccount": { "description": "Represents a specific [WhatsApp Business Account (WABA)](https://developers.facebook.com/docs/whatsapp/overview/business-accounts).", "properties": { "accountReviewStatus": { "$ref": "#/components/schemas/WhatsappBusinessAccountReviewStatus" }, "authIntlRateEligibilityCountries": { "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:\n- June 1, 2024 – Indonesia (country calling code +62, country code `ID`)\n- July 1, 2024 – India (country calling code +91, country code `IN`)\n\nSee also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates).", "items": { "$ref": "#/components/schemas/WhatsappAuthIntlRateEligibilityCountry" }, "type": "array" }, "banDate": { "description": "The date when the WABA is banned.", "example": "December 9, 2022", "type": "string" }, "banState": { "$ref": "#/components/schemas/WhatsappBusinessAccountBanState" }, "businessId": { "description": "Business Portfolio ID.", "type": "string" }, "businessName": { "description": "Business Portfolio Name.", "type": "string" }, "businessStatus": { "description": "Business Portfolio Status,Default:APPROVED", "type": "string" }, "businessVerificationStatus": { "$ref": "#/components/schemas/MetaBusinessAccountVerificationStatus" }, "country": { "description": "Country of the WhatsApp Business Account's owning Meta Business account.", "type": "string" }, "currency": { "description": "The currency in which the payment transactions for the WhatsApp Business Account will be processed.", "type": "string" }, "decision": { "$ref": "#/components/schemas/WhatsappReviewDecision", "description": "Review decision made on this WhatsApp Business Account. One of `APPROVED` or `REJECTED` or `DEFERRED`." }, "id": { "description": "WhatApp Business Account ID.", "type": "string" }, "messageTemplateNamespace": { "description": "Namespace string for the message templates that belong to the WhatsApp Business Account.", "type": "string" }, "name": { "description": "User-friendly name to differentiate WhatsApp Business Accounts.", "type": "string" }, "ownershipType": { "description": "Ownership type of the WhatsApp Business Account.", "type": "string" }, "paymentMethodAttached": { "description": "Whether we have attached a payment method to the WhatsApp Business Account.", "type": "boolean" }, "primaryBusinessLocation": { "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.\n[ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "US", "type": "string" }, "primaryFundingId": { "description": "Primary funding ID for the WhatsApp Business Account paid service.", "type": "string" }, "purchaseOrderNumber": { "description": "The purchase order number supplied by the business for payment management purposes.", "type": "string" }, "removedInitiatedBy": { "description": "Raw initiator from the WhatsApp Business Account deletion event. Known values include:\n- `USER`: The removal was initiated by the WhatsApp user.\n- `SYSTEM`: The removal was initiated by the Meta system.\n\nUnknown values are returned as received.", "example": "USER", "type": "string" }, "removedReason": { "description": "Raw reason from the WhatsApp Business Account deletion event. Known values include:\n- `ACCOUNT_DISCONNECTED`: The account was disconnected due to enforcement or because the WhatsApp account was explicitly deleted.\n- `BUSINESS_DOWNGRADE`: The phone number was registered with the consumer WhatsApp app.\n- `CHANGE_NUMBER`: The WhatsApp phone number was changed.\n- `COMPANION_INACTIVITY`: A companion device was inactive for approximately 30 days.\n- `PRIMARY_INACTIVITY`: A primary device was inactive for approximately 30 days.\n- `USER_RE_REGISTERED`: WhatsApp was re-registered on a new device.\n\nUnknown values are returned as received.", "example": "ACCOUNT_DISCONNECTED", "type": "string" }, "removedTime": { "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", "format": "date-time", "type": "string" }, "restrictions": { "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" }, "type": "array" }, "timezoneId": { "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", "type": "string" }, "updateEvent": { "$ref": "#/components/schemas/WhatsappBusinessAccountUpdateEventEnum" }, "violationType": { "description": "Used to report violations imposed on the WABA.\nSee also [WhatsApp Business Platform Policy Violations](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/violations).", "example": "SCAM", "type": "string" }, "whatsappBusinessManagerMessagingLimit": { "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).\n- `TIER_NOT_SET`: The business phone number has not been used to send a message yet.\n- `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period.\n- `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period.\n- `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period.\n- `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period.\n- `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period.\n- `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations.", "example": "TIER_2K", "type": "string" } }, "type": "object" }, "WhatsappBusinessAccountBanState": { "description": "The ban state of the WhatsApp Business Account.", "enum": [ "SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE" ], "type": "string" }, "WhatsappBusinessAccountPage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of WhatsApp Business Accounts.", "properties": { "items": { "description": "An array containing WhatsApp Business Account objects.", "items": { "$ref": "#/components/schemas/WhatsappBusinessAccount" }, "type": "array" } }, "type": "object" }, "WhatsappBusinessAccountRestrictionInfo": { "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": { "expiration": { "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", "format": "date-time", "type": "string" }, "restrictionType": { "description": "Restriction type.", "enum": [ "RESTRICTED_ADD_PHONE_NUMBER_ACTION", "RESTRICTED_BIZ_INITIATED_MESSAGING", "RESTRICTED_CUSTOMER_INITIATED_MESSAGING" ], "type": "string" } }, "type": "object" }, "WhatsappBusinessAccountReviewStatus": { "description": "WhatsApp Business Account review status.", "enum": [ "PENDING", "APPROVED", "REJECTED" ], "type": "string" }, "WhatsappBusinessAccountUpdateEventEnum": { "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.\n- `DISABLED_UPDATE`: WhatsApp Business Account Banned.\n- `ACCOUNT_RESTRICTION`: WhatsApp Business Account Restricted Due To Policy Violations.\n- `ACCOUNT_VIOLATION`: WhatsApp Business Account Violates Policy.\n- `PARTNER_REMOVED`: WhatsApp Business Account was removed from the partner connection.\n- `PARTNER_APP_UNINSTALLED`: WhatsApp Business Account partner app was uninstalled.\n- `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).\n- `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" ], "type": "string" }, "WhatsappBusinessUsername": { "description": "Business Username state for a WhatsApp business phone number.", "properties": { "businessUsername": { "description": "Active Business Username. The value is a plain username without `@`.", "example": "acme.support", "type": "string" }, "businessUsernameStatus": { "$ref": "#/components/schemas/WhatsappBusinessUsernameStatus" }, "businessUsernameUpdatedAt": { "description": "The time when the Business Username state was last updated.", "example": "2026-05-26T12:00:00.000Z", "format": "date-time", "type": "string" }, "displayPhoneNumber": { "description": "Display phone number.", "example": "+1 631-555-1111", "type": "string" }, "id": { "description": "Phone number ID.", "example": "1234567890123456", "type": "string" }, "phoneNumber": { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "requestedBusinessUsername": { "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", "type": "string" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" } }, "type": "object" }, "WhatsappBusinessUsernameDeleteResult": { "description": "Business Username deletion result.\nDeleting 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": { "businessUsernameStatus": { "$ref": "#/components/schemas/WhatsappBusinessUsernameStatus" }, "businessUsernameUpdatedAt": { "description": "The time when the Business Username state was last updated.", "example": "2026-05-26T12:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "description": "Phone number ID.", "example": "1234567890123456", "type": "string" }, "phoneNumber": { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "success": { "description": "Whether the delete request was accepted.", "example": true, "type": "boolean" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" } }, "type": "object" }, "WhatsappBusinessUsernameStatus": { "description": "Business Username state for a WhatsApp business phone number.\n- `not_set`: No active or pending Business Username exists.\n- `active`: A Business Username is active.\n- `reserved`: A requested Business Username is reserved by Meta and may still be under review.\n- `pending_review`: Legacy compatibility value for an under-review request. New writes use `reserved`.\nIf 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" ], "type": "string" }, "WhatsappBusinessUsernameSuggestions": { "description": "Reserved Business Username suggestions.", "properties": { "data": { "example": [ "acme.support", "acme.help" ], "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "WhatsappBusinessUsernameUpdateRequest": { "properties": { "username": { "description": "Business Username to request for the phone number. Send the plain username without `@`.\n\nYCloud 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`.", "example": "acme.support", "maxLength": 35, "minLength": 3, "pattern": "^[A-Za-z0-9._]+$", "type": "string" } }, "required": [ "username" ], "type": "object" }, "WhatsappCallingConnectRequest": { "description": "Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.", "properties": { "from": { "description": "The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+6283138205150", "type": "string" }, "recipient": { "description": "The callee's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided.", "example": "US.1234", "type": "string" }, "sdp": { "description": "The Session Description Protocol (SDP) offer information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866).\nContains 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", "type": "string" }, "sdpType": { "description": "The SDP type, must be \"offer\" for connection requests.", "enum": [ "offer" ], "example": "offer", "type": "string" }, "to": { "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", "type": "string" } }, "required": [ "from", "sdpType", "sdp" ], "type": "object" }, "WhatsappCallingPreAcceptRequest": { "properties": { "phoneId": { "description": "The WhatsApp Business phone number ID.", "example": "461269257068832", "type": "string" }, "sdp": { "description": "The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866).\nContains 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", "type": "string" }, "sdpType": { "description": "The SDP type for pre-accept operations. Must be \"answer\".", "enum": [ "answer" ], "example": "answer", "type": "string" }, "wacid": { "description": "The WhatsApp call ID. Required for inbound call operations.\nThis ID is received from the Call Connect webhook when a WhatsApp user initiates the call.", "example": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIDhEMjc4NEY2QUU4NTA2MTgxNTBGNzQ3N0M4QTBDMTU5HBgNNjI4MzEzODIwNTE1MBUCABUeAA==", "type": "string" } }, "required": [ "phoneId", "wacid", "sdpType", "sdp" ], "type": "object" }, "WhatsappCallingRequest": { "properties": { "from": { "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", "type": "string" }, "phoneId": { "description": "The WhatsApp Business phone number ID.", "example": "436666719526789", "type": "string" }, "sdp": { "description": "The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866).\nRequired 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...", "type": "string" }, "sdpType": { "description": "The SDP type. For pre-accept and accept operations, must be \"answer\".", "enum": [ "offer", "answer" ], "example": "answer", "type": "string" }, "to": { "description": "The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required for outbound call connections.", "example": "+16315551112", "type": "string" }, "wacid": { "description": "The WhatsApp call ID. Required for inbound call operations.\nThis ID is received from the Call Connect webhook when a WhatsApp user initiates the call.", "example": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "type": "string" } }, "type": "object" }, "WhatsappCallingResponse": { "properties": { "success": { "description": "Indicates whether the calling operation was successful.", "example": true, "type": "boolean" }, "wacid": { "description": "The WhatsApp call ID associated with this calling operation.", "example": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA==", "type": "string" } }, "required": [ "success" ], "type": "object" }, "WhatsappCallingTerminateRequest": { "properties": { "phoneId": { "description": "The WhatsApp Business phone number ID.", "example": "461269257068832", "type": "string" }, "wacid": { "description": "The WhatsApp call ID. Required for terminate operations.\nThis ID is received from the Call Connect webhook when a WhatsApp user initiates the call.", "example": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABEYIDNENjg2OEMzNTFFRDkwRkUxRUE1RTgxNjY1NjJCQUJBHBgNNjI4MzEzODIwNTE1MBUCABUeAA==", "type": "string" } }, "required": [ "phoneId", "wacid" ], "type": "object" }, "WhatsappCommerceSettings": { "description": "WhatsApp business phone number's commerce settings.", "properties": { "id": { "description": "Unique ID for the object.", "type": "string" }, "isCartEnabled": { "description": "When enabled, cart-related buttons appear in the conversation, catalog, and product details views.\nWhen the cart is disabled, customers can see products and their details, but all cart related buttons will not appear in any view.", "type": "boolean" }, "isCatalogVisible": { "description": "When enabled, the catalog storefront icon and catalog-related buttons appear in conversation and business profile views.\nWhen 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.", "type": "boolean" } }, "type": "object" }, "WhatsappCommerceSettingsUpdateRequest": { "properties": { "isCartEnabled": { "description": "When enabled, cart-related buttons appear in the conversation, catalog, and product details views.\nWhen the cart is disabled, customers can see products and their details, but all cart related buttons will not appear in any view.", "type": "boolean" }, "isCatalogVisible": { "description": "When enabled, the catalog storefront icon and catalog-related buttons appear in conversation and business profile views.\nWhen 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.", "type": "boolean" } }, "type": "object" }, "WhatsappContactBookEntryDeleteResult": { "description": "Meta's contact book entry deletion result returned by YCloud.", "properties": { "deleted": { "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, "type": "boolean" }, "success": { "description": "Always `true` in an HTTP 200 response.", "example": true, "type": "boolean" } }, "required": [ "success", "deleted" ], "type": "object" }, "WhatsappConversation": { "description": "WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business.\nSee also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing).", "properties": { "expireTime": { "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", "format": "date-time", "type": "string" }, "id": { "description": "Unique ID for the object.", "type": "string" }, "originType": { "$ref": "#/components/schemas/WhatsappConversationOriginType" }, "type": { "$ref": "#/components/schemas/WhatsappConversationType" } }, "type": "object" }, "WhatsappConversationOriginType": { "description": "Indicates [conversation category](https://developers.facebook.com/docs/whatsapp/pricing#conversation-categories). This can also be referred to as a conversation entry point.\n- `referral_conversion`: Indicates a [free entry point conversation](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations).\n- `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.\n- `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.\n- `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.\n- `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" ], "type": "string" }, "WhatsappConversationType": { "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.\n- `FREE_ENTRY`: Conversations originating from a [free entry point](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations).\n- `FREE_TIER`: Conversations within the monthly [free tier](https://developers.facebook.com/docs/whatsapp/pricing#free-tier-conversations).\n- `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" ], "type": "string" }, "WhatsappFlow": { "description": "Represents a WhatsApp Flow.", "properties": { "categories": { "description": "Flow categories.", "items": { "$ref": "#/components/schemas/WhatsappFlowCategory" }, "type": "array" }, "dataApiVersion": { "description": "Version of the Data API.", "example": "3.0", "type": "string" }, "endpointUri": { "description": "The endpoint URI for the Flow.", "example": "https://example.com/flow-endpoint", "type": "string" }, "id": { "description": "Flow ID.", "example": "flow-1", "type": "string" }, "jsonVersion": { "description": "Version of the Flow JSON structure.", "example": "3.0", "type": "string" }, "name": { "description": "Flow name.", "example": "My first flow", "type": "string" }, "status": { "$ref": "#/components/schemas/WhatsappFlowStatus" }, "validationErrors": { "description": "List of validation errors.", "items": { "$ref": "#/components/schemas/WhatsappFlowValidationError" }, "type": "array" }, "whatsappBusinessAccount": { "description": "WhatsApp Business Account information.", "properties": { "currency": { "description": "Currency used by the WhatsApp Business Account.", "example": "EUR", "type": "string" }, "id": { "description": "WhatsApp Business Account ID.", "example": "463056733559090", "type": "string" }, "name": { "description": "WhatsApp Business Account name.", "example": "Waba - Name", "type": "string" } }, "type": "object" } }, "type": "object" }, "WhatsappFlowCategory": { "description": "Category of the WhatsApp Flow.\n- `SIGN_UP`: For sign-up processes.\n- `SIGN_IN`: For sign-in processes.\n- `APPOINTMENT_BOOKING`: For booking appointments.\n- `LEAD_GENERATION`: For lead generation.\n- `CONTACT_US`: For contact forms.\n- `CUSTOMER_SUPPORT`: For customer support.\n- `SURVEY`: For surveys.\n- `OTHER`: For other purposes.", "enum": [ "SIGN_UP", "SIGN_IN", "APPOINTMENT_BOOKING", "LEAD_GENERATION", "CONTACT_US", "CUSTOMER_SUPPORT", "SURVEY", "OTHER" ], "type": "string" }, "WhatsappFlowPreviewUrl": { "properties": { "expiresAt": { "example": "2022-03-01T12:00:00.000Z", "format": "date-time", "type": "string" }, "previewUrl": { "description": "The flow preview url", "example": "https://business.facebook.com/wa/manage/flows/123456/preview/?token=xxxx", "type": "string" } } }, "WhatsappFlowStatus": { "description": "Status of the WhatsApp Flow.\n- `DRAFT`: The Flow is in draft state and can be modified.\n- `PUBLISHED`: The Flow is published and cannot be modified.\n- `DEPRECATED`: The Flow is deprecated and cannot be used.", "enum": [ "DRAFT", "PUBLISHED", "DEPRECATED" ], "type": "string" }, "WhatsappFlowValidationError": { "description": "Represents a validation error in a WhatsApp Flow.", "properties": { "columnEnd": { "description": "End column of the error.", "example": 34, "type": "integer" }, "columnStart": { "description": "Start column of the error.", "example": 21, "type": "integer" }, "error": { "description": "Error code.", "example": "INVALID_PROPERTY_VALUE", "type": "string" }, "errorType": { "description": "Error type.", "example": "FLOW_JSON_ERROR", "type": "string" }, "lineEnd": { "description": "End line of the error.", "example": 10, "type": "integer" }, "lineStart": { "description": "Start line of the error.", "example": 10, "type": "integer" }, "message": { "description": "Error message.", "example": "Invalid value found for property 'type'.", "type": "string" }, "pointers": { "description": "List of pointers to the error location.", "items": { "properties": { "columnEnd": { "description": "End column of the error.", "example": 34, "type": "integer" }, "columnStart": { "description": "Start column of the error.", "example": 21, "type": "integer" }, "lineEnd": { "description": "End line of the error.", "example": 10, "type": "integer" }, "lineStart": { "description": "Start line of the error.", "example": 10, "type": "integer" }, "path": { "description": "Path to the error location.", "example": "screens[0].layout.children[0].type", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "WhatsappGroup": { "description": "WhatsApp group object.", "properties": { "creationTimestamp": { "description": "Unix timestamp indicating when the group was created.", "example": 1739321024, "format": "int64", "type": "integer" }, "description": { "description": "The group description.", "example": "Group for purchase inquiries.", "maxLength": 2048, "type": "string" }, "groupId": { "description": "WhatsApp group ID.", "example": "120363345678901234@g.us", "type": "string" }, "joinApprovalMode": { "$ref": "#/components/schemas/WhatsappGroupJoinApprovalMode" }, "participants": { "description": "Group participants.", "items": { "$ref": "#/components/schemas/WhatsappGroupParticipant" }, "type": "array" }, "subject": { "description": "The group subject.", "example": "New Purchase Inquiry", "maxLength": 128, "type": "string" }, "suspended": { "description": "Whether the group is suspended.", "example": false, "type": "boolean" }, "totalParticipantCount": { "description": "Total number of participants in the group.", "example": 3, "type": "integer" } }, "type": "object" }, "WhatsappGroupAsyncResponse": { "description": "Response for asynchronous WhatsApp group operations.", "properties": { "requestId": { "description": "The request ID for tracking the asynchronous operation in webhooks.", "example": "REQ_1", "type": "string" }, "status": { "description": "The asynchronous request status.", "enum": [ "pending" ], "example": "pending", "type": "string" } }, "type": "object" }, "WhatsappGroupCreateRequest": { "properties": { "description": { "description": "The group description.", "example": "Group for purchase inquiries.", "maxLength": 2048, "type": "string" }, "joinApprovalMode": { "$ref": "#/components/schemas/WhatsappGroupJoinApprovalMode", "description": "Defaults to `auto_approve` when omitted." }, "subject": { "description": "The group subject.", "example": "New Purchase Inquiry", "maxLength": 128, "type": "string" } }, "required": [ "subject" ], "type": "object" }, "WhatsappGroupCustomerProfile": { "description": "WhatsApp customer profile information.", "properties": { "name": { "description": "WhatsApp profile name.", "example": "John Doe", "type": "string" }, "username": { "description": "WhatsApp username.", "example": "john_doe", "type": "string" } }, "type": "object" }, "WhatsappGroupFailedJoinRequest": { "properties": { "errors": { "description": "Errors returned by WhatsApp for this join request.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "joinRequestId": { "description": "The join request ID.", "example": "join-request-id", "type": "string" } }, "type": "object" }, "WhatsappGroupInviteLink": { "description": "WhatsApp group invite link object.", "properties": { "inviteLink": { "description": "The group invite link.", "example": "https://chat.whatsapp.com/AbCdEfGhIjK", "type": "string" } }, "type": "object" }, "WhatsappGroupInviteLinkMessageRequest": { "description": "Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.", "properties": { "languageCode": { "description": "The template language code.", "example": "en_US", "type": "string" }, "parameters": { "description": "Template body parameters in template variable order. Must include one group invite link parameter with `type=group_id` and `group_id=`.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameter" }, "type": "array" }, "recipient": { "description": "The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided.", "example": "US.1234", "type": "string" }, "templateName": { "description": "The name of the approved WhatsApp template.", "example": "group_invite_link", "type": "string" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided.", "example": "+16315551111", "type": "string" } }, "required": [ "templateName", "languageCode", "parameters" ], "type": "object" }, "WhatsappGroupJoinApprovalMode": { "description": "WhatsApp group join approval mode.\n- `approval_required`: New members must be approved before joining.\n- `auto_approve`: New members can join without approval.", "enum": [ "approval_required", "auto_approve" ], "example": "auto_approve", "type": "string" }, "WhatsappGroupJoinRequest": { "description": "WhatsApp group join request object.", "properties": { "creationTimestamp": { "description": "Unix timestamp indicating when the join request was created.", "example": 1739321024, "format": "int64", "type": "integer" }, "joinRequestId": { "description": "The join request ID.", "example": "join-request-id", "type": "string" }, "parentUserId": { "description": "Parent business-scoped user ID.", "example": "US.parent123", "type": "string" }, "userId": { "description": "Business-scoped user ID.", "example": "US.1234", "type": "string" }, "username": { "description": "WhatsApp username.", "example": "John", "type": "string" }, "waId": { "description": "WhatsApp user ID.", "example": "16315551111", "type": "string" } }, "type": "object" }, "WhatsappGroupJoinRequestActionRequest": { "properties": { "joinRequests": { "description": "Join request IDs to approve or reject.", "example": [ "join-request-id" ], "items": { "type": "string" }, "type": "array" } }, "required": [ "joinRequests" ], "type": "object" }, "WhatsappGroupJoinRequestActionResponse": { "description": "Result of approving or rejecting group join requests.", "properties": { "approvedJoinRequests": { "description": "Approved join request IDs.", "items": { "type": "string" }, "type": "array" }, "errors": { "description": "Errors returned by WhatsApp.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "failedJoinRequests": { "description": "Join requests that failed to be processed.", "items": { "$ref": "#/components/schemas/WhatsappGroupFailedJoinRequest" }, "type": "array" }, "rejectedJoinRequests": { "description": "Rejected join request IDs.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "WhatsappGroupJoinRequestListResponse": { "description": "Cursor-paginated WhatsApp group join request response.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WhatsappGroupJoinRequest" }, "type": "array" }, "paging": { "$ref": "#/components/schemas/WhatsappGroupPaging" } }, "type": "object" }, "WhatsappGroupListItem": { "description": "WhatsApp group list item.", "properties": { "createdAt": { "description": "Unix timestamp indicating when the group was created.", "example": 1739321024, "format": "int64", "type": "integer" }, "groupId": { "description": "WhatsApp group ID.", "example": "120363345678901234@g.us", "type": "string" }, "subject": { "description": "The group subject.", "example": "New Purchase Inquiry", "type": "string" } }, "type": "object" }, "WhatsappGroupListResponse": { "description": "Cursor-paginated WhatsApp group list response.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WhatsappGroupListItem" }, "type": "array" }, "paging": { "$ref": "#/components/schemas/WhatsappGroupPaging" } }, "type": "object" }, "WhatsappGroupPaging": { "description": "Cursor pagination information.", "properties": { "after": { "description": "Cursor for the next page.", "example": "eyJvIjoiYWZ0ZXIifQ", "type": "string" }, "before": { "description": "Cursor for the previous page.", "example": "eyJvIjoiYmVmb3JlIn0", "type": "string" } }, "type": "object" }, "WhatsappGroupParticipant": { "description": "WhatsApp group participant object.", "properties": { "parentUserId": { "description": "Parent business-scoped user ID.", "example": "US.parent123", "type": "string" }, "userId": { "description": "Business-scoped user ID.", "example": "US.1234", "type": "string" }, "username": { "description": "WhatsApp username.", "example": "John", "type": "string" }, "waId": { "description": "WhatsApp user ID.", "example": "16315551111", "type": "string" } }, "type": "object" }, "WhatsappGroupRemoveParticipant": { "description": "Participant identifier for a group removal request. Provide exactly one of `user` or `fromUserId`.", "properties": { "fromUserId": { "description": "Business-scoped user ID to remove. Also accepts `userId` as an alias.", "example": "US.1234", "pattern": "^[A-Z]{2}\\.[A-Za-z0-9]{1,128}$", "type": "string" }, "user": { "description": "WhatsApp user ID to remove.", "example": "16315551111", "type": "string" } }, "type": "object" }, "WhatsappGroupRemoveParticipantsRequest": { "properties": { "participants": { "description": "Participants to remove. Up to 8 participants are supported in one request.", "items": { "$ref": "#/components/schemas/WhatsappGroupRemoveParticipant" }, "maxItems": 8, "type": "array" } }, "required": [ "participants" ], "type": "object" }, "WhatsappGroupUpdateSettingsRequest": { "description": "Contains the group settings to update. At least one of `subject` or `description` is required.", "properties": { "description": { "description": "The group description.", "example": "Group for purchase inquiries.", "maxLength": 2048, "type": "string" }, "subject": { "description": "The group subject.", "example": "New Purchase Inquiry", "maxLength": 128, "type": "string" } }, "type": "object" }, "WhatsappGroupWebhook": { "description": "WhatsApp group webhook payload.", "properties": { "addedParticipants": { "description": "Participants added to the group.", "items": { "$ref": "#/components/schemas/WhatsappGroupWebhookParticipant" }, "type": "array" }, "contacts": { "description": "Contacts included in group message status webhooks.", "items": { "$ref": "#/components/schemas/WhatsappGroupWebhookStatusContact" }, "type": "array" }, "customerProfile": { "$ref": "#/components/schemas/WhatsappGroupCustomerProfile" }, "dedupeKey": { "description": "Idempotency key for deduplicating group webhook events.", "example": "WABA_ID|REQ_1|group_lifecycle_update|group_create|created", "type": "string" }, "description": { "description": "The group description.", "example": "Group for purchase inquiries.", "type": "string" }, "displayPhoneNumber": { "description": "The display phone number from WhatsApp webhook metadata.", "example": "16315551111", "type": "string" }, "errors": { "description": "Errors returned by WhatsApp.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "failedParticipants": { "description": "Participants that failed to be added or removed.", "items": { "$ref": "#/components/schemas/WhatsappGroupWebhookParticipant" }, "type": "array" }, "field": { "$ref": "#/components/schemas/WhatsappGroupWebhookField" }, "groupId": { "description": "WhatsApp group ID.", "example": "120363345678901234@g.us", "type": "string" }, "initiatedBy": { "description": "Indicates who initiated a participant removal event.", "enum": [ "business", "participant" ], "example": "business", "type": "string" }, "inviteLink": { "description": "The group invite link.", "example": "https://chat.whatsapp.com/AbCdEfGhIjK", "type": "string" }, "joinApprovalMode": { "$ref": "#/components/schemas/WhatsappGroupJoinApprovalMode" }, "joinRequestId": { "description": "The join request ID.", "example": "join-request-id", "type": "string" }, "parentRecipientUserId": { "description": "Parent business-scoped user ID for a single participant event.", "example": "US.parent123", "type": "string" }, "phoneNumberId": { "description": "WhatsApp phone number ID.", "example": "1234567890123456", "type": "string" }, "reason": { "description": "The reason for a participant, join request, or removal event.", "example": "invite_link", "type": "string" }, "recipientUserId": { "description": "Business-scoped user ID for a single participant event.", "example": "US.1234", "type": "string" }, "removedParticipants": { "description": "Participants removed from the group.", "items": { "$ref": "#/components/schemas/WhatsappGroupWebhookParticipant" }, "type": "array" }, "requestId": { "description": "The request ID returned by an asynchronous group API operation.", "example": "REQ_1", "type": "string" }, "settings": { "description": "Group setting update details.", "items": { "$ref": "#/components/schemas/WhatsappGroupWebhookSetting" }, "type": "array" }, "status": { "$ref": "#/components/schemas/WhatsappGroupWebhookStatus" }, "statuses": { "description": "Group message status details.", "items": { "$ref": "#/components/schemas/WhatsappGroupWebhookMessageStatus" }, "type": "array" }, "subject": { "description": "The group subject.", "example": "New Purchase Inquiry", "type": "string" }, "type": { "$ref": "#/components/schemas/WhatsappGroupWebhookType" }, "waId": { "description": "WhatsApp user ID for a single participant event.", "example": "16315551111", "type": "string" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "123456789012345", "type": "string" }, "webhookTime": { "description": "The time at which WhatsApp triggered this webhook.", "example": "2026-05-13T00:00:00.000Z", "format": "date-time", "type": "string" } }, "type": "object" }, "WhatsappGroupWebhookConversation": { "description": "WhatsApp conversation object included in group message status webhooks.", "properties": { "expirationTimestamp": { "description": "Unix timestamp indicating when the conversation expires.", "example": 1739321024, "format": "int64", "type": "integer" }, "id": { "description": "Conversation ID.", "example": "conversation-id", "type": "string" }, "origin": { "$ref": "#/components/schemas/WhatsappGroupWebhookConversationOrigin" } }, "type": "object" }, "WhatsappGroupWebhookConversationOrigin": { "properties": { "type": { "description": "Conversation origin type.", "example": "service", "type": "string" } }, "type": "object" }, "WhatsappGroupWebhookField": { "description": "WhatsApp webhook field that produced the group event.", "enum": [ "group_lifecycle_update", "group_participants_update", "group_settings_update", "group_status_update", "messages" ], "type": "string" }, "WhatsappGroupWebhookMessageStatus": { "description": "Group message status detail.", "properties": { "conversation": { "$ref": "#/components/schemas/WhatsappGroupWebhookConversation" }, "errors": { "description": "Errors returned by WhatsApp.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "id": { "description": "WhatsApp message ID.", "example": "wamid.1", "type": "string" }, "parentRecipientUserId": { "description": "Parent business-scoped user ID of the recipient participant.", "example": "US.parent123", "type": "string" }, "pricing": { "$ref": "#/components/schemas/WhatsappGroupWebhookPricing" }, "recipientId": { "description": "Recipient group ID.", "example": "120363345678901234@g.us", "type": "string" }, "recipientParticipantId": { "description": "WhatsApp user ID of the recipient participant.", "example": "16315551111", "type": "string" }, "recipientType": { "description": "Recipient type.", "enum": [ "group" ], "example": "group", "type": "string" }, "recipientUserId": { "description": "Business-scoped user ID of the recipient participant.", "example": "US.1234", "type": "string" }, "status": { "description": "Message status.", "example": "delivered", "type": "string" }, "timestamp": { "description": "Unix timestamp indicating when the message status was updated.", "example": 1739321024, "format": "int64", "type": "integer" } }, "type": "object" }, "WhatsappGroupWebhookParticipant": { "description": "Participant information included in group webhook payloads.", "properties": { "customerProfile": { "$ref": "#/components/schemas/WhatsappGroupCustomerProfile" }, "errors": { "description": "Errors returned by WhatsApp for this participant.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "input": { "description": "The original participant input.", "example": "US.1234", "type": "string" }, "parentRecipientUserId": { "description": "Parent business-scoped user ID.", "example": "US.parent123", "type": "string" }, "recipientUserId": { "description": "Business-scoped user ID.", "example": "US.1234", "type": "string" }, "waId": { "description": "WhatsApp user ID.", "example": "16315551111", "type": "string" } }, "type": "object" }, "WhatsappGroupWebhookPricing": { "description": "Pricing information included in group message status webhooks.", "properties": { "billable": { "description": "Whether the message is billable.", "example": true, "type": "boolean" }, "category": { "description": "Pricing category.", "example": "service", "type": "string" }, "pricingModel": { "description": "Pricing model.", "example": "PMP", "type": "string" }, "type": { "description": "Pricing type.", "example": "regular", "type": "string" } }, "type": "object" }, "WhatsappGroupWebhookSetting": { "description": "Group setting update detail.", "properties": { "errors": { "description": "Errors returned by WhatsApp for this setting.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "mimeType": { "description": "MIME type for profile picture updates.", "example": "image/jpeg", "type": "string" }, "name": { "description": "Setting name.", "enum": [ "profile_picture", "group_subject", "group_description" ], "example": "group_subject", "type": "string" }, "sha256": { "description": "SHA-256 hash for profile picture updates.", "example": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "type": "string" }, "text": { "description": "Text value for subject or description updates.", "example": "New Purchase Inquiry", "type": "string" }, "updateSuccessful": { "description": "Whether the setting update succeeded.", "example": true, "type": "boolean" } }, "type": "object" }, "WhatsappGroupWebhookStatus": { "description": "WhatsApp group webhook status.", "enum": [ "created", "failed", "deleted", "added", "removed", "left", "requested", "revoked", "updated", "suspended", "suspend_cleared", "sent", "delivered", "read" ], "type": "string" }, "WhatsappGroupWebhookStatusContact": { "description": "Contact information included in group message status webhooks.", "properties": { "customerProfile": { "$ref": "#/components/schemas/WhatsappGroupCustomerProfile" }, "parentRecipientUserId": { "description": "Parent business-scoped user ID.", "example": "US.parent123", "type": "string" }, "recipientUserId": { "description": "Business-scoped user ID.", "example": "US.1234", "type": "string" }, "waId": { "description": "WhatsApp user ID.", "example": "16315551111", "type": "string" } }, "type": "object" }, "WhatsappGroupWebhookType": { "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" ], "type": "string" }, "WhatsappInboundMessage": { "description": "WhatsApp inbound message object.", "properties": { "audio": { "$ref": "#/components/schemas/WhatsappInboundMessageMedia" }, "button": { "$ref": "#/components/schemas/WhatsappInboundMessageButton" }, "contacts": { "items": { "$ref": "#/components/schemas/WhatsappMessageContact" }, "type": "array" }, "context": { "$ref": "#/components/schemas/WhatsappInboundMessageContext" }, "customerProfile": { "$ref": "#/components/schemas/WhatsappProfile", "description": "The customer's profile information." }, "document": { "$ref": "#/components/schemas/WhatsappInboundMessageMedia" }, "errors": { "items": { "$ref": "#/components/schemas/WhatsappInboundMessageError" }, "type": "array" }, "from": { "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", "type": "string" }, "fromParentUserId": { "description": "The customer's parent WhatsApp Business-scoped user ID.", "example": "US.parent123", "type": "string" }, "fromUserId": { "description": "The customer's WhatsApp Business-scoped user ID (BSUID).", "example": "US.1234", "type": "string" }, "groupId": { "description": "WhatsApp group ID. This field is included when the inbound message is sent in a WhatsApp group.", "example": "120363345678901234@g.us", "type": "string" }, "id": { "description": "Unique ID for the object.", "type": "string" }, "image": { "$ref": "#/components/schemas/WhatsappInboundMessageMedia" }, "interactive": { "$ref": "#/components/schemas/WhatsappInboundMessageInteractive" }, "location": { "$ref": "#/components/schemas/WhatsappInboundMessageLocation" }, "order": { "$ref": "#/components/schemas/WhatsappInboundMessageOrder" }, "reaction": { "$ref": "#/components/schemas/WhatsappMessageReaction" }, "referral": { "$ref": "#/components/schemas/WhatsappInboundMessageReferral" }, "sendTime": { "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", "format": "date-time", "type": "string" }, "sticker": { "$ref": "#/components/schemas/WhatsappInboundMessageMedia" }, "system": { "$ref": "#/components/schemas/WhatsappInboundMessageSystem" }, "text": { "$ref": "#/components/schemas/WhatsappInboundMessageText" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "type": { "$ref": "#/components/schemas/WhatsappInboundMessageType" }, "video": { "$ref": "#/components/schemas/WhatsappInboundMessageMedia" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" }, "wamid": { "description": "The original message ID on WhatsApp's platform.", "example": "wamid.BgNODYxN...", "type": "string" } }, "required": [ "id" ], "type": "object" }, "WhatsappInboundMessageButton": { "description": "When the message type field is set to `button`, this object is included in the message object.", "properties": { "payload": { "description": "The payload for a button set up by the business that a customer clicked as part of an interactive message.", "type": "string" }, "text": { "description": "Button text.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageContext": { "description": "Message context.", "properties": { "forwarded": { "description": "**Added to Webhooks if message was forwarded.**\n\nSet to `true` if the received message has been forwarded.", "type": "boolean" }, "frequently_forwarded": { "description": "**Added to Webhooks if message has been frequently forwarded.**\n\nSet to `true` if the received message has been forwarded more than five times.", "type": "boolean" }, "from": { "description": "**Added to Webhooks if message is an inbound reply to a sent message.**\n\nThe WhatsApp ID (a phone number without the '+' prefix) of the sender of the sent message.", "type": "string" }, "id": { "description": "**Optional.**\n\nThe `wamid` for the sent message for an inbound reply. `wamid` is the original message ID on WhatsApp's platform.", "example": "wamid.BgNODYxN...", "type": "string" }, "referred_product": { "$ref": "#/components/schemas/WhatsappInboundMessageReferredProduct", "description": "**Required for Product Inquiry Messages.**\n\nSpecifies 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)." } }, "type": "object" }, "WhatsappInboundMessageError": { "description": "When the message type `unsupported`, this object is included.", "properties": { "code": { "description": "The error code.", "example": 131051, "type": "string" }, "error_data": { "description": "An error data object with the following properties:\n- `details`: A string describing the reason for the error. Example: `Message type is currently not supported.`.", "type": "object" }, "message": { "description": "The error message.", "example": "Message type unknown", "type": "string" }, "title": { "description": "The error title.", "example": "Message type unknown", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageInteractive": { "description": "When a customer has interacted with your message, this object is included in the message object.", "properties": { "button_reply": { "description": "Sent when a customer clicks a button. Returned when `type` is `button_reply`.", "properties": { "id": { "description": "Unique ID of the clicked button.", "type": "string" }, "title": { "description": "Title of a button.", "type": "string" } }, "type": "object" }, "call_permission_reply": { "description": "Sent when a customer responds to a call permission request. Returned when `type` is `call_permission_reply`.\nThis occurs when WhatsApp prompts users to grant callback permissions after they call your business.", "properties": { "expiration_timestamp": { "description": "The timestamp (in seconds) when the call permission expires.\nOnly present when response is \"accept\" and is_permanent is false.", "example": 1672531200, "format": "int64", "type": "integer" }, "is_permanent": { "description": "Whether the permission is permanent or temporary.\n- `true`: Permanent authorization (no expiration)\n- `false`: Temporary authorization (expires at expiration_timestamp)", "example": false, "type": "boolean" }, "response": { "description": "The customer's response to the call permission request.\n- `accept`: User granted permission for business to call back\n- `reject`: User rejected permission for business to call back", "enum": [ "accept", "reject" ], "example": "accept", "type": "string" }, "response_source": { "description": "The source of this permission response.\n- `user_action`: User explicitly approved or rejected the permission\n- `automatic`: Automatic permission approval due to the WhatsApp user initiating the call", "enum": [ "user_action", "automatic" ], "example": "user_action", "type": "string" } }, "type": "object" }, "list_reply": { "description": "Sent when a customer selects an item from a list. Returned when `type` is `list_reply`.", "properties": { "description": { "description": "Description of the selected row.", "type": "string" }, "id": { "description": "Unique ID of the selected list item.", "type": "string" }, "title": { "description": "Title of the selected list item.", "type": "string" } }, "type": "object" }, "nfm_reply": { "description": "Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging). Returned when `type` is `nfm_reply`.", "properties": { "body": { "description": "The body content of the flow reply message.", "example": "Sent", "type": "string" }, "name": { "description": "The name of the flow or form being replied to.", "example": "flow", "type": "string" }, "response_json": { "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\"}", "type": "string" } }, "type": "object" }, "type": { "description": "The type of interactive message received.\n- `button_reply`: Sent when a customer clicks a button.\n- `list_reply`: Sent when a customer selects an item from a list.\n- `nfm_reply`: Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging).\n- `call_permission_reply`: Sent when a customer responds to a call permission request.", "enum": [ "button_reply", "list_reply", "nfm_reply", "call_permission_reply" ], "type": "string" } }, "type": "object" }, "WhatsappInboundMessageLocation": { "description": "When you receive a notification of a user's static location, the location object provides the details of the location.", "properties": { "address": { "description": "Address of the location.", "type": "string" }, "latitude": { "description": "Latitude of location being sent.", "format": "double", "type": "number" }, "longitude": { "description": "Longitude of location being sent.", "format": "double", "type": "number" }, "name": { "description": "Name of the location.", "type": "string" }, "url": { "description": "URL for the website where the user downloaded the location information.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageMedia": { "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": { "caption": { "description": "The provided caption for the media. Only present if specified.", "type": "string" }, "filename": { "description": "Filename on the sender's device. This will only be present in `document` media messages.", "type": "string" }, "id": { "description": "ID of the media. Can be used to delete the media if stored locally on the client.", "type": "string" }, "link": { "description": "The url to download the media file.\nNote 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.", "type": "string" }, "metadata": { "additionalProperties": { "type": "object" }, "description": "Metadata pertaining to `sticker` media.", "type": "object" }, "mime_type": { "description": "Mime type of the media.", "type": "string" }, "sha256": { "description": "Checksum.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageOrder": { "description": "When a customer places an order, the message type is set to `order`, and this field is included.", "properties": { "catalog_id": { "description": "The catalog ID.", "example": "the-catalog_id", "type": "string" }, "product_items": { "items": { "$ref": "#/components/schemas/WhatsappInboundMessageOrderProductItem" }, "type": "array" }, "text": { "description": "Text message sent along with the order.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageOrderProductItem": { "properties": { "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" }, "item_price": { "description": "Unitary price of item.", "format": "double", "type": "number" }, "product_retailer_id": { "description": "The product SKU identifier.", "type": "string" }, "quantity": { "description": "Number of item.", "format": "int32", "type": "integer" } }, "type": "object" }, "WhatsappInboundMessageReferral": { "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": { "body": { "description": "The description, or body, from the ad or post that generated the message.", "type": "string" }, "ctwa_clid": { "description": "Click ID generated by Meta for ads that click to WhatsApp.", "type": "string" }, "headline": { "description": "Specifies the headline used in the ad or post that generated the message.", "type": "string" }, "image_url": { "description": "**Added if media_type is \"image\".**\n\nContains a URL to the raw image.", "type": "string" }, "media_type": { "description": "Media present in the ad or post the user clicked. Supported values are \"image\" or \"video\".", "type": "string" }, "source_id": { "description": "Specifies the Meta ID for an ad or post.", "type": "string" }, "source_type": { "description": "Specifies the type of the ad's source. Supported values are \"ad\" or \"post\".", "type": "string" }, "source_url": { "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.", "type": "string" }, "thumbnail_url": { "description": "**Added if media_type is \"video\".**\n\nContains a URL to the thumbnail image of the clicked video.", "type": "string" }, "video_url": { "description": "**Added if media_type is \"video\".**\n\nContains a URL to the video.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageReferredProduct": { "description": "A Product Inquiry Message is received when a user is asking for more information about a specific product.\nThese can be received as in two scenarios:\n1. When a customer replies to Single or Multi-Product Messages.\n2. 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": { "description": "The catalog ID.", "type": "string" }, "product_retailer_id": { "description": "The product SKU identifier.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageSystem": { "description": "When the message type is set to `system`, this field is included.\nThis 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": { "description": "Describes the system message event. Supported use cases are:\n- Phone number update: for when a user changes from an old number to a new number.\n- Identity update: for when a user identity has changed.", "type": "string" }, "new_wa_id": { "description": "**Added to Webhooks for phone number updates.**\n\nNew WhatsApp ID of the customer.", "type": "string" }, "type": { "description": "Supported types are:\n- `user_changed_number`: for a user changed number notification.\n- `user_identity_changed`: for user identity changed notification.", "type": "string" }, "user": { "description": "**Added to Webhooks for identity updates.**\n\nThe new WhatsApp user ID of the customer.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageText": { "description": "When the notification describes a text message, the text object provides the body of the text message.", "properties": { "body": { "description": "Message text.", "type": "string" } }, "type": "object" }, "WhatsappInboundMessageType": { "description": "WhatsApp inbound message type.\nSee 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" ], "type": "string" }, "WhatsappInboundMessageTypingResponse": { "description": "Successful response from the JSON typing-indicator endpoint.", "properties": { "success": { "description": "Always `true` in an HTTP 200 response.", "enum": [ true ], "example": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "WhatsappListFlowItem": { "description": "Represents a list item of WhatsApp Flows.", "properties": { "categories": { "description": "Flow categories.", "items": { "$ref": "#/components/schemas/WhatsappFlowCategory" }, "type": "array" }, "id": { "description": "Flow ID.", "example": "flow-1", "type": "string" }, "name": { "description": "Flow name.", "example": "My first flow", "type": "string" }, "status": { "$ref": "#/components/schemas/WhatsappFlowStatus" }, "validationErrors": { "description": "List of validation errors.", "items": { "$ref": "#/components/schemas/WhatsappFlowValidationError" }, "type": "array" } }, "type": "object" }, "WhatsappMedia": { "description": "Represents a WhatsApp media object that has been uploaded via the media upload API.", "properties": { "id": { "description": "Unique identifier for the uploaded media. This ID can be used in subsequent message requests.", "type": "string" } }, "type": "object" }, "WhatsappMessage": { "description": "WhatsApp outbound message object.", "properties": { "audio": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "bizType": { "description": "This can be either empty or one of `whatsapp`, or `verify`. Defaults to `whatsapp`.\n- `whatsapp`: Indicates that the message is sent via the **WhatsApp** product.\n- `verify`: Indicates that the message is sent via the **Verify** product.", "example": "whatsapp", "type": "string" }, "contacts": { "items": { "$ref": "#/components/schemas/WhatsappMessageContact" }, "type": "array" }, "context": { "$ref": "#/components/schemas/WhatsappMessageContext" }, "conversation": { "$ref": "#/components/schemas/WhatsappConversation", "description": "WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business.\nThis field is present after the message status changes to `sent`.\nSee also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing)." }, "createTime": { "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", "format": "date-time", "type": "string" }, "currency": { "description": "Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217).", "example": "USD", "type": "string" }, "customerProfile": { "$ref": "#/components/schemas/WhatsappProfile", "description": "The recipient's profile information, including WhatsApp username when available." }, "deliverTime": { "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", "format": "date-time", "type": "string" }, "document": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "errorCode": { "description": "Error code when the message status is `failed`.", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "errorMessage": { "description": "Error message when the message status is `failed`.", "type": "string" }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "from": { "description": "The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "id": { "description": "Unique ID of the message.", "type": "string" }, "image": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "interactive": { "$ref": "#/components/schemas/WhatsappMessageInteractive" }, "location": { "$ref": "#/components/schemas/WhatsappMessageLocation" }, "parentRecipientUserId": { "description": "The recipient's parent WhatsApp Business-scoped user ID.", "example": "US.ENT.1234", "type": "string" }, "pricingCategory": { "$ref": "#/components/schemas/WhatsappPricingCategory", "description": "The pricing category of the message.\n**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.\n- `PMP`: Per-message pricing applies.\n- `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.\n- `regular`: Indicates the message is billable.\n- `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.\n- `free_entry_point`: Indicates the message is free because it is part of a free-entry point conversation." }, "reaction": { "$ref": "#/components/schemas/WhatsappMessageReaction" }, "readTime": { "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", "format": "date-time", "type": "string" }, "recipient": { "description": "The recipient value submitted in the request when a BSUID or parent BSUID was used.", "example": "US.1234", "type": "string" }, "recipientUserId": { "description": "The recipient's WhatsApp Business-scoped user ID (BSUID).", "example": "US.1234", "type": "string" }, "regionCode": { "description": "The [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the recipient phone number.", "example": "US", "type": "string" }, "sendTime": { "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", "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/WhatsappMessageStatus" }, "sticker": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "template": { "$ref": "#/components/schemas/WhatsappMessageTemplate" }, "text": { "$ref": "#/components/schemas/WhatsappMessageText" }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "toParentUserId": { "description": "Alias of `parentRecipientUserId` kept for compatibility.", "example": "US.ENT.1234", "type": "string" }, "toUserId": { "description": "Alias of `recipientUserId` kept for compatibility.", "example": "US.1234", "type": "string" }, "totalPrice": { "description": "Total price of this message.\n**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, "format": "double", "type": "number" }, "type": { "$ref": "#/components/schemas/WhatsappMessageType" }, "updateTime": { "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", "format": "date-time", "type": "string" }, "verificationId": { "description": "The verification ID. Included only when `bizType` is `verify`.", "example": "VERIFICATION-ID", "type": "string" }, "video": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" }, "wamid": { "description": "The original message ID on WhatsApp's platform.", "example": "wamid.BgNODYxN...", "type": "string" }, "whatsappApiError": { "$ref": "#/components/schemas/WhatsappApiError" } }, "required": [ "id", "wabaId", "from" ], "type": "object" }, "WhatsappMessageContact": { "description": "When the message type filed is set to `contacts`, this object is included in the message object.", "properties": { "addresses": { "items": { "$ref": "#/components/schemas/WhatsappMessageContactAddress" }, "type": "array" }, "birthday": { "description": "`YYYY-MM-DD` formatted string.", "example": "2022-09-27", "type": "string" }, "emails": { "items": { "$ref": "#/components/schemas/WhatsappMessageContactEmail" }, "type": "array" }, "name": { "$ref": "#/components/schemas/WhatsappMessageContactName" }, "org": { "$ref": "#/components/schemas/WhatsappMessageContactOrg" }, "phones": { "description": "Contact phone number(s) formatted as a phone object.", "items": { "$ref": "#/components/schemas/WhatsappMessageContactPhone" }, "type": "array" }, "urls": { "description": "Contact URL(s) formatted as a urls object.", "items": { "$ref": "#/components/schemas/WhatsappMessageContactUrl" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "WhatsappMessageContactAddress": { "description": "Full contact address(es) formatted as an addresses object.", "properties": { "city": { "description": "City name.", "type": "string" }, "country": { "description": "Full country name.", "type": "string" }, "country_code": { "description": "Two-letter country abbreviation.", "type": "string" }, "state": { "description": "State abbreviation.", "type": "string" }, "street": { "description": "Street number and name.", "type": "string" }, "type": { "description": "Standard values are `HOME` and `WORK`.", "example": "WORK", "type": "string" }, "zip": { "description": "ZIP code.", "type": "string" } }, "type": "object" }, "WhatsappMessageContactEmail": { "description": "Contact email address(es) formatted as an emails object.", "properties": { "email": { "description": "Email address.", "type": "string" }, "type": { "description": "Standard values are `HOME` and `WORK`.", "example": "WORK", "type": "string" } }, "type": "object" }, "WhatsappMessageContactName": { "description": "Full contact name formatted as a name object.", "properties": { "first_name": { "description": "First name.", "type": "string" }, "formatted_name": { "description": "Full name, as it normally appears.", "type": "string" }, "last_name": { "description": "Last name.", "type": "string" }, "middle_name": { "description": "Middle name.", "type": "string" }, "prefix": { "description": "Name prefix.", "type": "string" }, "suffix": { "description": "Name suffix.", "type": "string" } }, "required": [ "formatted_name" ], "type": "object" }, "WhatsappMessageContactOrg": { "description": "Contact organization information formatted as an org object.", "properties": { "company": { "description": "Name of the contact's company.", "type": "string" }, "department": { "description": "Name of the contact's department.", "type": "string" }, "title": { "description": "Contact's business title.", "type": "string" } }, "type": "object" }, "WhatsappMessageContactPhone": { "properties": { "phone": { "description": "Automatically populated with the `wa_id` value as a formatted phone number.", "type": "string" }, "type": { "description": "Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`.", "type": "string" }, "wa_id": { "description": "WhatsApp ID.", "type": "string" } }, "type": "object" }, "WhatsappMessageContactUrl": { "properties": { "type": { "description": "Standard values are `HOME` and `WORK`.", "type": "string" }, "url": { "description": "URL.", "type": "string" } }, "type": "object" }, "WhatsappMessageContext": { "description": "Used to mention a specific message you are replying to. The reply can be any message type.", "properties": { "message_id": { "description": "Specifies the `wamid` of the message your are replying to. `wamid` is the original message ID on WhatsApp's platform.", "example": "wamid.BgNODYxN...", "type": "string" } }, "type": "object" }, "WhatsappMessageInteractive": { "description": "Use for `interactive` messages.", "properties": { "action": { "$ref": "#/components/schemas/WhatsappMessageInteractiveAction" }, "body": { "$ref": "#/components/schemas/WhatsappMessageInteractiveBody" }, "footer": { "$ref": "#/components/schemas/WhatsappMessageInteractiveFooter" }, "header": { "$ref": "#/components/schemas/WhatsappMessageInteractiveHeader" }, "type": { "description": "**Required.**\nThe type of interactive message you want to send.\n- `button`: Use for Reply Buttons.\n- `list`: Use for List Messages.\n- `cta_url`: Use for Call-To-Action (CTA) URL Button Messages.\n- `product`: Use for Single Product Messages.\n- `product_list`: Use for Multi-Product Messages.\n- `catalog_message`: Use for Catalog Messages.\n- `location_request_message`: Use for Location Request Messages.\n- `order_details`: Use for Order Details Messages.\n- `order_status`: Use for Order Status Messages.\n- `voice_call`: Use for Voice Call Messages.\n- `flow`: Use for Flow Messages.\n- `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" ], "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveAction": { "description": "**Required.**\nAction you want the user to perform after reading the `interactive` message.", "properties": { "button": { "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, "type": "string" }, "buttons": { "description": "Required for Reply Buttons. You can have up to 3 buttons.", "items": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionButton" }, "maxItems": 3, "type": "array" }, "cards": { "description": "Required for Carousel Messages.\nArray of card objects. Minimum of 2, maximum of 10.", "items": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionCard" }, "maxItems": 10, "type": "array" }, "catalog_id": { "description": "Required for Single Product Messages and Multi-Product Messages.\nUnique 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).", "type": "string" }, "name": { "description": "Action name.\nRequired for Call-To-Action (CTA) buttons.\n- `cta_url`: Use for Call-To-Action (CTA) URL buttons.\n- `send_location`: Use for Location Request buttons.\n- `flow`: Use for Flow buttons.\n- `review_and_pay`: Use for Order Details buttons.\n- `review_order`: Use for Order Status buttons.\n- `voice_call`: Use for Voice Call buttons.", "enum": [ "cta_url", "send_location", "flow", "review_and_pay", "review_order", "voice_call" ], "type": "string" }, "parameters": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionParameters" }, "product_retailer_id": { "description": "Required for Single Product Messages and Multi-Product Messages.\nUnique identifier of the product in a catalog.", "type": "string" }, "sections": { "description": "Required for List Messages and Multi-Product Messages.\nArray of section objects. Minimum of 1, maximum of 10.", "items": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionSection" }, "maxItems": 10, "minItems": 1, "type": "array" } }, "type": "object" }, "WhatsappMessageInteractiveActionButton": { "description": "A button object in `interactive` messages.", "properties": { "reply": { "properties": { "id": { "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, "type": "string" }, "title": { "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, "type": "string" } }, "type": "object" }, "type": { "description": "Only supported type is `reply` (for Reply Button).", "enum": [ "reply" ], "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionCard": { "description": "A card object in `interactive` messages. All cards must have the same structure.", "properties": { "action": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionCardAction" }, "body": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionCardBody" }, "card_index": { "description": "Card index. Unique index for each card (0-9).", "type": "number" }, "header": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionCardHeader" }, "type": { "description": "Must be \"cta_url\".", "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionCardAction": { "description": "A button object in `interactive` messages.\nCards must include either one URL button, or one or more quick-reply buttons. Button types and numbers must match across all cards (for example, if you define a card with 2 quick-reply buttons, all cards must define exactly 2 quick-reply buttons).", "properties": { "buttons": { "description": "Required when card action is quick reply button.", "items": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionCardActionButton" }, "type": "array" }, "name": { "description": "Required when card action is url button. Must be \"cta_url\".", "type": "string" }, "parameters": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionCardActionParameters" } }, "type": "object" }, "WhatsappMessageInteractiveActionCardActionButton": { "properties": { "quick_reply": { "properties": { "id": { "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, "type": "string" }, "title": { "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, "type": "string" } }, "type": "object" }, "type": { "description": "Must be \"quick_reply\".", "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionCardActionParameters": { "description": "Required when card action is url button. Only support `display_text` and `url`. Button display text Max 20 chars.", "properties": { "display_text": { "description": "Text of the CTA URL button.\nMaximum length: 20 bytes.", "example": "See Docs", "maxLength": 20, "type": "string" }, "url": { "description": "URL of the CTA URL button.", "example": "https://developers.facebook.com/docs/whatsapp", "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionCardBody": { "description": "Optional for card.", "properties": { "text": { "description": "Max 160 chars, and up to 2 line breaks.", "maxLength": 160, "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionCardHeader": { "properties": { "image": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "type": { "description": "**Required.**\nThe header type you would like to use.\n- `video`: Used for Reply Buttons.\n- `image`: Used for Reply Buttons.", "enum": [ "image", "video" ], "type": "string" }, "video": { "$ref": "#/components/schemas/WhatsappMessageMedia" } }, "type": "object" }, "WhatsappMessageInteractiveActionParameters": { "description": "Action parameters.\nRequired for Call-To-Action (CTA) buttons.", "properties": { "beneficiaries": { "description": "Required for `review_and_pay` buttons.\nAn array of beneficiaries for this order.\nA beneficiary is an intended recipient for shipping the physical goods in the order.\nBeneficiary information isn't shown to users but is needed for legal and compliance reasons.", "items": { "$ref": "#/components/schemas/WhatsappMessageOrderBeneficiary" }, "type": "array" }, "currency": { "description": "Required for `review_and_pay` buttons.\nThe currency for this order.\nCurrently the only supported value is `INR`.", "type": "string" }, "display_text": { "description": "Text of the CTA URL button.\nMaximum length: 20 bytes.", "example": "See Docs", "maxLength": 20, "type": "string" }, "flow_action": { "description": "Use for `flow` buttons.\nEither `navigate` or `data_exchange`. Defaults to `navigate`.", "example": "navigate", "type": "string" }, "flow_action_payload": { "description": "Required if `flow_action` is `navigate`. Should be omitted otherwise.", "properties": { "data": { "additionalProperties": { "type": "object" }, "description": "Optional input data for the first screen of the Flow. If provided, this must be a non-empty object.", "type": "object" }, "screen": { "description": "The ID of the screen displayed first. It needs to be an **entry** screen.", "type": "string" } }, "type": "object" }, "flow_cta": { "description": "Required for `flow` buttons.\nText on the CTA button. For example: \"Open flow!\". Maximum length: 20 characters.", "example": "Open flow!", "maxLength": 20, "type": "string" }, "flow_id": { "description": "Conditionally required for `flow` buttons. Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter.", "type": "string" }, "flow_message_version": { "description": "Use for `flow` buttons.\nValue must be \"3\".", "type": "string" }, "flow_name": { "description": "Conditionally required for `flow` buttons.\nThe 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.", "type": "string" }, "flow_token": { "description": "Use for `flow` buttons.\nFlow token that is generated by the business to serve as an identifier. Defaults to `unused`.", "type": "string" }, "order": { "$ref": "#/components/schemas/WhatsappMessageOrderInfo", "description": "Required for `review_and_pay` or `review_order` buttons.\n\nFor `review_and_pay` buttons, provides order `status`, `items`, `subtotal`, `tax`, etc.\n\nFor `review_order` buttons, provides only order `status` and `description`." }, "payment_settings": { "description": "Required for `review_and_pay` buttons.\nPayment settings for the order.", "items": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentSetting" }, "type": "array" }, "reference_id": { "description": "Required for `review_and_pay` buttons.\nUnique 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.\n\nThe `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": "string" }, "thumbnail_product_retailer_id": { "description": "Item SKU number. Labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce).\nThe thumbnail of this item will be used as the message's header image.", "type": "string" }, "total_amount": { "$ref": "#/components/schemas/WhatsappMessageOrderAmount", "description": "Required for `review_and_pay` buttons.\nThe total amount for this order." }, "type": { "description": "Required for `review_and_pay` buttons.\nThe type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`.", "type": "string" }, "url": { "description": "URL of the CTA URL button.", "example": "https://developers.facebook.com/docs/whatsapp", "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionSection": { "description": "WhatsApp Message Interactive Section Object.", "properties": { "product_items": { "description": "Required for Multi-Product Messages.\nArray of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.", "items": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionSectionProductItem" }, "maxItems": 30, "minItems": 1, "type": "array" }, "rows": { "description": "Contains a list of rows. You can have a total of 10 rows across your sections.\nEach 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.", "items": { "$ref": "#/components/schemas/WhatsappMessageInteractiveActionSectionRow" }, "maxItems": 10, "type": "array" }, "title": { "description": "**Required if the message has more than one section.**\nTitle of the section. Maximum length: 24 characters.", "maxLength": 24, "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionSectionProductItem": { "properties": { "product_retailer_id": { "description": "Required for Multi-Product Messages.\nUnique identifier of the product in a catalog.", "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveActionSectionRow": { "properties": { "description": { "description": "Row description content. Maximum length: 72 characters.", "maxLength": 72, "type": "string" }, "id": { "description": "Unique row ID. Maximum length: 200 characters.", "maxLength": 200, "type": "string" }, "title": { "description": "Row title content. Maximum length: 24 characters.", "maxLength": 24, "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveBody": { "description": "Optional for type `product`. Required for other message types.", "properties": { "text": { "description": "The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters.", "maxLength": 1024, "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveFooter": { "description": "Optional. An object with the footer of the message.", "properties": { "text": { "description": "The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters.", "maxLength": 60, "type": "string" } }, "type": "object" }, "WhatsappMessageInteractiveHeader": { "description": "Required for type `product_list`. Optional for other types.", "properties": { "document": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "image": { "$ref": "#/components/schemas/WhatsappMessageMedia" }, "text": { "description": "Text for the header. Formatting allows emojis, but not markdown.", "maxLength": 60, "type": "string" }, "type": { "description": "**Required.**\nThe header type you would like to use.\n- `text`: Used for List Messages, Reply Buttons, and Multi-Product Messages.\n- `video`: Used for Reply Buttons.\n- `image`: Used for Reply Buttons.\n- `document`: Used for Reply Buttons.", "enum": [ "text", "image", "video", "document" ], "type": "string" }, "video": { "$ref": "#/components/schemas/WhatsappMessageMedia" } }, "type": "object" }, "WhatsappMessageLocation": { "description": "Use for `location` messages.", "properties": { "address": { "description": "Address of the location. Only displayed if `name` is present.", "type": "string" }, "latitude": { "description": "Latitude of the location.", "format": "double", "type": "number" }, "longitude": { "description": "Longitude of the location.", "format": "double", "type": "number" }, "name": { "description": "Name of the location.", "type": "string" } }, "required": [ "latitude", "longitude" ], "type": "object" }, "WhatsappMessageMedia": { "description": "Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages.\nSee also [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).\n\n**Note**: Either `id` or `link` must be provided, but not both. These parameters are mutually exclusive.\n\nReference: [WhatsApp Cloud API Media Object](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#media-object)", "properties": { "caption": { "description": "Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages.", "type": "string" }, "filename": { "description": "Describes the filename for the specific document. Use only with `document` media.", "type": "string" }, "id": { "description": "**Use this when media is uploaded to WhatsApp servers.**\n\nProvide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/).\n\nNote: Either `id` or `link` must be provided. If both are provided, `id` takes precedence.", "type": "string" }, "link": { "description": "**Use this when sending media directly from your server.**\n\nThe protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.\n\nNote: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL.\n\nNote: Either `id` or `link` must be provided. If both are provided, `id` takes precedence and `link` will be ignored.", "type": "string" } }, "type": "object" }, "WhatsappMessageOrderAmount": { "description": "Represents the amount of an order.", "properties": { "description": { "description": "Use only for `tax`, `shipping`, or `discount`.\nDescription of the amount. Max character limit is 60 characters.", "maxLength": 60, "type": "string" }, "discount_program_name": { "description": "Use only for `discount`.\nText used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters.", "maxLength": 60, "type": "string" }, "offset": { "description": "Must be `100` for `INR`.", "example": 100, "format": "int32", "type": "integer" }, "value": { "description": "Positive integer representing the amount value multiplied by offset.\nFor example, ₹12.34 has value 1234.", "example": 1234, "format": "int32", "type": "integer" } }, "required": [ "offset", "value" ], "type": "object" }, "WhatsappMessageOrderBeneficiary": { "description": "A beneficiary is an intended recipient for shipping the physical goods in the order.\nBeneficiary information isn't shown to users but is needed for legal and compliance reasons.", "properties": { "address_line1": { "description": "Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters.", "maxLength": 100, "type": "string" }, "address_line2": { "description": "Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters.", "maxLength": 100, "type": "string" }, "city": { "description": "Name of the city.", "type": "string" }, "country": { "description": "Name of the country.\nCurrently the only supported value is `India`.", "type": "string" }, "name": { "description": "Name of the individual or business receiving the physical goods. Cannot exceed 200 characters.", "maxLength": 200, "type": "string" }, "postal_code": { "description": "6-digit zipcode of shipping address.", "maxLength": 6, "minLength": 6, "type": "string" }, "state": { "description": "Name of the state.", "type": "string" } }, "required": [ "name", "address_line1", "city", "state", "country", "postal_code" ], "type": "object" }, "WhatsappMessageOrderDetails": { "description": "Contains the order details when sending a template message with a `order_details` button.", "properties": { "currency": { "description": "The currency for this order.\nCurrently the only supported value is `INR`.", "type": "string" }, "order": { "$ref": "#/components/schemas/WhatsappMessageOrderInfo", "description": "Provides order `status`, `items`, `subtotal`, `tax`, etc." }, "payment_settings": { "description": "Payment settings for the order.", "items": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentSetting" }, "type": "array" }, "reference_id": { "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.\n\nThe `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": "string" }, "total_amount": { "$ref": "#/components/schemas/WhatsappMessageOrderAmount", "description": "The total amount of the order." }, "type": { "description": "The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`.", "type": "string" } }, "required": [ "currency", "order", "reference_id", "total_amount", "type", "payment_settings" ], "type": "object" }, "WhatsappMessageOrderExpiration": { "description": "Expiration for this order.", "properties": { "description": { "description": "Text explanation for expiration.", "maxLength": 120, "type": "string" }, "timestamp": { "description": "A string of UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds.", "example": "1727438564", "type": "string" } }, "required": [ "timestamp" ], "type": "object" }, "WhatsappMessageOrderInfo": { "description": "Order info.", "properties": { "catalog_id": { "description": "Unique identifier of the Facebook catalog being used by the business.\nIf you do not provide this field, you must provide the following fields inside the items object: `country_of_origin`, `importer_name`, and `importer_address`.", "type": "string" }, "description": { "description": "**Optional.**\nText for sharing status related information. Could be useful while sending cancellation. Max character limit is 120 characters.", "maxLength": 120, "type": "string" }, "discount": { "$ref": "#/components/schemas/WhatsappMessageOrderAmount", "description": "The discount amount for this order." }, "expiration": { "$ref": "#/components/schemas/WhatsappMessageOrderExpiration" }, "items": { "description": "Array of items in the order.", "items": { "$ref": "#/components/schemas/WhatsappMessageOrderItem" }, "type": "array" }, "shipping": { "$ref": "#/components/schemas/WhatsappMessageOrderAmount", "description": "The shipping cost of the order." }, "status": { "$ref": "#/components/schemas/WhatsappMessageOrderStatusEnum" }, "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." }, "type": { "description": "Only supported value is `quick_pay`.\nWhen this field is passed in we hide the \"Review and Pay\" button and only show the \"Pay Now\" button in the order details bubble.", "type": "string" } }, "type": "object" }, "WhatsappMessageOrderItem": { "properties": { "amount": { "$ref": "#/components/schemas/WhatsappMessageOrderAmount", "description": "The price per item." }, "country_of_origin": { "description": "Required if `catalog_id` is not present.\nThe country of origin of the product.", "type": "string" }, "image": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "Custom image for the item to be displayed to the user." }, "importer_address": { "description": "Required if `catalog_id` is not present.\nAddress of importer company.", "type": "string" }, "importer_name": { "description": "Required if `catalog_id` is not present.\nName of the importer company.", "type": "string" }, "name": { "description": "The item's name to be displayed to the user. Cannot exceed 60 characters.", "maxLength": 60, "type": "string" }, "quantity": { "description": "The number of items in the order.", "format": "int32", "type": "integer" }, "retailer_id": { "description": "Content ID for an item in the order from your catalog.", "type": "string" }, "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." } }, "required": [ "name", "amount", "quantity" ], "type": "object" }, "WhatsappMessageOrderPaymentGateway": { "description": "An object that describes payment account information.", "properties": { "billdesk": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk" }, "configuration_name": { "description": "The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters.\nThis value must match with a payment configuration set up on the WhatsApp Business Manager.", "maxLength": 60, "type": "string" }, "payu": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayPayu" }, "razorpay": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay" }, "type": { "description": "Payment type.\nMust 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" ], "type": "string" }, "zaakpay": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay" } }, "required": [ "type", "configuration_name" ], "type": "object" }, "WhatsappMessageOrderPaymentSetting": { "description": "Payment settings for the order.", "properties": { "payment_gateway": { "$ref": "#/components/schemas/WhatsappMessageOrderPaymentGateway" }, "type": { "description": "Must be set to `payment_gateway`.", "example": "payment_gateway", "type": "string" } }, "required": [ "type", "payment_gateway" ], "type": "object" }, "WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk": { "description": "Additional info for BillDesk.\nUser-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" } }, "type": "object" }, "WhatsappMessageOrderPaymentSettingPaymentGatewayPayu": { "description": "Additional info for PayU.\nUser-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" } }, "type": "object" }, "WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay": { "description": "Additional info for Razorpay.", "properties": { "notes": { "additionalProperties": { "type": "string" }, "description": "The object can be key value pairs with maximum 15 keys and each value limits to 256 characters.", "type": "object" }, "receipt": { "description": "Receipt number that corresponds to this order, set for your internal reference.\nMaximum length of 40 characters supported with minimum length greater than 0 characters.", "type": "string" } }, "type": "object" }, "WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay": { "description": "Additional info for Zaakpay.\nUser-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" } }, "type": "object" }, "WhatsappMessageOrderStatus": { "properties": { "order": { "$ref": "#/components/schemas/WhatsappMessageOrderInfo", "description": "Provides only `status` and `description` of this order for `order_status` messages." }, "reference_id": { "description": "Unique identifier for the order provided by the business.", "type": "string" } }, "type": "object" }, "WhatsappMessageOrderStatusEnum": { "description": "Only supported value in the `order_details` message is `pending`.\nIn an `order_status` message, `status` can be: `pending`, `processing`, `partially_shipped`, `shipped`, `completed`, or `canceled`.", "enum": [ "pending", "processing", "partially_shipped", "shipped", "completed", "canceled" ], "type": "string" }, "WhatsappMessageReaction": { "description": "When a user reacts to messages with an emoji, the message type is set to `reaction`, and this field is included.", "properties": { "emoji": { "description": "**Required** when you send a `reaction` message. Set it to `\"\"` if you want to remove the emoji.\n**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.", "type": "string" }, "message_id": { "description": "Specifies the `wamid` of the message received that contained the reaction.", "example": "wamid.BgNODYxN...", "type": "string" } }, "required": [ "message_id" ], "type": "object" }, "WhatsappMessageSendRequest": { "description": "Provide exactly one of `to` or `recipient`. If both are provided, `to` takes precedence and `recipient` is ignored.", "properties": { "audio": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "Required when `type` is `audio`." }, "category": { "description": "**Optional.**\nIndicates the category of the message to be sent with Direct Send. Supported values are `utility` and `authentication`.\n\nUse `utility` for business-initiated utility messages. Messages sent with `utility` are charged at utility rates.\n\nUse `authentication` for business-initiated authentication messages. Messages sent with `authentication` are charged at authentication rates. Authentication Direct Send only supports `text` messages.", "enum": [ "utility", "authentication" ], "example": "utility", "type": "string" }, "contacts": { "description": "Required when `type` is `contacts`.", "items": { "$ref": "#/components/schemas/WhatsappMessageContact" }, "type": "array" }, "context": { "$ref": "#/components/schemas/WhatsappMessageContext" }, "customerProfile": { "$ref": "#/components/schemas/WhatsappProfile", "description": "The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios." }, "document": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "Required when `type` is `document`." }, "externalId": { "description": "A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.", "type": "string" }, "filterBlocked": { "description": "**Optional.**\nIf set to `true`, the message will not be sent to users in your block list. Defaults to `false`.\n\nOnly 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`.\n\nNot applicable to `POST /v2/whatsapp/messages/sendDirectly`.", "type": "boolean" }, "filterUnsubscribed": { "description": "**Optional.**\nIf set to `true`, the message will not be sent to users who have unsubscribed from your account. Defaults to `false`.\n\nOnly use for `POST /v2/whatsapp/messages`. If the user has unsubscribed, we will push webhook notifications with `whatsappMessage.errorCode` set to `RECIPIENT_UNSUBSCRIBED`.\n\nNot applicable to `POST /v2/whatsapp/messages/sendDirectly`.", "type": "boolean" }, "from": { "description": "The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "image": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "Required when `type` is `image`." }, "interactive": { "$ref": "#/components/schemas/WhatsappMessageInteractive", "description": "Required when `type` is `interactive`." }, "location": { "$ref": "#/components/schemas/WhatsappMessageLocation", "description": "Required when `type` is `location`." }, "reaction": { "$ref": "#/components/schemas/WhatsappMessageReaction", "description": "Required when `type` is `reaction`." }, "recipient": { "description": "The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when `to` is not provided.", "example": "US.1234", "type": "string" }, "sticker": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "Required when `type` is sticker." }, "template": { "$ref": "#/components/schemas/WhatsappMessageTemplate", "description": "Required when `type` is `template`." }, "text": { "$ref": "#/components/schemas/WhatsappMessageText", "description": "Required when `type` is `text`." }, "to": { "description": "The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. Required when `recipient` is not provided.", "example": "+16315551111", "type": "string" }, "ttlSeconds": { "description": "**Optional.**\nMessage time-to-live in seconds for Direct Send `utility` or `authentication` messages.\n\nThe supported range is 30 seconds to 43200 seconds (12 hours). If omitted, the default Direct Send TTL is used.", "example": 600, "maximum": 43200, "minimum": 30, "type": "integer" }, "type": { "$ref": "#/components/schemas/WhatsappMessageType" }, "useDirectSend": { "default": false, "description": "**Optional.**\nWhether to send the message through Direct Send. Defaults to `false`.\n\nSet this to `true` to send the message through Direct Send when the sender WABA is enabled for Direct Send.\n\nFor template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are:\n\n- Text messages\n- Interactive Call-to-Action URL button messages\n- Interactive reply button messages", "type": "boolean" }, "video": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "Required when `type` is `video`." } }, "required": [ "from", "type" ], "type": "object" }, "WhatsappMessageStatus": { "description": "WhatsApp message status. One of `accepted`, `failed`, `sent`, `delivered`, `read`.\n- `accepted`: The messaging request is accepted by our system.\n- `failed`: A message sent by your business failed to send.\n- `sent`: A message sent by your business is in transit within WhatsApp's systems.\n- `delivered`: A message sent by your business was delivered to the user's device.\n- `read`: A message sent by your business was read by the user.", "enum": [ "accepted", "failed", "sent", "delivered", "read" ], "type": "string" }, "WhatsappMessageTemplate": { "description": "Use for sending a WhatsApp `template` message.", "properties": { "components": { "description": "**Required when the specified template contains variables or media.**\nArray of component objects containing the parameters of the message.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponent" }, "type": "array" }, "language": { "description": "Contains a language object. Specifies the language the template may be rendered in.", "properties": { "code": { "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", "type": "string" }, "policy": { "description": "The language policy the message should follow.\nDefault (and only supported option): `deterministic`, which means that WhatsApp delivers the message template in exactly the language and locale asked for.", "example": "deterministic", "type": "string" } }, "required": [ "code" ], "type": "object" }, "name": { "description": "Name of the template.", "example": "sample_whatsapp_template", "type": "string" } }, "required": [ "name", "language" ], "type": "object" }, "WhatsappMessageTemplateComponent": { "description": "Component object containing the parameters of the message.", "properties": { "cards": { "description": "Use for `carousel` components. Provides card components containing the parameters of the message.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentCard" }, "type": "array" }, "index": { "description": "**Required when `type` = `button`. Not used for the other types.**\nIndicates order in which button should appear, if the template uses multiple buttons.\nButtons 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.", "format": "int32", "maximum": 9, "minimum": 0, "type": "integer" }, "parameters": { "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`).**\nArray of parameter objects with the content of the message.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameter" }, "type": "array" }, "sub_type": { "description": "**Required when type is `button`.**\nType of button.\n- `quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message.\n- `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.\n- `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.\n- `catalog`: Refers to a previously created catalog button that allows the customer to view your product catalog.\n- `mpm`: Refers to a previously created MPM (multi-product message) button that allows the customer to browser products and sections.\n- `flow`: Refers to a previously created flow button that allows the customer to interact with a [flow](https://developers.facebook.com/docs/whatsapp/flows).\n- `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" ], "type": "string" }, "type": { "description": "Component type.", "enum": [ "header", "body", "button", "limited_time_offer", "carousel", "order_status" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "WhatsappMessageTemplateComponentCard": { "description": "Card component containing the parameters of the message.", "properties": { "card_index": { "description": "**Required.**\nZero-indexed order in which card appears within the card carousel. 0 indicates first card, 1 indicates second card, etc.", "format": "int32", "maximum": 9, "minimum": 0, "type": "integer" }, "components": { "description": "Card component.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentCardComponent" }, "type": "array" } }, "type": "object" }, "WhatsappMessageTemplateComponentCardComponent": { "description": "Card component object containing the parameters of the message.", "properties": { "index": { "description": "**Required when `type` = `button`. Not used for the other types.**\nIndicates order in which button should appear, if the template uses multiple buttons.\nButtons 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.", "format": "int32", "maximum": 9, "minimum": 0, "type": "integer" }, "parameters": { "description": "**Required when `type` = `button`, or there are variables in the corresponding template component, or the card component `HEADER` format is media (`IMAGE`, `VIDEO`).**\nArray of parameter objects with the content of the message.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameter" }, "type": "array" }, "sub_type": { "description": "**Required when type is `button`.**\nType of button.\n- `quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message.\n- `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" ], "type": "string" }, "type": { "description": "Component type.", "enum": [ "header", "body", "button" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "WhatsappMessageTemplateComponentParameter": { "properties": { "action": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameterAction" }, "coupon_code": { "description": "**Required when `type` = `coupon_code`.**\nThe coupon code to be copied when the customer taps the button.", "type": "string" }, "document": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "**Required when the template `HEADER` format is `DOCUMENT`.**" }, "gif": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "**Required when the template `HEADER` format is `GIF`.**" }, "group_id": { "description": "**Required when `type` = `group_id`.**\nWhatsApp group ID used by group invite link templates.", "example": "120363345678901234@g.us", "type": "string" }, "image": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "**Required when the template `HEADER` format is `IMAGE`.**" }, "limited_time_offer": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameterLimitedTimeOffer" }, "location": { "$ref": "#/components/schemas/WhatsappMessageLocation", "description": "**Required when `type` = `location`.**" }, "order_status": { "$ref": "#/components/schemas/WhatsappMessageOrderStatus" }, "payload": { "description": "Required for `quick_reply` buttons.\nDeveloper-defined payload that is returned when the button is clicked in addition to the display text on the button.", "type": "string" }, "text": { "description": "**Required when `type` = `text`.**\nThe message's text. For the header component, the character limit is 60 characters. For the body component, the character limit is 1024 characters.\nFor url buttons, it indicates the developer-provided suffix that is appended to the predefined prefix URL in the template.", "type": "string" }, "type": { "description": "**Required.**\nComponent parameter type.\n- `text`: Used when the template component type is `BODY`, or the `HEADER` component format is `TEXT`.\n- `image`: Used when the template `HEADER` component is `IMAGE`.\n- `gif`: Used when the template `HEADER` component is `GIF`.\n- `video`: Used when the template `HEADER` component is `VIDEO`.\n- `document`: Used when the template `HEADER` component is `DOCUMENT`.\n- `payload`: Used when the template component button type is `QUICK_REPLY`.\n- `coupon_code`: Used when the template component button type is `COPY_CODE`.\n- `limited_time_offer`: Used when the template component type is `LIMITED_TIME_OFFER`.\n- `action`: Used when the template component button type is `CATALOG`, `MPM`, `FLOW`, or `ORDER_DETAILS`.\n- `order_status`: Used when the template subcategory is `ORDER_STATUS`.\n- `location`: Used when the template `HEADER` component is `LOCATION`.\n- `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" ], "type": "string" }, "video": { "$ref": "#/components/schemas/WhatsappMessageMedia", "description": "**Required when the template `HEADER` format is `VIDEO`.**" } }, "type": "object" }, "WhatsappMessageTemplateComponentParameterAction": { "description": "Required if template uses catalog or MPM (multi-product message) buttons.", "properties": { "flow_action_data": { "additionalProperties": { "type": "object" }, "description": "Use for `FLOW` buttons.\nJSON object with the data payload for the first screen.", "type": "object" }, "flow_token": { "description": "Use for `FLOW` buttons.\nFlow token that is generated by the business to serve as an identifier. Defaults to `unused`.", "type": "string" }, "order_details": { "$ref": "#/components/schemas/WhatsappMessageOrderDetails", "description": "Required for `order_details` buttons." }, "sections": { "description": "Use for MPM templates.\nProduct sections. You can define up to 10 sections.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameterActionSection" }, "maxItems": 10, "type": "array" }, "thumbnail_product_retailer_id": { "description": "**Optional.**\nUse for catalog and MPM template messages.\nItem SKU number. Labeled as Content ID in the Commerce Manager.\nThe thumbnail of this item will be used as the message's header image.\nIf the `parameters` object is omitted, the product image of the first item in your catalog will be used.", "example": "2lc20305pt", "type": "string" } }, "type": "object" }, "WhatsappMessageTemplateComponentParameterActionSection": { "properties": { "product_items": { "description": "Array of product SKU numbers. There is a minimum of 1 product per section and a maximum of 30 products across all sections.", "items": { "$ref": "#/components/schemas/WhatsappMessageTemplateComponentParameterActionSectionProductItem" }, "maxItems": 30, "minItems": 1, "type": "array" }, "title": { "description": "Section title text.\nMaximum 24 characters. Markdown is not supported.", "maxLength": 24, "type": "string" } }, "type": "object" }, "WhatsappMessageTemplateComponentParameterActionSectionProductItem": { "properties": { "product_retailer_id": { "description": "SKU number of the item you want to appear in the section.\nSKU numbers are labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce).", "type": "string" } }, "type": "object" }, "WhatsappMessageTemplateComponentParameterLimitedTimeOffer": { "description": "Required if template uses offer expiration details.", "properties": { "expiration_time_ms": { "description": "**Required.**\nOffer code expiration time as a UNIX timestamp in milliseconds.", "example": "1698562800000", "format": "int64", "type": "integer" } }, "type": "object" }, "WhatsappMessageText": { "description": "WhatsApp Message Text Object.", "properties": { "body": { "description": "Required for text messages.\nThe text of the text message which can contain URLs which begin with http:// or https:// and formatting. See available formatting options here.\nIf 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.\nMaximum length: 4096 characters.", "maxLength": 4096, "type": "string" }, "preview_url": { "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.\nThe 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.\nURL previews are only rendered after one of the following has happened:\n- The business has sent a message template to the user.\n- The user initiates a conversation with a \"click to chat\" link.\n- The user adds the business phone number to their address book and initiates a conversation.\nDefault: `false`.", "type": "boolean" } }, "required": [ "body" ], "type": "object" }, "WhatsappMessageType": { "description": "WhatsApp outbound message type.\nSee 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" ], "type": "string" }, "WhatsappPayment": { "description": "Represents a payment object.\nBusinesses receive updates via webhooks when the status of the user-initiated transaction changes.", "properties": { "referenceId": { "description": "Unique identifier for the payment provided by the business.\nIt 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.", "type": "string" }, "status": { "$ref": "#/components/schemas/WhatsappPaymentStatus" }, "transactions": { "description": "Contains the latest transaction attempt for this payment.", "items": { "$ref": "#/components/schemas/WhatsappPaymentTransaction" }, "type": "array" }, "wabaId": { "description": "WhatsApp Business Account ID.", "type": "string" } }, "required": [ "wabaId", "referenceId", "status" ], "type": "object" }, "WhatsappPaymentStatus": { "description": "Status of this payment.\n- `captured`: Indicates the payment is successfully completed.\n- `pending`: Indicates the user attempted but yet to receive success transactions signal.", "enum": [ "captured", "pending" ], "type": "string" }, "WhatsappPaymentTransaction": { "description": "Represents a transaction attempt for a payment.", "properties": { "amount": { "$ref": "#/components/schemas/WhatsappMessageOrderAmount", "description": "Total amount that user has paid." }, "createdTimestamp": { "description": "Time when transaction was created in epoch milliseconds.", "format": "int64", "type": "integer" }, "currency": { "description": "The currency for this payment.\nCurrently the only supported value is `INR`.", "type": "string" }, "error": { "description": "The payment error details might not be available for all payments attempts.", "properties": { "code": { "description": "Describes the payment failure reason that generated by payment gateway and Meta transmits this to partners.", "type": "string" }, "reason": { "description": "Describes the payment failure reason in plain text that is generated by payment gateway and Meta transmits this to partners.", "type": "string" } }, "required": [ "code", "reason" ], "type": "object" }, "id": { "description": "Transaction ID.", "type": "string" }, "methodType": { "description": "Describes the type of payment method used by consumer to pay for the order. Can be one of `upi`, `card`, `wallet`, or `netbanking`.\nThe payment method information might not be available for failed payments.", "example": "upi", "type": "string" }, "status": { "description": "The status of the transaction. One of `pending`, `success` or `failed`.", "enum": [ "pending", "success", "failed" ], "type": "string" }, "type": { "description": "The payment type for this transactions. One of `billdesk`, `razorpay`, `payu`, or `zaakpay`.", "enum": [ "billdesk", "razorpay", "payu", "zaakpay" ], "type": "string" }, "updatedTimestamp": { "description": "Time when transaction was last updated in epoch milliseconds.", "format": "int64", "type": "integer" } }, "required": [ "id", "type", "status", "createdTimestamp", "updatedTimestamp", "amount", "currency" ], "type": "object" }, "WhatsappPhoneNameUpdateRequest": { "description": "WhatsApp Phone Number Display Name", "properties": { "newName": { "description": "The new name you want to modify", "example": "newName", "maxLength": 150, "minLength": 3, "type": "string" } }, "type": "object" }, "WhatsappPhoneNameUpdateResponse": { "description": "WhatsApp Phone Number Display Name Modify Result", "properties": { "nameStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberNameStatus" }, "newName": { "description": "The new name you want to modify", "example": "newName", "maxLength": 150, "minLength": 3, "type": "string" }, "newNameStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberNameStatus" }, "verifiedName": { "description": "The verified name", "example": "verifiedName", "maxLength": 150, "minLength": 3, "type": "string" } }, "type": "object" }, "WhatsappPhoneNumber": { "description": "See [WhatsApp Business Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers)", "properties": { "businessUsername": { "description": "Active Business Username for this phone number. The value is a plain username without `@`.", "example": "acme.support", "type": "string" }, "businessUsernameStatus": { "$ref": "#/components/schemas/WhatsappBusinessUsernameStatus" }, "businessUsernameUpdatedAt": { "description": "The time when the Business Username state was last updated.", "example": "2026-05-26T12:00:00.000Z", "format": "date-time", "type": "string" }, "codeVerificationStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberCodeVerificationStatus" }, "decision": { "$ref": "#/components/schemas/WhatsappReviewDecision", "description": "Review decision made on this phone number. One of `APPROVED` or `REJECTED` or `DEFERRED`." }, "displayPhoneNumber": { "description": "Display phone number.", "example": "+1 631-555-1111", "type": "string" }, "id": { "description": "Phone number ID.", "example": "1234567890123456", "type": "string" }, "isOfficialBusinessAccount": { "description": "Whether this phone number is an official business account or not.\nAn 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.", "type": "boolean" }, "messagingLimit": { "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).\n- `TIER_NOT_SET`: Unknown limit.\n- `TIER_50`: 50 business-initiated conversations in a rolling 24-hour period.\n- `TIER_250`: 250 business-initiated conversations in a rolling 24-hour period.\n- `TIER_1K`: 1K business-initiated conversations with unique customers in a rolling 24-hour period.\n- `TIER_10K`: 10K business-initiated conversations with unique customers in a rolling 24-hour period.\n- `TIER_100K`: 100K business-initiated conversations with unique customers in a rolling 24-hour period.\n- `TIER_UNLIMITED`: An unlimited number of business-initiated conversations in a rolling 24-hour period.", "example": "TIER_1K", "type": "string" }, "nameStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberNameStatus" }, "newName": { "description": "The modified name", "example": "John's Cake", "type": "string" }, "newNameStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberNameStatus", "description": "The review status of the new display name request.\nSee also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-)." }, "phoneNumber": { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "qualityRating": { "$ref": "#/components/schemas/WhatsappPhoneNumberQualityRating" }, "qualityUpdateEvent": { "$ref": "#/components/schemas/WhatsappPhoneNumberQualityUpdateEventEnum" }, "rejectionReason": { "description": "Rejection reason.", "type": "string" }, "requestedBusinessUsername": { "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", "type": "string" }, "requestedVerifiedName": { "description": "Last requested verified name.", "type": "string" }, "status": { "$ref": "#/components/schemas/WhatsappPhoneNumberStatus" }, "throughputLevel": { "description": "Current Meta throughput level of the WhatsApp phone number.\n- `STANDARD`: Default Cloud API throughput level, currently up to 80 messages per second.\n- `HIGH`: Upgraded Cloud API throughput level, currently up to 1,000 messages per second, subject to Meta's current Cloud API throughput rules.\n- `NOT_APPLICABLE`: Throughput level is not applicable to this phone number.", "enum": [ "STANDARD", "HIGH", "NOT_APPLICABLE" ], "example": "HIGH", "type": "string" }, "updateEvent": { "description": "Account update event that triggered this phone number status change.", "enum": [ "ACCOUNT_RECONNECTED", "ACCOUNT_OFFBOARDED" ], "example": "ACCOUNT_OFFBOARDED", "type": "string" }, "verifiedName": { "description": "Verified name.", "example": "John's Cake Shop", "type": "string" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" }, "whatsappBusinessManagerMessagingLimit": { "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).\n- `TIER_NOT_SET`: The business phone number has not been used to send a message yet.\n- `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period.\n- `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period.\n- `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period.\n- `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period.\n- `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period.\n- `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations.", "example": "TIER_2K", "type": "string" }, "ycloudName": { "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", "readOnly": true, "type": "string" } }, "type": "object" }, "WhatsappPhoneNumberCodeVerificationStatus": { "description": "To see if a phone number has been verified via OTP (one-time password).", "enum": [ "VERIFIED", "NOT_VERIFIED", "EXPIRED" ], "type": "string" }, "WhatsappPhoneNumberNameStatus": { "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-).\n- `APPROVED`: The name has been approved. You can download your certificate now.\n- `AVAILABLE_WITHOUT_REVIEW`: The certificate for the phone is available and display name is ready to use without review.\n- `DECLINED`: The name has not been approved. You cannot download your certificate.\n- `EXPIRED`: Your certificate has expire and can no longer be downloaded.\n- `PENDING_REVIEW`: Your name request is under review. You cannot download your certificate.\n- `NONE`: No certificate is available.", "enum": [ "APPROVED", "AVAILABLE_WITHOUT_REVIEW", "DECLINED", "EXPIRED", "PENDING_REVIEW", "NONE" ], "type": "string" }, "WhatsappPhoneNumberPage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of WhatsApp phone numbers.", "properties": { "items": { "description": "An array containing WhatsApp phone number objects.", "items": { "$ref": "#/components/schemas/WhatsappPhoneNumber" }, "type": "array" } }, "type": "object" }, "WhatsappPhoneNumberProfile": { "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": { "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", "type": "string" }, "address": { "description": "Address of the business. Character limit 256.", "example": "ADDRESS", "maxLength": 256, "type": "string" }, "description": { "description": "Description of the business. Character limit 512.", "example": "DESCRIPTION", "maxLength": 512, "type": "string" }, "email": { "description": "The contact email address (in valid email format) of the business. Character limit 128.", "example": "tom@example.com", "maxLength": 128, "type": "string" }, "nameStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberNameStatus" }, "newName": { "description": "The modified name", "example": "John's Cake", "type": "string" }, "newNameStatus": { "$ref": "#/components/schemas/WhatsappPhoneNumberNameStatus" }, "profilePictureUrl": { "description": "URL of the profile picture used to upload to Meta.", "example": "https://URL", "type": "string" }, "verifiedName": { "description": "The verified name", "example": "verifiedName", "type": "string" }, "vertical": { "$ref": "#/components/schemas/WhatsappPhoneNumberProfileVertical" }, "websites": { "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.\nThere is a maximum of 2 websites with a maximum of 255 characters each.", "items": { "example": "https://WEBSITE-1", "maxLength": 255, "type": "string" }, "maxItems": 2, "type": "array" }, "ycloudName": { "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", "readOnly": true, "type": "string" } }, "type": "object" }, "WhatsappPhoneNumberProfileUpdateRequest": { "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": { "description": "The business's **About** text. This text appears in the business's profile, beneath its profile image, phone number, and contact buttons.\n- String cannot be empty.\n- Strings must be between 1 and 139 characters.\n- Rendered emojis are supported however their unicode values are not. Emoji unicode values must be Java- or JavaScript-escape encoded.\n- Hyperlinks can be included but will not render as clickable links.\n- Markdown is not supported.", "example": "ABOUT", "maxLength": 139, "minLength": 1, "type": "string" }, "address": { "description": "Address of the business. Character limit 256.", "example": "ADDRESS", "maxLength": 256, "type": "string" }, "description": { "description": "Description of the business. Character limit 512.", "example": "DESCRIPTION", "maxLength": 512, "type": "string" }, "email": { "description": "The contact email address (in valid email format) of the business. Character limit 128.", "example": "tom@example.com", "maxLength": 128, "type": "string" }, "profilePictureUrl": { "description": "URL of the profile picture that was uploaded to Meta.", "example": "https://PICTURE-URL", "type": "string" }, "vertical": { "$ref": "#/components/schemas/WhatsappPhoneNumberProfileVertical" }, "websites": { "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.\nThere is a maximum of 2 websites with a maximum of 255 characters each.", "items": { "example": "https://WEBSITE-1", "maxLength": 255, "type": "string" }, "maxItems": 2, "type": "array" } }, "type": "object" }, "WhatsappPhoneNumberProfileVertical": { "description": "Industry of the WhatsApp phone number business profile. This can be either an empty string or one of the accepted values.", "enum": [ "OTHER", "AUTO", "BEAUTY", "APPAREL", "EDU", "ENTERTAIN", "EVENT_PLAN", "FINANCE", "GROCERY", "GOVT", "HOTEL", "HEALTH", "NONPROFIT", "PROF_SERVICES", "RETAIL", "TRAVEL", "RESTAURANT" ], "example": "OTHER", "type": "string" }, "WhatsappPhoneNumberQualityRating": { "description": "Quality rating. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001).\n- `GREEN`: High quality.\n- `YELLOW`: Medium quality.\n- `RED`: Low quality.\n- `UNKNOWN`: Unknown quality.", "enum": [ "GREEN", "YELLOW", "RED", "UNKNOWN" ], "type": "string" }, "WhatsappPhoneNumberQualityUpdateEventEnum": { "description": "Indicates the update event type of WhatsApp phone number quality when a notification is sent to you.\n- `ONBOARDING`: Typically when the messaging limit changes from `TIER_NOT_SET` to another tier.\n- `UPGRADE`: Messaging limit tier upgraded.\n- `DOWNGRADE`: Messaging limit tier downgraded.\n- `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.\n- `UNFLAGGED`: Phone number status changes from `FLAGGED` to `CONNECTED`.", "enum": [ "ONBOARDING", "UPGRADE", "DOWNGRADE", "FLAGGED", "UNFLAGGED" ], "type": "string" }, "WhatsappPhoneNumberSettings": { "description": "WhatsApp business phone number settings.", "properties": { "calling": { "description": "Calling feature settings for the phone number.", "properties": { "iconVisibility": { "description": "Calling icon display configuration:\n- `DEFAULT`: Show icon by default\n- `DISABLE_ALL`: Hide all calling icons", "enum": [ "DEFAULT", "DISABLE_ALL" ], "example": "DEFAULT", "type": "string" }, "id": { "description": "Phone number ID.", "example": "19213232132", "type": "string" }, "status": { "description": "Calling feature status:\n- `ENABLED`: Calling feature is enabled\n- `DISABLED`: Calling feature is disabled", "enum": [ "ENABLED", "DISABLED" ], "example": "ENABLED", "type": "string" } }, "type": "object" }, "capture": { "$ref": "#/components/schemas/CallingCaptureSettings" } }, "type": "object" }, "WhatsappPhoneNumberStatus": { "description": "The status of a WhatsApp business phone number.\n- `PENDING`: Pending. Phone number is newly added. Verify and register this phone number so it can be connected to your account.\n- `UNVERIFIED`: Unverified. Verify this phone number to start sending messages.\n- `MANUAL_REVIEW`: Being reviewed. Phone number is currently being reviewed for connection to your account.\n- `DISCONNECTED`: Offline. Phone number is currently not reachable by WhatsApp servers.\n- `CONNECTED`: Connected. Phone number is associated with this account and working properly.\n- `FLAGGED`: Flagged. This phone number has been flagged due to low quality messages.\n- `WARNED`: Warned. A warning has been issued for this number, potentially due to spam reports.\n- `RATE_LIMITED`: Rate limited. The number of messages you can send from this phone number may be restricted.\n- `BANNED`: Banned. Phone number cannot be used with a WhatsApp account.\n- `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.\n- `BLOCKED`: Message limit reached. The limit has been reached for this 24-hour period.\n- `MIGRATED`: Transferred. This phone number has been transferred to another WhatsApp Business account.\n- `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" ], "type": "string" }, "WhatsappPricingCategory": { "description": "WhatsApp pricing category.\n- `referral_conversion`: Indicates a [free entry point conversation](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations).\n- `authentication`: Indicates the conversation was billed at authentication rate.\n- `authentication_international`: Indicates the conversation was conversation was billed at the [authentication-international rate](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates).\n- `marketing`: Indicates the conversation was billed at authentication rate.\n- `marketing_lite`: Indicates the conversation was billed at marketing-lite rate.\n- `utility`: Indicates the conversation was billed at utility rate.\n- `service`: Indicates the conversation was billed at service rate.\n\nSee also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing).", "enum": [ "referral_conversion", "authentication", "authentication_international", "marketing", "marketing_lite", "utility", "service" ], "type": "string" }, "WhatsappPricingModel": { "description": "WhatsApp pricing model.\n- `PMP`: Per-message pricing applies.\n- `CBP`: Conversation-based pricing applies.", "enum": [ "PMP", "CBP" ], "type": "string" }, "WhatsappPricingType": { "description": "WhatsApp pricing type. This field is only available in PMP (Per-Message Pricing) mode.\n- `regular`: Indicates the message is billable.\n- `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.\n- `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" ], "type": "string" }, "WhatsappProfile": { "description": "Represents the profile of a WhatsApp account.", "properties": { "name": { "description": "Name of the WhatsApp account.", "example": "John", "type": "string" }, "username": { "description": "WhatsApp username.", "example": "john_doe", "type": "string" } }, "type": "object" }, "WhatsappReviewDecision": { "description": "Used if a decision about WhatsApp accounts or phone numbers has been made.", "enum": [ "APPROVED", "REJECTED", "DEFERRED" ], "type": "string" }, "WhatsappTemplate": { "description": "See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates).", "properties": { "category": { "$ref": "#/components/schemas/WhatsappTemplateCategory" }, "components": { "description": "Template components. A template consists of `HEADER`, `BODY`, `FOOTER`, and `BUTTONS` components. `BODY` component is required, the other types are optional.", "items": { "$ref": "#/components/schemas/WhatsappTemplateComponent" }, "minItems": 1, "type": "array" }, "createTime": { "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", "format": "date-time", "type": "string" }, "ctaUrlLinkTrackingOptedOut": { "description": "Whether Meta CTA URL click tracking is disabled. Historical `null` values are returned as `true`.", "example": true, "type": "boolean" }, "disableDate": { "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", "type": "string" }, "language": { "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", "type": "string" }, "messageSendTtlSeconds": { "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.\nBy 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**.\nSet 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.\nWe 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.\nAuthentication templates created before October 23, 2024, have a default TTL of 30 days.", "example": 600, "format": "int32", "type": "integer" }, "name": { "description": "Name of the template.", "maxLength": 512, "pattern": "[a-z0-9_]{1,512}", "type": "string" }, "officialTemplateId": { "description": "Official template ID assigned by WhatsApp. This ID is used to identify the template in WhatsApp's system.", "example": "official-template-id", "type": "string" }, "previousCategory": { "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.", "type": "string" }, "qualityRating": { "$ref": "#/components/schemas/WhatsappTemplateQualityRating" }, "reason": { "description": "The reason why the template is rejected.", "type": "string" }, "status": { "$ref": "#/components/schemas/WhatsappTemplateStatus" }, "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." }, "subCategory": { "$ref": "#/components/schemas/WhatsappTemplateSubCategory" }, "updateTime": { "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", "format": "date-time", "type": "string" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" }, "whatsappApiError": { "$ref": "#/components/schemas/WhatsappApiError" } }, "required": [ "wabaId", "name", "language" ], "type": "object" }, "WhatsappTemplateAnalytics": { "properties": { "analyticsStatus": { "description": "Meta Template Insights status only; it does not describe YCloud message metrics.\nNO_DATA means the Meta query completed without data for the requested date range.\nERROR indicates that Template Insights are unavailable because of an error after the\ncurrent template was successfully resolved and validated.", "enum": [ "ENABLED", "NOT_ENABLED", "UNSUPPORTED_REGION", "PERMISSION_DENIED", "NO_DATA", "ERROR" ], "type": "string" }, "dataPoints": { "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" }, "type": "array" }, "endDate": { "description": "Inclusive end date from the request.", "format": "date", "type": "string" }, "language": { "description": "Template language used for the statistics query.", "type": "string" }, "officialTemplateId": { "description": "Resolved official WhatsApp/Meta template ID. Successful queries resolve a current template; the property remains nullable for contract compatibility.", "nullable": true, "type": "string" }, "startDate": { "description": "Inclusive start date from the request.", "format": "date", "type": "string" }, "templateName": { "description": "Template name used for the statistics query.", "type": "string" }, "timezone": { "description": "IANA timezone resolved from the WABA configuration and used to interpret the date range.", "type": "string" }, "wabaId": { "description": "WhatsApp Business Account ID.", "type": "string" } }, "required": [ "wabaId", "officialTemplateId", "templateName", "language", "timezone", "analyticsStatus", "startDate", "endDate", "dataPoints" ], "type": "object" }, "WhatsappTemplateAnalyticsButtonClick": { "properties": { "buttonContent": { "description": "Button content associated with the clicks.", "type": "string" }, "count": { "description": "Number of clicks for this button entry.", "format": "int64", "type": "integer" }, "type": { "description": "Type of button associated with the clicks. Values may include quick_reply_button, unique_url_button, or url_button.", "type": "string" } }, "required": [ "type", "buttonContent", "count" ], "type": "object" }, "WhatsappTemplateAnalyticsDataPoint": { "properties": { "buttonClicks": { "description": "Button click breakdown for this template on this date. Empty when no details are available.", "items": { "$ref": "#/components/schemas/WhatsappTemplateAnalyticsButtonClick" }, "type": "array" }, "clicks": { "description": "Total number of clicks recorded for this template on this date. Interpret zero together with analyticsStatus.", "format": "int64", "type": "integer" }, "date": { "format": "date", "type": "string" }, "delivered": { "description": "Number of those messages that were delivered.", "format": "int64", "type": "integer" }, "failed": { "description": "Number of those messages whose status is failed or expired.", "format": "int64", "type": "integer" }, "read": { "description": "Number of those messages that were read.", "format": "int64", "type": "integer" }, "sent": { "description": "Number of messages created on this date for the selected template.", "format": "int64", "type": "integer" }, "uniqueReplies": { "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.", "format": "int64", "type": "integer" } }, "required": [ "date", "sent", "delivered", "failed", "read", "clicks", "uniqueReplies", "buttonClicks" ], "type": "object" }, "WhatsappTemplateAnalyticsRequest": { "description": "Specify exactly one template selector: either officialTemplateId alone, or templateName together\nwith language. officialTemplateId cannot be combined with templateName or language.", "properties": { "endDate": { "description": "Inclusive end date interpreted in the WABA timezone. The inclusive range must not exceed 90 calendar days.", "example": "2026-07-07", "format": "date", "type": "string" }, "language": { "description": "Template language code. Must be provided together with templateName when officialTemplateId is absent.", "example": "en_US", "nullable": true, "type": "string" }, "officialTemplateId": { "description": "Official WhatsApp/Meta template ID exposed by the existing template REST APIs.", "example": "875432109876543", "nullable": true, "type": "string" }, "startDate": { "description": "Inclusive start date interpreted in the WABA timezone.", "example": "2026-07-01", "format": "date", "type": "string" }, "templateName": { "description": "Exact template name. Must be provided together with language when officialTemplateId is absent.", "example": "order_update", "nullable": true, "type": "string" }, "wabaId": { "example": "102012345678901", "type": "string" } }, "required": [ "wabaId", "startDate", "endDate" ], "type": "object" }, "WhatsappTemplateCategory": { "description": "Category of WhatsApp templates.\n- `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).\n- `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.\n- `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" ], "type": "string" }, "WhatsappTemplateComponent": { "properties": { "add_security_recommendation": { "description": "**Optional. Only applicable in the `BODY` component of an AUTHENTICATION template.**\nSet 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.", "type": "boolean" }, "buttons": { "description": "**Required for type `BUTTONS`.**\nButtons 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.\nIf 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.", "items": { "$ref": "#/components/schemas/WhatsappTemplateComponentButton" }, "maxItems": 10, "type": "array" }, "cards": { "description": "**Required for type `CAROUSEL`.**\nCarousel templates support up to 10 carousel cards.", "items": { "$ref": "#/components/schemas/WhatsappTemplateComponentCard" }, "maxItems": 10, "type": "array" }, "code_expiration_minutes": { "description": "**Optional. Only applicable in the `FOOTER` component of an AUTHENTICATION template.**\nIndicates number of minutes the password or code is valid.\nIf omitted, the code expiration warning will not be displayed in the delivered message.\nMinimum 1, maximum 90.", "example": 5, "format": "int32", "maximum": 90, "minimum": 1, "type": "integer" }, "example": { "$ref": "#/components/schemas/WhatsappTemplateComponentExample" }, "format": { "description": "**Required for type `HEADER`.**", "enum": [ "TEXT", "IMAGE", "GIF", "VIDEO", "DOCUMENT", "LOCATION" ], "type": "string" }, "limited_time_offer": { "$ref": "#/components/schemas/WhatsappTemplateComponentLimitedTimeOffer" }, "text": { "description": "For body text (type = `BODY`), maximum 1024 characters.\nFor header text (type = `HEADER`, format = `TEXT`), maximum 60 characters.\nFor footer text (type = `FOOTER`), maximum 60 characters.\nFor card body text (`CAROUSEL` card component type = `BODY`), maximum 160 characters.", "maxLength": 1024, "type": "string" }, "type": { "description": "**Required.** Template component type.\n- `BODY`: Body components are text-only components and are required by all templates. Templates are limited to one body component.\n- `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.\n- `FOOTER`: Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component.\n- `BUTTONS`: Buttons are optional interactive components that perform specific actions when tapped.\n- `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.\n- `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.\n- `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" ], "type": "string" } }, "type": "object" }, "WhatsappTemplateComponentButton": { "properties": { "app_deep_link": { "$ref": "#/components/schemas/WhatsappTemplateComponentButtonAppDeepLink" }, "autofill_text": { "description": "**One-tap and zero-tap buttons only.**\nOne-tap button text.\nMaximum 25 characters.", "example": "Autofill", "maxLength": 25, "type": "string" }, "example": { "description": "Sample full URL for a `URL` button with a variable.", "items": { "type": "string" }, "type": "array" }, "flow_action": { "description": "**Use for button type `FLOW`.**\nEither `navigate` or `data_exchange`. Defaults to `navigate`.", "example": "navigate", "type": "string" }, "flow_id": { "description": "**Conditionally required for button type `FLOW`.**\nThe 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", "type": "string" }, "flow_json": { "description": "**Conditionally required for button type `FLOW`.**\nThe 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.", "type": "string" }, "flow_name": { "description": "**Conditionally required for button type `FLOW`.**\nThe 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.", "type": "string" }, "navigate_screen": { "description": "**Required if `flow_action` is `navigate`.**\nThe unique ID of the Screen in the Flow.", "example": "WELCOME_SCREEN", "type": "string" }, "otp_type": { "$ref": "#/components/schemas/WhatsappTemplateComponentButtonOtpType", "description": "**Required for button type `OTP`.**\nIndicates button OTP type.\nSet 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." }, "package_name": { "deprecated": true, "description": "**Deprecated since 2025-07-23. Use `supported_apps` instead.**\n**One-tap and zero-tap buttons only.**\nYour Android app's package name.", "example": "com.example.myapplication", "type": "string" }, "phone_number": { "description": "**Required for button type `PHONE_NUMBER`.**\nAlphanumeric string. Business phone number to be (display phone number) called when the user taps the button.\n20 characters maximum.", "example": 15550051310, "maxLength": 20, "type": "string" }, "signature_hash": { "deprecated": true, "description": "**Deprecated since 2025-07-23. Use `supported_apps` instead.**\n**One-tap and zero-tap buttons only.**\nYour 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", "type": "string" }, "supported_apps": { "description": "**One-tap and zero-tap buttons only.**\nList of supported apps.", "items": { "$ref": "#/components/schemas/WhatsappTemplateComponentButtonOtpSupportedApp" }, "type": "array" }, "text": { "description": "**Required for button type `PHONE_NUMBER` or `URL`.** Button text.\nFor `CODE_CODE` buttons, the text is a pre-set value and cannot be customized.\nFor `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, "type": "string" }, "type": { "$ref": "#/components/schemas/WhatsappTemplateComponentButtonType" }, "url": { "description": "**Required for button type `URL`.** URL of website.\nThere can be at most 1 variable at the end of the URL. Example: `https://www.luckyshrub.com/shop?promo={{1}}`.\n2000 characters maximum.", "maxLength": 2000, "type": "string" }, "zero_tap_terms_accepted": { "description": "**Zero-tap buttons only.**\nSet 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.\nIf set to `false`, the template will not be created as you need to accept zero-tap terms before creating zero-tap enabled message templates.", "type": "boolean" } }, "required": [ "type" ], "type": "object" }, "WhatsappTemplateComponentButtonAppDeepLink": { "properties": { "android_deep_link": { "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/", "type": "string" }, "android_fallback_playstore_url": { "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/", "type": "string" }, "meta_app_id": { "description": "Required if using a URL button mapped to a deep link. APP ID.", "example": "2892949377516980", "type": "string" } }, "type": "object" }, "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:", "properties": { "package_name": { "description": "Your Android app's package name.", "example": "com.example.myapplication", "type": "string" }, "signature_hash": { "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", "type": "string" } }, "type": "object" }, "WhatsappTemplateComponentButtonOtpType": { "description": "Indicates button OTP type.\nSet 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" ], "type": "string" }, "WhatsappTemplateComponentButtonType": { "description": "Button type.\n- `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.\n- `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.\n- `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.\n- `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.\n- `OTP`: One-time password (OTP) buttons are a special type of URL button component used with authentication templates.\n- `CATALOG`: When a customer taps the **View catalog** button in a catalog template message, your product catalog appears within WhatsApp.\n- `MPM`: Customers can browse products and sections by tapping the **View items** button in a multi-product template message.\n- `FLOW`: Use this type to specify the [Flow](https://developers.facebook.com/docs/whatsapp/flows) to be sent with the template message.\n- `ORDER_DETAILS`: Provides a order details button with `Review and Pay` text.\n- `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" ], "type": "string" }, "WhatsappTemplateComponentCard": { "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": { "description": "**Required.**\nCard 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)." }, "type": "array" } }, "type": "object" }, "WhatsappTemplateComponentCardComponent": { "properties": { "buttons": { "description": "**Required for type `BUTTONS`.**\nCards 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.", "items": { "$ref": "#/components/schemas/WhatsappTemplateComponentButton" }, "maxItems": 2, "minItems": 1, "type": "array" }, "example": { "$ref": "#/components/schemas/WhatsappTemplateComponentExample" }, "format": { "description": "**Required for type `HEADER`.**\nCards must have a media header (image or video).", "enum": [ "IMAGE", "VIDEO" ], "type": "string" }, "text": { "description": "**Required for type `BODY`.**\nCard body text supports variables. Maximum 160 characters.", "maxLength": 160, "type": "string" }, "type": { "description": "**Required.**\nCard component type.\n- `BODY`: Body components are text-only components. Cards must have body text.\n- `HEADER`: Cards must have a media header (image or video).\n- `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" ], "type": "string" } }, "type": "object" }, "WhatsappTemplateComponentExample": { "description": "**Required** when:\n- `type` is `HEADER`, and `format` is one of `IMAGE`, `GIF`, `VIDEO`, or `DOCUMENT`. Provide a sample media URL in `header_url`.\n- `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.\n- `type` is `BODY`, and variables are used in `text`. Provide sample values for those variables in `body_text`.", "properties": { "body_text": { "description": "Sample values for variables in `text` of a `BODY` component.", "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, "header_text": { "description": "Sample value for the variable in `text` of a `HEADER` component.", "items": { "type": "string" }, "type": "array" }, "header_url": { "description": "Sample media URL for a `HEADER` component whose format is one of `IMAGE`, `GIF`, `VIDEO`, or `DOCUMENT`.\nSupported types:\n- For `IMAGE`, the URL must end with one of `.jpg`, `.jpeg`, or `.png`, size limit is 5MB.\n- For `GIF`, the URL must end with `.mp4`, size limit is 3.5MB.\n- For `VIDEO`, the URL must end with `.mp4`, size limit is 16MB.\n- For `DOCUMENT`, the URL must end with `.pdf`, size limit is 100MB.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "WhatsappTemplateComponentLimitedTimeOffer": { "description": "Use for `LIMITED_TIME_OFFER` components.", "properties": { "has_expiration": { "description": "**Optional.**\nSet 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.\nIf set to `true`, the copy code button component must be included in the `buttons` array, and must appear first in the array.\nIf 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.", "type": "boolean" }, "text": { "description": "**Required.**\nOffer details text.\nMaximum 16 characters.", "example": "Expiring offer!", "maxLength": 16, "type": "string" } }, "type": "object" }, "WhatsappTemplateCreateRequest": { "description": "See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates).", "properties": { "category": { "$ref": "#/components/schemas/WhatsappTemplateCategory" }, "components": { "items": { "$ref": "#/components/schemas/WhatsappTemplateComponent" }, "type": "array" }, "ctaUrlLinkTrackingOptedOut": { "description": "**Optional.**\nIndicates if template button click tracking is disabled. Set to `true` to disable button click tracking on the template, or `false` to enable.\nYou 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.\nIf not provided or set to `null`, this value defaults to `true`, which means button click tracking is disabled by default.", "example": true, "type": "boolean" }, "language": { "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", "type": "string" }, "messageSendTtlSeconds": { "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.\nBy 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**.\nSet 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.\nWe 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.\nAuthentication templates created before October 23, 2024, have a default TTL of 30 days.", "example": 600, "format": "int32", "type": "integer" }, "name": { "description": "Name of the template.", "example": "sample_whatsapp_template", "maxLength": 512, "pattern": "[a-z0-9_]{1,512}", "type": "string" }, "subCategory": { "$ref": "#/components/schemas/WhatsappTemplateSubCategory" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" } }, "required": [ "wabaId", "name", "language", "category", "components" ], "type": "object" }, "WhatsappTemplateEditRequest": { "description": "The request body to edit a WhatsApp template.", "properties": { "components": { "items": { "$ref": "#/components/schemas/WhatsappTemplateComponent" }, "type": "array" }, "ctaUrlLinkTrackingOptedOut": { "description": "**Optional.**\nIndicates if template button click tracking is disabled. Set to `true` to disable button click tracking on the template, or `false` to enable.\nYou 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.\nIf not provided or set to `null`, this value defaults to `true`, which means button click tracking is disabled by default.", "example": true, "type": "boolean" }, "messageSendTtlSeconds": { "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.\nBy 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**.\nSet 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.\nWe 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.\nAuthentication templates created before October 23, 2024, have a default TTL of 30 days.", "example": 600, "format": "int32", "type": "integer" } }, "required": [ "components" ], "type": "object" }, "WhatsappTemplatePage": { "allOf": [ { "$ref": "#/components/schemas/Page" } ], "description": "Represents a given page of WhatsApp templates.", "properties": { "items": { "description": "An array containing WhatsApp template objects.", "items": { "$ref": "#/components/schemas/WhatsappTemplate" }, "type": "array" } }, "type": "object" }, "WhatsappTemplateQualityRating": { "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).\n- `GREEN`: High quality.\n- `YELLOW`: Medium quality.\n- `RED`: Low quality.\n- `UNKNOWN`: Unknown quality.", "enum": [ "GREEN", "YELLOW", "RED", "UNKNOWN" ], "type": "string" }, "WhatsappTemplateStatus": { "description": "The status of a WhatsApp template.\n- `PENDING`: The template is still under review. Review can take up to 24 hours.\n- `REJECTED`: The template has been rejected during review process.\n- `APPROVED`: The template is approved, and you may begin sending it to customers.\n- `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).\n- `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).\n- `ARCHIVED`: The template has been archived. Archived templates cannot be sent or edited.\n- `IN_APPEAL`: The template is in appeal. See also [Template Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals).\n- `DELETED`: The template is deleted.", "enum": [ "PENDING", "REJECTED", "APPROVED", "PAUSED", "DISABLED", "ARCHIVED", "IN_APPEAL", "DELETED" ], "example": "REJECTED", "type": "string" }, "WhatsappTemplateStatusUpdateEventEnum": { "description": "Used when an event happened on WhatsApp template status updates.\n- `PENDING`: Pending.\n- `APPROVED`: Approved.\n- `REJECTED`: Rejected.\n- `IN_APPEAL`: In appeal. See also [Template Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals).\n- `PAUSED`: Paused. See also [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing).\n- `FLAGGED`: Flagged. The template is scheduled for disabling.\n- `DISABLED`: Disabled. See also [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing).\n- `ARCHIVED`: Archived. The template status is updated to `ARCHIVED`.\n- `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.\n- `REINSTATED`: Reinstated.\n- `PENDING_DELETION`: Pending deletion.", "enum": [ "PENDING", "APPROVED", "REJECTED", "IN_APPEAL", "PAUSED", "FLAGGED", "DISABLED", "ARCHIVED", "UNARCHIVED", "REINSTATED", "PENDING_DELETION" ], "type": "string" }, "WhatsappTemplateSubCategory": { "description": "Subcategory of WhatsApp templates.\n- 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" ], "type": "string" }, "WhatsappUserPreference": { "properties": { "businessPhoneId": { "description": "Phone number ID.", "example": "1234567890123456", "type": "string" }, "businessPhoneNumber": { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "category": { "example": "marketing_messages", "type": "string" }, "contactName": { "description": "WhatsApp user name.", "example": "John", "type": "string" }, "contactPhoneNumber": { "description": "WhatsApp user phone number. Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "example": "+16315551111", "type": "string" }, "detail": { "description": "Description of marketing message preference.", "example": "User requested to stop marketing messages", "type": "string" }, "timestamp": { "description": "Unix timestamp indicating when the webhook was triggered.", "example": "1739321024000", "type": "string" }, "value": { "description": "Marketing message preference.", "example": "stop", "type": "string" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": 1234123123, "type": "string" } } } }, "securitySchemes": { "api_key": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "externalDocs": { "description": "Homepage", "url": "https://ycloud.com" }, "info": { "contact": { "email": "service@ycloud.com" }, "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.", "termsOfService": "https://ycloud.com/terms-service", "title": "YCloud API", "version": "v2" }, "openapi": "3.0.0", "paths": { "/balance": { "get": { "description": "Retrieves the current account balance.", "operationId": "balance-retrieve", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } }, "description": "Successfully retrieved balance." } }, "summary": "Retrieve balance", "tags": [ "Balance" ] } }, "/contact/contacts": { "get": { "description": "Returns a paginated list of contacts.\n\nOmit `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.\n\nDo 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.", "operationId": "contact-list", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/includeTotal" }, { "$ref": "#/components/parameters/contactPageAfter" }, { "description": "Comma-separated list of tag names. If any tag does not exist, the request fails with a parameter error.", "in": "query", "name": "filter.tags", "required": false, "schema": { "example": "tag1,tag2", "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).", "in": "query", "name": "filter.countryCode", "required": false, "schema": { "example": "US", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "query", "name": "filter.phoneNumber", "required": false, "schema": { "example": "+16315551111", "type": "string" } }, { "description": "The contact's email address.", "in": "query", "name": "filter.email", "required": false, "schema": { "example": "support@example.com", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactPage" } } }, "description": "Successfully retrieved a paginated list of objects." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "One or more query parameters are invalid, including an invalid cursor, incompatible pagination parameters, an out-of-range limit, or an unknown tag." } }, "summary": "List contacts", "tags": [ "Contacts" ], "x-group-parameters": true }, "post": { "description": "Creates a contact.", "operationId": "contact-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "description": "Successfully created a contact." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The notes array or note content is invalid." } }, "summary": "Create a contact", "tags": [ "Contacts" ] } }, "/contact/contacts/attributes": { "get": { "description": "Returns a list of all available contact attributes and their configurations.", "operationId": "contact-attributes-list", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ContactAttribute" }, "type": "array" } } }, "description": "Successfully retrieved contact attributes." } }, "summary": "List contact attributes", "tags": [ "Contacts" ] } }, "/contact/contacts/{contactIdentifier}/notes": { "get": { "description": "Returns all notes for a contact, ordered by creation time descending.\nThe `{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.\nContact retrieve, list, and search responses do not include notes; use this endpoint to read contact notes.", "operationId": "contact-notes-list", "parameters": [ { "$ref": "#/components/parameters/contactIdentifier-in_path_for_contact_note" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ContactNote" }, "maxItems": 50, "type": "array" } } }, "description": "Successfully retrieved contact notes." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact identifier is invalid." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "List contact notes", "tags": [ "Contacts" ] }, "post": { "description": "Creates one note for the contact and returns the created note.\nLeading 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.", "operationId": "contact-note-create", "parameters": [ { "$ref": "#/components/parameters/contactIdentifier-in_path_for_contact_note" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNote" } } }, "description": "Successfully created the contact note." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact identifier or note content is invalid, or the contact already has 50 notes." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact does not exist." } }, "summary": "Create a contact note", "tags": [ "Contacts" ] } }, "/contact/contacts/{id}": { "delete": { "description": "Deletes a contact.", "operationId": "contact-delete", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_contact" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "description": "Successfully deleted the contact." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete a contact", "tags": [ "Contacts" ] }, "get": { "description": "Retrieves a contact.", "operationId": "contact-retrieve", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_contact" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "description": "Successfully retrieved the contact." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a contact", "tags": [ "Contacts" ] }, "patch": { "description": "Updates a contact. If every supplied persisted contact field already has\nthe requested value, the contact is not updated and no\n`contact.attributes_changed` event is emitted. Note mutations in the\nsame request are still applied.", "operationId": "contact-update", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_contact" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } }, "description": "Successfully updated the contact." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The notes array, note ID, or note content is invalid." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact or referenced contact note does not exist, or the note is not owned by the contact." } }, "summary": "Update a contact", "tags": [ "Contacts" ] } }, "/contact/notes/{noteId}": { "delete": { "description": "Deletes one note in the current tenant by note ID and returns its snapshot before deletion.\nDeleting the same note again returns `404`; the operation does not use a client idempotency key.", "operationId": "contact-note-delete", "parameters": [ { "$ref": "#/components/parameters/noteId-in_path_for_contact_note" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNote" } } }, "description": "Successfully deleted the contact note." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact note ID is invalid." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact note does not exist in the current tenant." } }, "summary": "Delete a contact note", "tags": [ "Contacts" ] }, "patch": { "description": "Updates one note in the current tenant by note ID and returns the updated note.\nRepeating the same request leaves the stored content unchanged, but an accepted update may still produce another `contact.note.updated` event.", "operationId": "contact-note-update", "parameters": [ { "$ref": "#/components/parameters/noteId-in_path_for_contact_note" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNote" } } }, "description": "Successfully updated the contact note." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact note ID or content is invalid." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The contact note does not exist in the current tenant." } }, "summary": "Update a contact note", "tags": [ "Contacts" ] } }, "/emails": { "post": { "description": "Sends an outbound email message.", "operationId": "email-send", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } }, "description": "The request is successfully accepted." } }, "summary": "Send an email", "tags": [ "Emails" ] } }, "/event/definitions": { "post": { "description": "Creates a custom event definition.", "operationId": "custom_events-create-definition", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinitionCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinition" } } }, "description": "Successfully created an event definition." } }, "summary": "Create an event definition", "tags": [ "Custom Events" ] } }, "/event/definitions/{name}": { "get": { "description": "Retrieves a custom event definition you previously created.", "operationId": "custom_events-retrieve-definition", "parameters": [ { "$ref": "#/components/parameters/name-in_path_for_custom_event" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinition" } } }, "description": "Successfully retrieved the event definition." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve an event definition", "tags": [ "Custom Events" ] }, "patch": { "description": "Updates an event definition's label and description.", "operationId": "custom_events-update-definition", "parameters": [ { "$ref": "#/components/parameters/name-in_path_for_custom_event" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinitionUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinition" } } }, "description": "Successfully updated the event definition." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update an event definition", "tags": [ "Custom Events" ] } }, "/event/definitions/{name}/properties": { "post": { "description": "Defines a new property for the event definition.", "operationId": "custom_events-create-property-definition", "parameters": [ { "$ref": "#/components/parameters/name-in_path_for_custom_event" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinitionPropertyCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinitionProperty" } } }, "description": "Successfully created an event property." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Create an event property definition", "tags": [ "Custom Events" ] } }, "/event/definitions/{name}/properties/{propertyName}": { "delete": { "description": "Deletes a property of the event definition.", "operationId": "custom_events_delete-property-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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete an event property definition", "tags": [ "Custom Events" ] }, "patch": { "description": "Updates an event property definition's label and description.", "operationId": "custom_events_update-property-definition", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventDefinitionProperty" } } }, "description": "Successfully updated the event property definition." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update an event property definition", "tags": [ "Custom Events" ] } }, "/event/events": { "post": { "description": "Sends an event.", "operationId": "custom_events-send-event", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventSendRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully sent the event." } }, "summary": "Send an event", "tags": [ "Custom Events" ] } }, "/sms": { "get": { "description": "Returns a paginated list of SMS messages you've previously sent.", "operationId": "sms-list", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsPage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List SMS records", "tags": [ "SMS" ], "x-group-parameters": true }, "post": { "description": "Sends an outbound text message.", "operationId": "sms-send", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsSendRequest" } } }, "description": "SMS request that needs to be sent.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sms" } } }, "description": "The request is successfully accepted." } }, "summary": "Send an SMS", "tags": [ "SMS" ] } }, "/unsubscribers": { "get": { "description": "Returns a paginated list of unsubscribers.", "operationId": "unsubscriber-list", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/includeTotal" }, { "$ref": "#/components/parameters/pageAfter" }, { "in": "query", "name": "filter.customer", "schema": { "description": "The customer who has opted out.", "example": "+16315551111", "type": "string" } }, { "in": "query", "name": "filter.channel", "schema": { "$ref": "#/components/schemas/UnsubscriberChannel" } }, { "in": "query", "name": "filter.regionCode", "schema": { "description": "Region code, formatted in [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsubscriberPage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List unsubscribers", "tags": [ "Unsubscribers" ], "x-group-parameters": true }, "post": { "description": "Creates an unsubscriber.\nAn unsubscriber is a configuration item representing that customers opt out of receiving messages from your business.\n**A customer and a channel form a unique identifier for an unsubscriber.**", "operationId": "unsubscriber-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsubscriberCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unsubscriber" } } }, "description": "Successfully created an unsubscriber." } }, "summary": "Create an unsubscriber", "tags": [ "Unsubscribers" ] } }, "/unsubscribers/{customer}": { "get": { "description": "Returns all unsubscribers for the specified customer.", "operationId": "unsubscriber-list-all-by-customer", "parameters": [ { "$ref": "#/components/parameters/customer-in_path_for_unsubscriber" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Unsubscriber" }, "type": "array" } } }, "description": "Successfully retrieved the unsubscribers." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "List all unsubscribers by customer", "tags": [ "Unsubscribers" ] } }, "/unsubscribers/{customer}/{channel}": { "delete": { "description": "Deletes the unsubscriber for the specified customer and channel.", "operationId": "unsubscriber-delete-by-customer-and-channel", "parameters": [ { "$ref": "#/components/parameters/customer-in_path_for_unsubscriber" }, { "$ref": "#/components/parameters/channel-in_path_for_unsubscriber" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unsubscriber" } } }, "description": "Successfully deleted the unsubscriber." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete an unsubscriber", "tags": [ "Unsubscribers" ] }, "get": { "description": "Retrieves the unsubscriber for the specified customer and channel.", "operationId": "unsubscriber-retrieve-by-customer-and-channel", "parameters": [ { "$ref": "#/components/parameters/customer-in_path_for_unsubscriber" }, { "$ref": "#/components/parameters/channel-in_path_for_unsubscriber" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unsubscriber" } } }, "description": "Successfully retrieved the unsubscribers." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve an unsubscriber", "tags": [ "Unsubscribers" ] } }, "/verify/verificationChecks": { "post": { "description": "Checks a verification with a phone number, an email address, or a verification ID.\nA `pending` verification status changes to `approved` once you receive a response with the `valid` parameter is `true`. An approved verification cannot be checked anymore.", "operationId": "verification-check", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationCheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationCheck" } } }, "description": "Successfully processed the verification check." } }, "summary": "Check a verification", "tags": [ "Verify" ] } }, "/verify/verifications": { "post": { "description": "Starts a verification by sending an SMS, voice, or email message to the recipient.\nThis verification is charged once the message is sent successfully.", "operationId": "verification-send", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSendRequest" } } }, "description": "Verification request that needs to be sent.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } }, "description": "The request is successfully accepted." } }, "summary": "Start a verification", "tags": [ "Verify" ] } }, "/voices": { "get": { "description": "Returns a paginated list of voice calls you've previously sent.", "operationId": "voice-list", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List voice records", "tags": [ "Voices" ], "x-group-parameters": true }, "post": { "description": "Sends an outbound voice call verification code.", "operationId": "voice-send", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSendRequest" } } }, "description": "Voice call request that needs to be sent.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } }, "description": "The request is successfully accepted." } }, "summary": "Send a voice code", "tags": [ "Voices" ] } }, "/webhookEndpoints": { "get": { "description": "Returns a paginated list of webhook endpoints.", "operationId": "webhook_endpoint-list", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/includeTotal" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointPage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List webhook endpoints", "tags": [ "Webhook Endpoints" ], "x-group-parameters": true }, "post": { "description": "Creates a webhook endpoint listening for specific events.", "operationId": "webhook_endpoint-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "Successfully created a webhook endpoint." } }, "summary": "Create a webhook endpoint", "tags": [ "Webhook Endpoints" ] } }, "/webhookEndpoints/{id}": { "delete": { "description": "Deletes a webhook endpoint.", "operationId": "webhook_endpoint-delete", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_webhook_endpoint" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "Successfully deleted the webhook endpoint." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete a webhook endpoint", "tags": [ "Webhook Endpoints" ] }, "get": { "description": "Retrieves the webhook endpoint with the given ID.", "operationId": "webhook_endpoint-retrieve", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_webhook_endpoint" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "Successfully retrieved the webhook endpoint." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook Endpoints" ] }, "patch": { "description": "Updates a webhook endpoint, such as url, events, status.", "operationId": "webhook_endpoint-update", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_webhook_endpoint" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "Successfully updated the webhook endpoint." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update a webhook endpoint", "tags": [ "Webhook Endpoints" ] } }, "/webhookEndpoints/{id}/rotateSecret": { "post": { "description": "Generates a new secret for a webhook endpoint.", "operationId": "webhook_endpoint-rotate-secret", "parameters": [ { "$ref": "#/components/parameters/id-in_path_for_webhook_endpoint" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "Successfully rotated the webhook endpoint secret." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Rotate a webhook endpoint secret", "tags": [ "Webhook Endpoints" ] } }, "/whatsapp/businessAccounts": { "get": { "description": "Returns a paginated list of WhatsApp business accounts you've registered.", "operationId": "whatsapp_business_account-list", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/includeTotal" }, { "$ref": "#/components/parameters/filter_accountReviewStatus-WABA" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessAccountPage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List WABAs", "tags": [ "WhatsApp Business Accounts" ], "x-group-parameters": true } }, "/whatsapp/businessAccounts/{id}": { "get": { "description": "Retrieves a WABA you've registered.", "operationId": "whatsapp_business_account-retrieve", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "id", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessAccount" } } }, "description": "Successfully retrieved the WABA." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a WABA", "tags": [ "WhatsApp Business Accounts" ] } }, "/whatsapp/businessAccounts/{wabaId}/automatic-creative-optimizations": { "get": { "description": "Retrieves current automatic creative optimization feature enrollment for a WhatsApp Business Account from Meta.\n\nThis 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.", "operationId": "whatsapp_waba-retrieve-automatic-creative-optimizations", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationRetrieveResponse" } } }, "description": "Successfully retrieved current automatic creative optimization features." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Meta returned an error for the WABA automatic creative optimization query." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "You have no access to the requested WABA." } }, "summary": "Retrieve WABA automatic creative optimizations", "tags": [ "WhatsApp Business Accounts" ] }, "patch": { "description": "Partially updates automatic creative optimization feature enrollment for a WhatsApp Business Account.\n\nOnly 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.", "operationId": "whatsapp_waba-update-automatic-creative-optimizations", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappAutomaticCreativeOptimizationUpdateResponse" } } }, "description": "Successfully updated submitted automatic creative optimization features." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "One or more request parameters are invalid, or Meta returned an error for the WABA automatic creative optimization update." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "You have no access to the requested WABA." } }, "summary": "Update WABA automatic creative optimizations", "tags": [ "WhatsApp Business Accounts" ] } }, "/whatsapp/calls/accept": { "post": { "description": "Accepts an inbound WhatsApp call.\n\nOnce the WebRTC connection is made, this endpoint is used to accept the call.\nMedia will begin flowing immediately since the connection was established prior to call connect.", "operationId": "whatsapp_call-accept", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingPreAcceptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingResponse" } } }, "description": "The call accept request is successfully processed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Accept a call", "tags": [ "WhatsApp Calling" ] } }, "/whatsapp/calls/connect": { "post": { "description": "Initiates a WhatsApp call connection.\n\nEstablishes the initial connection for a WhatsApp call by providing SDP offer information.\nThis endpoint is used for business-initiated calling scenarios.", "operationId": "whatsapp_call-connect", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingConnectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingResponse" } } }, "description": "The call connection request is successfully accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Connect a call", "tags": [ "WhatsApp Calling" ] } }, "/whatsapp/calls/media/{mediaAssetId}": { "get": { "description": "Downloads an available recording or transcription generated for an API-sourced WhatsApp call.\n\nMedia 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.", "operationId": "whatsapp_call-download-media", "parameters": [ { "description": "YCloud call media asset ID received in a recording or transcription webhook.", "in": "path", "name": "mediaAssetId", "required": true, "schema": { "example": "66b1f0c2e4b05c2d8f1a3b47", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "format": "binary", "type": "string" } }, "audio/ogg": { "schema": { "format": "binary", "type": "string" } } }, "description": "The complete recording or transcription file.", "headers": { "Accept-Ranges": { "description": "Always `none`; byte-range downloads are not supported.", "schema": { "enum": [ "none" ], "type": "string" } }, "Content-Disposition": { "description": "Download attachment filename. Recordings use the `.ogg` extension and transcriptions use the `.json` extension.", "schema": { "example": "attachment; filename=\"calling-media-66b1f0c2e4b05c2d8f1a3b47.ogg\"", "type": "string" } }, "Content-Length": { "schema": { "format": "int64", "type": "integer" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request includes a non-empty Range header. Byte-range downloads are not supported." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The media asset does not exist, is not available, is expired, or does not belong to the authenticated tenant." } }, "summary": "Download call media", "tags": [ "WhatsApp Calling" ] } }, "/whatsapp/calls/preAccept": { "post": { "description": "Pre-accepts an inbound WhatsApp call.\n\nPre-accepting calls allows the calling media connection to be established before\nattempting to send call media through the connection. This facilitates faster\nconnection times and avoids audio clipping issues.", "operationId": "whatsapp_call-pre-accept", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingPreAcceptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingResponse" } } }, "description": "The call pre-accept request is successfully processed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Pre-accept a call", "tags": [ "WhatsApp Calling" ] } }, "/whatsapp/calls/reject": { "post": { "description": "Rejects an inbound WhatsApp call.\n\nThis endpoint is used to reject an incoming call from a WhatsApp user.\nThe call will be terminated on the WhatsApp user side with appropriate notification.", "operationId": "whatsapp_call-reject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingTerminateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingResponse" } } }, "description": "The call rejection request is successfully processed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Reject a call", "tags": [ "WhatsApp Calling" ] } }, "/whatsapp/calls/terminate": { "post": { "description": "Terminates an active WhatsApp call.\n\nBoth the business or the WhatsApp user can terminate the call at any time.\nThis endpoint is used by the business to end the call.", "operationId": "whatsapp_call-terminate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingTerminateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCallingResponse" } } }, "description": "The call termination request is successfully processed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Terminate a call", "tags": [ "WhatsApp Calling" ] } }, "/whatsapp/flows": { "get": { "description": "Returns a list of WhatsApp Flows under a WhatsApp Business Account (WABA).", "operationId": "whatsapp_flow-list", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "query", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "description": "List of flows.", "items": { "$ref": "#/components/schemas/WhatsappListFlowItem" }, "type": "array" } }, "type": "object" } } }, "description": "Successfully retrieved the list of flows." } }, "summary": "List flows", "tags": [ "WhatsApp Flows" ] }, "post": { "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.", "operationId": "whatsapp_flow-create", "requestBody": { "content": { "application/json": { "schema": { "properties": { "categories": { "description": "Flow categories.", "items": { "$ref": "#/components/schemas/WhatsappFlowCategory" }, "type": "array" }, "cloneFlowId": { "description": "ID of source Flow to clone. You must have permission to access the specified Flow.", "example": "flow-id-to-clone", "type": "string" }, "endpointUri": { "description": "The endpoint URI for the Flow.", "example": "https://example.com/flow-endpoint", "type": "string" }, "flowJson": { "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\":{}}]}", "type": "string" }, "name": { "description": "Flow name.", "example": "My first flow", "type": "string" }, "publish": { "default": false, "description": "If true, the Flow will be created in PUBLISHED state.", "type": "boolean" }, "wabaId": { "description": "WhatsApp Business Account ID.", "example": "whatsapp-business-account-id", "type": "string" } }, "required": [ "wabaId", "name", "categories" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The ID of the created Flow.", "example": "flow-1", "type": "string" }, "success": { "description": "Whether the operation was successful.", "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Successfully created a flow." }, "400": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": false, "type": "boolean" }, "validationErrors": { "description": "List of validation errors.", "items": { "$ref": "#/components/schemas/WhatsappFlowValidationError" }, "type": "array" } }, "type": "object" } } }, "description": "Bad request. The Flow may be invalid." } }, "summary": "Create a flow", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/flows/{flowId}": { "delete": { "description": "Deletes a WhatsApp Flow. Only Flows in DRAFT status can be deleted.", "operationId": "whatsapp_flow-delete", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Successfully deleted the flow." } }, "summary": "Delete a flow", "tags": [ "WhatsApp Flows" ] }, "get": { "description": "Retrieves a WhatsApp Flow's details.", "operationId": "whatsapp_flow-retrieve", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlow" } } }, "description": "Successfully retrieved the flow." } }, "summary": "Retrieve a flow", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/flows/{flowId}/assets": { "patch": { "description": "Updates a WhatsApp Flow's structure. Note that the file must be attached as form-data.", "operationId": "whatsapp_flow-update-structure", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "flowJson": { "description": "JSON file containing the Flow structure.", "format": "binary", "type": "string" } }, "required": [ "flowJson" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Successfully updated the flow structure." }, "400": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": false, "type": "boolean" }, "validationErrors": { "description": "List of validation errors.", "items": { "$ref": "#/components/schemas/WhatsappFlowValidationError" }, "type": "array" } }, "type": "object" } } }, "description": "Bad request. The Flow structure may be invalid." } }, "summary": "Update flow structure", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/flows/{flowId}/deprecate": { "post": { "description": "Marks a published Flow as deprecated. Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated.", "operationId": "whatsapp_flow-deprecate", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Successfully deprecated the flow." } }, "summary": "Deprecate a flow", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/flows/{flowId}/metadata": { "patch": { "description": "Updates a WhatsApp Flow's metadata (name or categories).", "operationId": "whatsapp_flow-update-metadata", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "categories": { "description": "Flow categories.", "items": { "$ref": "#/components/schemas/WhatsappFlowCategory" }, "type": "array" }, "endpointUri": { "description": "The endpoint URI for the Flow.", "example": "https://example.com/flow-endpoint", "type": "string" }, "name": { "description": "Flow name.", "example": "New flow name", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Successfully updated the flow metadata." } }, "summary": "Update flow metadata", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/flows/{flowId}/preview": { "get": { "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.**.", "operationId": "whatsapp_flow-preview", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } }, { "description": "the link will expire in 30 days in default, or if you set with invalidate=true which will generate a new link.", "in": "query", "name": "invalidate", "required": false, "schema": { "example": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappFlowPreviewUrl" } } }, "description": "Successfully generate the flow preview url." } }, "summary": "generate a web preview URL with this flow.", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/flows/{flowId}/publish": { "post": { "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.", "operationId": "whatsapp_flow-publish", "parameters": [ { "description": "Flow ID.", "in": "path", "name": "flowId", "required": true, "schema": { "example": "flow-1", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Whether the operation was successful.", "example": true, "type": "boolean" } }, "type": "object" } } }, "description": "Successfully published the flow." } }, "summary": "Publish a flow", "tags": [ "WhatsApp Flows" ] } }, "/whatsapp/groups/{groupId}/participants/remove": { "post": { "description": "Removes one or more participants from a WhatsApp group.\n\nThe request is processed asynchronously. Use webhooks to receive the final participants update result.", "operationId": "whatsapp_group-remove-participants", "parameters": [ { "$ref": "#/components/parameters/groupId-in_path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupRemoveParticipantsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupAsyncResponse" } } }, "description": "The participant removal request is successfully accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "Remove group participants", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/inboundMessages/{id}/markAsRead": { "post": { "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.\n\nMarking a message as read will also mark earlier messages in the conversation as read.", "operationId": "whatsapp_inbound_message-mark-as-read", "parameters": [ { "description": "ID of the message.\n\nA wamid (i.e., the original message ID on WhatsApp's platform) is also acceptable.", "in": "path", "name": "id", "required": true, "schema": { "example": "627c8640675de8fc689ab9d9", "type": "string" } } ], "responses": { "200": { "description": "Successfully marked the message as read." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Mark message as read", "tags": [ "WhatsApp Inbound Messages" ] } }, "/whatsapp/inboundMessages/{id}/typing": { "post": { "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.\n\nMarking 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.\n\nA successful request returns `WhatsappInboundMessageTypingResponse`. Errors reuse the standard `ErrorResponse`.", "operationId": "whatsapp_inbound_message-typing", "parameters": [ { "description": "ID of the message.\n\nA wamid (i.e., the original message ID on WhatsApp's platform) is also acceptable.", "in": "path", "name": "id", "required": true, "schema": { "example": "627c8640675de8fc689ab9d9", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappInboundMessageTypingResponse" } } }, "description": "Successfully marked the message as read and displayed a typing indicator." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The inbound message cannot be used to send a typing indicator, or the upstream request is invalid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Authentication failed because the API key is missing or invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "You do not have access to the inbound message or permission to use this endpoint." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested inbound message does not exist." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Too many requests were sent in a given amount of time." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The typing indicator could not be sent because of an internal or upstream error." } }, "summary": "Mark message as read and display a typing indicator with a JSON response", "tags": [ "WhatsApp Inbound Messages" ] } }, "/whatsapp/media/{phoneNumber}/upload": { "post": { "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.\n\nFor 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).\n\nFor more information, refer to [Meta's WhatsApp Cloud API Media documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media).\n\nNote 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.", "operationId": "whatsapp_media-upload", "parameters": [ { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format to use for the upload.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "The media file to upload. Only one file is supported. If multiple files are uploaded, only the first file will be processed.", "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The ID of the uploaded media that can be used in subsequent message requests.", "type": "string" } }, "type": "object" } } }, "description": "Successfully uploaded the media." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. The file may be invalid or exceed size limits." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Upload media", "tags": [ "WhatsApp Media" ] } }, "/whatsapp/messages": { "post": { "description": "Enqueues an outbound WhatsApp message for sending.\n\nQueued messages will be submitted to the WhatsApp Business API asynchronously.\n\nFor WhatsApp `template` messages, the referenced template must be in `APPROVED` status. `ARCHIVED` templates cannot be sent.", "operationId": "whatsapp_message-send", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessageSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } }, "description": "The request is successfully accepted." } }, "summary": "Enqueue a message", "tags": [ "WhatsApp Messages" ] } }, "/whatsapp/messages/sendDirectly": { "post": { "description": "Sends an outbound WhatsApp message directly.\n\nThe message is submitted to the WhatsApp Business API synchronously. Typically used for sending OTP and instant messages.\n\nThe response body field `error.whatsappApiError` is included if we tried to request the WhatsApp Business API and got an error response.", "operationId": "whatsapp_message-send-directly", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessageSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } }, "description": "The request is successfully accepted." } }, "summary": "Send a message directly", "tags": [ "WhatsApp Messages" ] } }, "/whatsapp/messages/{id}": { "get": { "description": "Retrieves a WhatsApp message you've previously sent.", "operationId": "whatsapp_message-retrieve", "parameters": [ { "$ref": "#/components/parameters/id-in_path" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } }, "description": "Successfully retrieved the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a message", "tags": [ "WhatsApp Messages" ] } }, "/whatsapp/phoneNumbers": { "get": { "description": "Returns a paginated list of WhatsApp business phone numbers you've registered.", "operationId": "whatsapp_phone_number-list", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/includeTotal" }, { "$ref": "#/components/parameters/filter_wabaId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberPage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List phone numbers", "tags": [ "WhatsApp Phone Numbers" ], "x-group-parameters": true } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}": { "get": { "description": "Retrieves a WhatsApp business phone number you've registered.", "operationId": "whatsapp_phone_number-retrieve", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumber" } } }, "description": "Successfully retrieved the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a phone number", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername": { "delete": { "description": "Deletes the active Business Username for a WhatsApp business phone number.\nThis 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`.", "operationId": "whatsapp_phone_number-delete-business-username", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessUsernameDeleteResult" } } }, "description": "Successfully deleted the business username." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete a phone number business username", "tags": [ "WhatsApp Phone Numbers" ] }, "get": { "description": "Retrieves the Business Username state for a WhatsApp business phone number.\nThe 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.", "operationId": "whatsapp_phone_number-retrieve-business-username", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessUsername" } } }, "description": "Successfully retrieved the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a phone number business username", "tags": [ "WhatsApp Phone Numbers" ] }, "patch": { "description": "Requests a Business Username update for a WhatsApp business phone number.\nThe 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.\n\nThe `username` value is a plain username without `@`. YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission.", "operationId": "whatsapp_phone_number-update-business-username", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessUsernameUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessUsername" } } }, "description": "Successfully submitted the update request." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update a phone number business username", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername/suggestions": { "get": { "description": "Retrieves reserved Business Username suggestions for a WhatsApp business phone number.\nThe response flattens Meta username suggestions into a string array. If no suggestions are available, `data` is an empty array.", "operationId": "whatsapp_phone_number-retrieve-business-username-suggestions", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappBusinessUsernameSuggestions" } } }, "description": "Successfully retrieved the suggestions." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve phone number business username suggestions", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}": { "delete": { "description": "Deletes the Meta contact book entry that associates a WhatsApp business phone number with a customer's WhatsApp Business-scoped user ID (BSUID).\n\nOnly 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.\n\nAn 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.", "operationId": "whatsapp_phone_number-delete-contact-book-entry", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "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`.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } }, { "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.", "in": "path", "name": "bsuid", "required": true, "schema": { "example": "US.11815799212886844830", "pattern": "^[A-Z]{2}\\.[0-9]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappContactBookEntryDeleteResult" } } }, "description": "The delete request was processed successfully." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "One or more path parameters are invalid, or Meta returned HTTP 400 for the delete request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "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." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "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`." } }, "summary": "Delete a Meta contact book entry", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/displayName": { "patch": { "description": "Updates a WhatsApp business phone number display name.", "operationId": "whatsapp_phone_number-update-displayName", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNameUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNameUpdateResponse" } } }, "description": "Successfully updated the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update a phone number display name", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile": { "get": { "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.", "operationId": "whatsapp_phone_number-retrieve-profile", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberProfile" } } }, "description": "Successfully retrieved the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a phone number profile", "tags": [ "WhatsApp Phone Numbers" ] }, "patch": { "description": "Updates a WhatsApp business phone number profile.", "operationId": "whatsapp_phone_number-update-profile", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberProfileUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberProfile" } } }, "description": "Successfully updated the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update a phone number profile", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register": { "post": { "description": "Registers a WhatsApp business phone number.", "operationId": "whatsapp_phone_number-register", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number ID.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "1234567890123456", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumber" } } }, "description": "Successfully registered the phone number." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Register a phone number", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings": { "get": { "description": "Retrieves phone number specific settings.", "operationId": "whatsapp_phone_number-retrieve-settings", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+6283138205170", "type": "string" } }, { "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.", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "capture", "calling" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "callingSettings": { "summary": "Existing Calling settings response", "value": { "calling": { "iconVisibility": "DEFAULT", "id": "19213232132", "status": "ENABLED" } } }, "captureSettings": { "summary": "Capture settings response when `type=capture`", "value": { "capture": { "announcementLanguage": "en_US", "purpose": "quality_assurance", "recordingEnabled": true, "transcriptionEnabled": true } } } }, "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberSettings" } } }, "description": "Successfully retrieved the phone number settings." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. The settings type is unsupported." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve phone number settings", "tags": [ "WhatsApp Phone Numbers" ] }, "post": { "description": "Saves phone number specific settings. Send `calling`, `capture`, or both.\nWhen both are supplied, the service independently attempts both saves after shared\nauthorization and phone-number validation. A failure in either branch does not prevent\nthe other branch from being attempted. If either branch fails, the existing error response\nis returned and the other setting may already have been saved.", "operationId": "whatsapp_phone_number-save-settings", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+6283138205150", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "callingAndCaptureSettings": { "summary": "Save Calling and Capture settings together", "value": { "calling": { "iconVisibility": "DEFAULT", "status": "ENABLED" }, "capture": { "announcementLanguage": "en_US", "purpose": "quality_assurance", "recordingEnabled": true, "transcriptionEnabled": true } } }, "callingSettings": { "summary": "Save existing Calling settings", "value": { "calling": { "iconVisibility": "DEFAULT", "status": "ENABLED" } } }, "captureSettings": { "summary": "Save Capture settings", "value": { "capture": { "announcementLanguage": "en_US", "purpose": "quality_assurance", "recordingEnabled": true, "transcriptionEnabled": true } } } }, "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberSettings" } } }, "description": "Phone number settings to save.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "callingAndCaptureSettings": { "summary": "Calling and Capture settings response", "value": { "calling": { "iconVisibility": "DEFAULT", "id": "19213232132", "status": "ENABLED" }, "capture": { "announcementLanguage": "en_US", "purpose": "quality_assurance", "recordingEnabled": true, "transcriptionEnabled": true } } }, "callingSettings": { "summary": "Existing Calling settings response", "value": { "calling": { "iconVisibility": "DEFAULT", "id": "19213232132", "status": "ENABLED" } } }, "captureSettings": { "summary": "Capture settings response", "value": { "capture": { "announcementLanguage": "en_US", "purpose": "quality_assurance", "recordingEnabled": true, "transcriptionEnabled": true } } } }, "schema": { "$ref": "#/components/schemas/WhatsappPhoneNumberSettings" } } }, "description": "Successfully saved the phone number settings." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. A Calling or Capture setting is invalid. For a combined request, the other setting may already have been saved." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Save phone number settings", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings": { "get": { "description": "Retrieves a WhatsApp business phone number's commerce settings.", "operationId": "whatsapp_phone_number-retrieve-commerce-settings", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCommerceSettings" } } }, "description": "Successfully retrieved the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve commerce settings", "tags": [ "WhatsApp Phone Numbers" ] }, "patch": { "description": "Updates a WhatsApp business phone number's commerce settings.\nUse this endpoint to enable or disable the shopping cart or the product catalog for a specific business phone number.", "operationId": "whatsapp_phone_number-update-commerce-settings", "parameters": [ { "description": "WhatsApp Business Account ID.", "in": "path", "name": "wabaId", "required": true, "schema": { "example": "whatsapp-business-account-id", "type": "string" } }, { "description": "Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.", "in": "path", "name": "phoneNumber", "required": true, "schema": { "example": "+16315551111", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCommerceSettingsUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappCommerceSettings" } } }, "description": "Successfully updated the object." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Update commerce settings", "tags": [ "WhatsApp Phone Numbers" ] } }, "/whatsapp/templates": { "get": { "description": "Returns a paginated list of WhatsApp templates you've previously created.\n\nArchived templates are included when they match the query. Use `filter.status=ARCHIVED` to list archived templates explicitly.", "operationId": "whatsapp_template-list", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/includeTotal" }, { "$ref": "#/components/parameters/filter_wabaId" }, { "description": "Name of the template.", "in": "query", "name": "filter.name", "required": false, "schema": { "example": "sample_whatsapp_template", "maxLength": 512, "pattern": "[a-z0-9_]{1,512}", "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.", "in": "query", "name": "filter.language", "required": false, "schema": { "example": "en", "type": "string" } }, { "description": "Comma-separated template statuses to filter by. Supported values include `PENDING`, `REJECTED`, `APPROVED`, `PAUSED`, `DISABLED`, `ARCHIVED`, `IN_APPEAL`, and `DELETED`.", "in": "query", "name": "filter.status", "required": false, "schema": { "example": "APPROVED,ARCHIVED", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplatePage" } } }, "description": "Successfully retrieved a paginated list of objects." } }, "summary": "List templates", "tags": [ "WhatsApp Templates" ], "x-group-parameters": true }, "post": { "description": "Creates a WhatsApp template.", "operationId": "whatsapp_template-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplateCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplate" } } }, "description": "Successfully created a WhatsApp template." } }, "summary": "Create a template", "tags": [ "WhatsApp Templates" ] } }, "/whatsapp/templates/analytics": { "post": { "description": "Returns daily YCloud message metrics and, when available, Meta Template Insights\nfor one WhatsApp template. Authenticate with `X-API-Key`.\n`analyticsStatus` describes Meta Template Insights only; it does not describe YCloud metrics.\nDates are interpreted in the WABA timezone, both boundaries are inclusive, and the range\nmust contain between 1 and 90 calendar days.\n\nThe selected template must currently exist under the requested WABA. REST resolves and\nvalidates the template before querying any statistics. A missing template returns `404`,\na template that belongs to another WABA returns `403`, and a template lookup failure returns\n`500`; none of these errors returns partial statistics.", "operationId": "whatsapp_template-analytics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplateAnalyticsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplateAnalytics" } } }, "description": "Successfully retrieved template analytics." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request parameters are invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The WABA or template is not accessible." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The WABA does not exist, or the template selected by either supported selector was not found." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "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." } }, "summary": "Retrieve WhatsApp template analytics", "tags": [ "WhatsApp Templates" ] } }, "/whatsapp/templates/{wabaId}/{name}": { "delete": { "description": "Deletes WhatsApp templates by name. If that template name exists in multiple languages, all languages will be deleted.\nHTTP status `404` is returned if no templates are found for the specific name.", "operationId": "whatsapp_template-delete-by-name", "parameters": [ { "$ref": "#/components/parameters/wabaId-in_path" }, { "description": "Name of the template.", "in": "path", "name": "name", "required": true, "schema": { "example": "sample_whatsapp_template", "maximum": 512, "minimum": 1, "pattern": "[a-z0-9_]{1,512}", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WhatsappTemplate" }, "type": "array" } } }, "description": "Successfully deleted the template(s)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete templates by name", "tags": [ "WhatsApp Templates" ] } }, "/whatsapp/templates/{wabaId}/{name}/{language}": { "delete": { "description": "Deletes a WhatsApp template by name and language.", "operationId": "whatsapp_template-delete-by-name-and-language", "parameters": [ { "$ref": "#/components/parameters/wabaId-in_path" }, { "description": "Name of the template.", "in": "path", "name": "name", "required": true, "schema": { "example": "sample_whatsapp_template", "maximum": 512, "minimum": 1, "pattern": "[a-z0-9_]{1,512}", "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.", "in": "path", "name": "language", "required": true, "schema": { "example": "en", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplate" } } }, "description": "Successfully deleted the template." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete a template", "tags": [ "WhatsApp Templates" ] }, "get": { "description": "Retrieves a WhatsApp template by name and language.\n\nThe returned template `status` may be `ARCHIVED`.", "operationId": "whatsapp_template-retrieve-by-name-and-language", "parameters": [ { "$ref": "#/components/parameters/wabaId-in_path" }, { "description": "Name of the template.", "in": "path", "name": "name", "required": true, "schema": { "example": "sample_whatsapp_template", "maximum": 512, "minimum": 1, "pattern": "[a-z0-9_]{1,512}", "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.", "in": "path", "name": "language", "required": true, "schema": { "example": "en", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplate" } } }, "description": "Successfully retrieved the template." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a template", "tags": [ "WhatsApp Templates" ] }, "patch": { "description": "Edits a WhatsApp template by name and language.\nEditing 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.\n\nOnly templates in `APPROVED`, `REJECTED`, or `PAUSED` status can be edited. `ARCHIVED` templates cannot be edited.", "operationId": "whatsapp_template-edit-by-name-and-language", "parameters": [ { "$ref": "#/components/parameters/wabaId-in_path" }, { "description": "Name of the template.", "in": "path", "name": "name", "required": true, "schema": { "example": "sample_whatsapp_template", "maximum": 512, "minimum": 1, "pattern": "[a-z0-9_]{1,512}", "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.", "in": "path", "name": "language", "required": true, "schema": { "example": "en", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplateEditRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappTemplate" } } }, "description": "Successfully edited the template." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Edit a template", "tags": [ "WhatsApp Templates" ] } }, "/whatsapp/{businessPhoneNumber}/groups": { "get": { "description": "Returns a cursor-paginated list of active WhatsApp groups.", "operationId": "whatsapp_group-list", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" }, { "$ref": "#/components/parameters/groupLimit" }, { "$ref": "#/components/parameters/groupBefore" }, { "$ref": "#/components/parameters/groupAfter" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupListResponse" } } }, "description": "Successfully retrieved groups." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "List groups", "tags": [ "WhatsApp Groups" ], "x-group-parameters": true }, "post": { "description": "Creates a WhatsApp group for the specified business phone number.\n\nThe request is processed asynchronously. Use webhooks to receive the final group lifecycle result.", "operationId": "whatsapp_group-create", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupAsyncResponse" } } }, "description": "The group creation request is successfully accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "Create a group", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/inviteLink/messages": { "post": { "description": "Sends a WhatsApp template message that contains the group invite link parameter.\n\nThis sends a message to an individual WhatsApp user. It does not send a message into the group conversation.", "operationId": "whatsapp_group-send-invite-link-message", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupInviteLinkMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } }, "description": "The message request is successfully accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "Send a group invite link message", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}": { "delete": { "description": "Deletes a WhatsApp group.\n\nThe request is processed asynchronously. Use webhooks to receive the final group lifecycle result.", "operationId": "whatsapp_group-delete", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" }, { "$ref": "#/components/parameters/groupId-in_path" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupAsyncResponse" } } }, "description": "The group deletion request is successfully accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Delete a group", "tags": [ "WhatsApp Groups" ] }, "get": { "description": "Retrieves a WhatsApp group.", "operationId": "whatsapp_group-retrieve", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" }, { "$ref": "#/components/parameters/groupId-in_path" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroup" } } }, "description": "Successfully retrieved the group." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a group", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}/inviteLink": { "get": { "description": "Retrieves the invite link for a WhatsApp group.", "operationId": "whatsapp_group-retrieve-invite-link", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" }, { "$ref": "#/components/parameters/groupId-in_path" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupInviteLink" } } }, "description": "Successfully retrieved the group invite link." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Retrieve a group invite link", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}/inviteLink/reset": { "post": { "description": "Resets and returns the invite link for a WhatsApp group.", "operationId": "whatsapp_group-reset-invite-link", "parameters": [ { "$ref": "#/components/parameters/businessPhoneNumber-in_path" }, { "$ref": "#/components/parameters/groupId-in_path" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupInviteLink" } } }, "description": "Successfully reset the group invite link." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The requested resource does not exist." } }, "summary": "Reset a group invite link", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests": { "get": { "description": "Returns a cursor-paginated list of pending join requests for a WhatsApp group.", "operationId": "whatsapp_group-list-join-requests", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupJoinRequestListResponse" } } }, "description": "Successfully retrieved group join requests." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "List group join requests", "tags": [ "WhatsApp Groups" ], "x-group-parameters": true } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests/approve": { "post": { "description": "Approves one or more pending join requests for a WhatsApp group.", "operationId": "whatsapp_group-approve-join-requests", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupJoinRequestActionResponse" } } }, "description": "Successfully processed the join request approval." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "Approve group join requests", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}/joinRequests/reject": { "post": { "description": "Rejects one or more pending join requests for a WhatsApp group.", "operationId": "whatsapp_group-reject-join-requests", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupJoinRequestActionResponse" } } }, "description": "Successfully processed the join request rejection." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "Reject group join requests", "tags": [ "WhatsApp Groups" ] } }, "/whatsapp/{businessPhoneNumber}/groups/{groupId}/settings": { "patch": { "description": "Updates a WhatsApp group's settings, such as subject or description.\n\nThe request is processed asynchronously. Use webhooks to receive the final settings update result.", "operationId": "whatsapp_group-update-settings", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappGroupAsyncResponse" } } }, "description": "The group settings update request is successfully accepted." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request. Invalid request parameters." } }, "summary": "Update group settings", "tags": [ "WhatsApp Groups" ] } } }, "security": [ { "api_key": [] } ], "servers": [ { "description": "Base URL", "url": "https://api.ycloud.com/v2" } ], "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" } ] }