{ "openapi": "3.1.0", "tags": [ { "name": "Messages", "description": "Send a message to one or many recipients. This API supports the same [channels](https://developers.sinch.com/docs/conversation/channel-support/) as Conversation API." }, { "name": "Contacts", "description": "Create or delete contacts in batches." }, { "name": "Consents", "description": "Manage Conversation API consents in batches." } ], "info": { "description": "Perform batch operations on select Conversation API resources.", "title": "Conversation API - Batch API | Sinch", "version": "1.0", "license": { "name": "MIT", "url": "https://www.sinch.com/toc" }, "contact": { "email": "support@sinch.com", "name": "support at sinch" } }, "servers": [ { "url": "https://{region}.conversationbatch.api.sinch.com", "variables": { "region": { "default": "us", "enum": [ "us", "eu", "br" ] } }, "description": "The {region} variable must be set to either us, eu, or br" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/projects/{project_id}/messages": { "parameters": [ { "$ref": "#/components/parameters/project_id" } ], "post": { "description": "Send a message to multiple recipients. Parameter variables can be included in all string fields and customized with recipient specific values. Each recipient in the request will generate a message and subsequent delivery reports based on the channel used.", "tags": [ "Messages" ], "summary": "Send a batch of messages", "operationId": "Batch_SendBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBatchRequest" }, "examples": { "TextMessageBatch": { "summary": "Text message batch", "value": { "app_id": "{{APP}}", "message": { "text_message": { "text": "Hello ${user}! Your code is ${code}" } }, "recipient_and_params": [ { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-1}" } ] } }, "parameters": { "user": "User 1", "code": "123" } }, { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-2}" } ] } }, "parameters": { "user": "User 2", "code": "456" } }, { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-3}" } ] } }, "parameters": { "user": "User 3", "code": "789" } } ] } }, "ChoiceMessageBatch": { "summary": "Choice message batch", "value": { "app_id": "{{APP}}", "message": { "choice_message": { "text_message": { "text": "Hello ${name}, what do you want to do?" }, "choices": [ { "text_message": { "text": "Choice 1" }, "postback_data": "${payload}-choice-1" }, { "text_message": { "text": "Choice 2" }, "postback_data": "${payload}-choice-2" }, { "text_message": { "text": "Choice 3" }, "postback_data": "${payload}-choice-3" } ] } }, "recipient_and_params": [ { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-1}" } ] } }, "parameters": { "name": "User 1", "payload": "user-1" } }, { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-2}" } ] } }, "parameters": { "name": "User 2", "payload": "user2" } } ] } }, "BatchWithMetadata": { "summary": "Batch with metadata", "value": { "app_id": "{{APP}}", "message": { "text_message": { "text": "Text message" } }, "recipient_and_params": [ { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-1}" } ] } }, "message_metadata": { "recipient_only": "arbitrary_value", "arbitrary_key": "overriding metadata" } }, { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-2}" } ] } }, "conversation_metadata": { "recipient_only": "arbitrary_value", "arbitrary_key": "overriding metadata" } } ], "message_metadata": { "arbitrary_key": "arbitrary_value" }, "conversation_metadata": { "arbitrary_key": "arbitrary_value" } } }, "ScheduledBatch": { "summary": "Scheduled batch", "value": { "app_id": "{{APP}}", "send_after": "2022-11-30T17:00:00", "message": { "text_message": { "text": "This is a scheduled message for 3 recipients!" } }, "recipient_and_params": [ { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-1}" } ] } } }, { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-2}" } ] } } }, { "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY-3}" } ] } } } ], "batch_metadata": { "CampaignId": "ef6b5e86-3a1f-43b4-8cba-d44b2d8162c5" } } }, "BatchWithCallbackUrl": { "summary": "Batch with callback URL override - all callbacks for given batch will be sent to this address", "value": { "app_id": "{{APP}}", "callback_url": "{{WEBHOOK_ADDRESS}}", "message": { "text_message": { "text": "Hello ${user}! Your code is ${code}" } }, "recipient_and_params": [ { "recipient": { "contact_id": "{{CONTACT-1}}" }, "parameters": { "user": "User 1", "code": "123" } }, { "recipient": { "contact_id": "{{CONTACT-2}}" }, "parameters": { "user": "User 2", "code": "456" } }, { "recipient": { "contact_id": "{{CONTACT-3}}" }, "parameters": { "user": "User 3", "code": "789" } } ] } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBatchResponse" } } } }, "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" }, "examples": { "TextMessageViolation": { "summary": "Text message violation", "value": { "error": { "code": 400, "message": "Invalid argument", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "field_violations": [ { "field": "message.text_message.text", "description": "Field is mandatory." } ] } ] } } }, "MultipleViolations": { "summary": "Multiple violations", "value": { "error": { "code": 400, "message": "Invalid argument", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "field_violations": [ { "field": "recipient_and_params[0].recipient", "description": "Field is mandatory." }, { "field": "message.text_message.text", "description": "Field is mandatory." } ] } ] } } } } } } }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PermissionDenied": { "summary": "Permission denied", "value": { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [] } } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [] } } } } } } } } }, "delete": { "description": "Cancel one or more scheduled message batches by ID or by batch metadata. If using metadata, all batches matching the given key and value will be cancelled.\n\nTo successfully cancel a batch, you must do so before the `send_after` time. Batches without a `send_after` value (i.e., batches that are sent immediately) cannot be cancelled.\n\nCancellation is performed asynchronously. This means that this method always returns a 200 response, even if the cancellation fails.", "tags": [ "Messages" ], "summary": "Cancel scheduled messages", "operationId": "Batch_CancelBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBatchRequest" }, "examples": { "CancelById": { "summary": "Cancel batch by id", "value": { "batch_id": "01GJJE4HZTAR53YE1WAA6VCF4D" } }, "CancelByMetadata": { "summary": "Cancel batches by metadata", "value": { "metadata_filter": { "key_name": "CampaignId", "key_value": "ef6b5e86-3a1f-43b4-8cba-d44b2d8162c5" } } } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PermissionDenied": { "summary": "Permission denied", "value": { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [] } } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [] } } } } } } } } }, "get": { "description": "Retrive the status of batches that match the metadata provided.", "tags": [ "Messages" ], "summary": "Get the status of batches by metadata", "operationId": "Batch_GetBatchStatusesByMetadata", "parameters": [ { "name": "metadataKey", "description": "The key of the metadata to filter batches by.", "in": "query", "required": true, "schema": { "type": "string", "example": "campaign_id" } }, { "name": "metadataValue", "description": "The value of the metadata to filter batches by.", "in": "query", "required": true, "schema": { "type": "string", "example": "my_campaign_123" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBatchStatusesByMetadataResponse" } } } }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint." }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [] } } } } } } } } } }, "/v1/projects/{project_id}/messages/{batch_id}": { "parameters": [ { "$ref": "#/components/parameters/project_id" }, { "$ref": "#/components/parameters/batch_id" } ], "get": { "description": "Retrieve the status of a batch of messages by its unique batch ID.", "tags": [ "Messages" ], "summary": "Get the status of batch of messages", "operationId": "Batch_GetBatchStatus", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBatchStatusResponse" } } } }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint." }, "404": { "description": "Batch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "BatchNotFound": { "summary": "Batch not found", "value": { "error": { "code": 404, "message": "Batch with batch_id {batch_id} was not found", "status": "NOT_FOUND", "details": [] } } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [] } } } } } } } } } }, "/v1/projects/{project_id}/contacts": { "parameters": [ { "$ref": "#/components/parameters/project_id" } ], "post": { "description": "Creates a batch of up to 1000 contacts as specified by the list of contacts.\n\nThe contacts are created asynchronously. A `CONTACT_CREATE` event will be generated for every successfully created contact.", "tags": [ "Contacts" ], "summary": "Create contacts", "operationId": "Batch_CreateContacts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactsRequest" }, "examples": { "CreateContacts": { "summary": "Create multiple contacts", "value": { "contacts": [ { "channel_identities": [ { "channel": "WHATSAPP", "identity": "{{PHONE_NUMBER_1}}" } ], "language": "EN_US" }, { "channel_identities": [ { "channel": "RCS", "identity": "{{PHONE_NUMBER_2}}" } ], "language": "EN_US" }, { "channel_identities": [ { "channel": "RCS", "identity": "{{PHONE_NUMBER_3}}" } ], "language": "EN_US" } ] } } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PermissionDenied": { "summary": "Permission denied", "value": { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [] } } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [] } } } } } } } } }, "delete": { "description": "Deletes a batch of up to 1000 contacts as specified by the list of contact IDs.\n\nThe contacts are deleted asynchronously. A `CONTACT_DELETE` event will be generated for every successfully deleted contact.", "tags": [ "Contacts" ], "summary": "Delete contacts", "operationId": "Batch_DeleteContacts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteContactsRequest" }, "examples": { "DeleteContacts": { "summary": "Delete multiple contacts", "value": { "contact_ids": [ "{{CONTACT_1}}", "{{CONTACT_2}}", "{{CONTACT_3}}", "{{CONTACT_4}}", "{{CONTACT_5}}" ] } } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PermissionDenied": { "summary": "Permission denied", "value": { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [] } } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR", "details": [] } } } } } } } } } }, "/v1/projects/{project_id}/consents": { "parameters": [ { "$ref": "#/components/parameters/project_id" } ], "post": { "description": "Insert consent records for multiple identifications in a single request. If the request fails, none or only some of the records may be inserted. Retry the batch later to try again.", "tags": [ "Consents" ], "summary": "Insert consent records", "operationId": "Batch_InsertConsents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertConsentsRequest" }, "examples": { "InsertConsents": { "summary": "Insert multiple consents", "value": { "app_id": "{{APP_ID}}", "consent_records": [ { "identification": "{{PHONE_NUMBER_1}}", "consent_type": "OPT_OUT_ALL" }, { "identification": "{{PHONE_NUMBER_2}}", "consent_type": "OPT_OUT_MARKETING" }, { "identification": "{{PHONE_NUMBER_3}}", "consent_type": "OPT_OUT_NOTIFICATION" } ] } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertConsentsResponse" } } } }, "401": { "description": "Invalid credentials" }, "403": { "description": "Permission denied. The specified project may not be allowed to use the batch endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PermissionDenied": { "summary": "Permission denied", "value": { "error": { "code": 403, "message": "", "status": "PERMISSION_DENIED", "details": [] } } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "InternalError": { "summary": "Internal error", "value": { "error": { "code": 500, "message": "There was an internal server error.", "status": "INTERNAL_ERROR" } } } } } } } } } } }, "components": { "parameters": { "project_id": { "name": "project_id", "description": "The unique ID of the project. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps).", "in": "path", "required": true, "schema": { "type": "string" } }, "batch_id": { "name": "batch_id", "description": "The unique ID of the batch. This ID is returned when submitting a batch of messages.", "in": "path", "required": true, "schema": { "type": "string" } } }, "schemas": { "BadRequest": { "type": "object", "properties": { "@type": { "type": "string" }, "field_violations": { "type": "array", "items": { "$ref": "#/components/schemas/FieldViolation" }, "description": "List of field violations in the request" } }, "additionalProperties": true }, "BadRequestResponse": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "status": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/BadRequest" } } } }, "CancelBatchRequest": { "description": "Either id or metadata", "allOf": [ { "oneOf": [ { "title": "batch_id", "description": "ID of the batch to be cancelled.", "type": "object", "properties": { "batch_id": { "type": "string" } } }, { "title": "metadata_filter", "description": "Key and value of metadata of batches to be cancelled. All batches with matching batch_metadata values will be cancelled.", "type": "object", "properties": { "metadata_filter": { "type": "object", "properties": { "key_name": { "type": "string" }, "key_value": { "type": "string" } } } } } ] } ] }, "GetBatchStatusResponse": { "type": "object", "properties": { "batch_id": { "description": "The ID of the batch of messages.", "type": "string" }, "meta_data": { "description": "The metadata associated with the batch of messages.", "type": "object", "additionalProperties": { "type": "string" } }, "status": { "description": "The status of the batch of messages.", "type": "string", "enum": [ "READY", "SCHEDULED", "PROCESSED", "CANCELLED" ] }, "send_after": { "description": "The date and time when the batch of messages is or was scheduled to be sent to recipients.", "type": "string", "format": "ISO 8601" } } }, "GetBatchStatusesByMetadataResponse": { "type": "array", "items": { "$ref": "#/components/schemas/GetBatchStatusResponse" }, "description": "List of batch statuses filtered by metadata" }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "status": { "type": "string" }, "details": { "type": "array" } } }, "FieldViolation": { "type": "object", "properties": { "field": { "type": "string", "description": "Field name which the violation refers to" }, "description": { "type": "string", "description": "Description of the violation found in the field" } } }, "GoogleProtobufAny": { "type": "object", "properties": { "@type": { "type": "string", "description": "The type of the serialized message." } }, "additionalProperties": true, "description": "Contains an arbitrary serialized message along with a @type that describes the type of the serialized message." }, "RecipientAndParam": { "type": "object", "required": [ "recipient" ], "description": "Represents a recipient and optional parameters for a message in a batch request.\nEach recipient can have custom parameters and metadata that apply only to that recipient.", "properties": { "recipient": { "$ref": "#/components/schemas/RecipientRequest" }, "parameters": { "description": "One or more key value string pairs. The key identifies what parameter to overwrite and the value is the new value.", "type": "object", "additionalProperties": { "type": "string" } }, "message_metadata": { "description": "Custom message metadata for the recipient. This will be merged with the `message metadata` in the batch request.", "type": "object", "additionalProperties": { "type": "string" } }, "conversation_metadata": { "description": "Custom conversation metadata for the recipient. This will be merged with the `conversation metadata` in the batch request.", "type": "object", "additionalProperties": { "type": "string" } } } }, "SendBatchRequest": { "type": "object", "description": "This is the request body for sending a batch of messages.", "required": [ "app_id", "message", "recipient_and_params" ], "properties": { "app_id": { "description": "The ID of the app sending the message.", "type": "string" }, "message": { "$ref": "#/components/schemas/AppMessage", "description": "Message that will be sent to the recipients. Parameters can be specified in any of the string fields inside this structure in the format `${parameter}`, where `parameter` is the parameter name." }, "processing_strategy": { "$ref": "#/components/schemas/ProcessingStrategy" }, "recipient_and_params": { "description": "A list of recipients who will receive the message. Each recipient entry can include custom parameters and metadata that apply only to that recipient.", "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/RecipientAndParam" } }, "batch_metadata": { "description": "Custom metadata that will be attached to the batch itself and returned in the response. This metadata can later be used to manage the batch. For example, you can use the metadata to [cancel it](https://developers.sinch.com/docs/conversation/api-reference/batch-api/batch/tag/Batch-API/#tag/Batch-API/operation/Batch_CancelBatch). Note: `batchId` is a reserved field that should not be included in this object, as it will be automatically added by the API.", "type": "object", "additionalProperties": { "type": "string" } }, "message_metadata": { "description": "Optional metadata that will be associated with the messages generated by the batch.\nReturned in the `metadata` field of a [Message Delivery Receipt](https://developers.sinch.com/docs/conversation/callbacks/#message-delivery-receipt).\nThis map is converted to a JSON string for compatibility with the Conversation API.\nSee [Conversation API metadata](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=message_metadata&t=request) for details.", "type": "object", "additionalProperties": { "type": "string" } }, "conversation_metadata": { "description": "Metadata that will be associated with the conversation of each message in the batch.\nThis metadata will be included in delivery receipts and can be used to correlate MO (mobile originated) messages with the original batch.\nSee [Conversation API metadata reference](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=conversation_metadata&t=request) for details.", "type": "object", "additionalProperties": { "type": "string" } }, "send_after": { "description": "Specifies when the batch should be sent. If not provided, it defaults to the current time and sends immediately. The value must be in UTC. If the scheduled time is less than 1 minute from the API call, it will be used as-is (with second-level precision). For times further in the future, the value will be rounded up to the next five-minute mark. The maximum allowed delay is 7 days. The final `send_after` value is returned in the response.", "type": "string", "format": "date-time", "example": "2025-01-01T12:34:56Z" }, "callback_url": { "description": "Overwrites the default callback url for delivery receipts for messages in this batch.\nNote that you may [define a `secret_for_overridden_callback_urls` at the app level](https://developers.sinch.com/docs/conversation/api-reference/conversation/app/app_getapp#app/app_getapp/t=response&c=200&path=callback_settings); this secret will be used to sign the contents of delivery receipts when the default callback URL is overridden by this property. The REST URL should be of the form: `http://host[:port]/path` or `https://host[:port]/path`", "type": "string" }, "channel_priority_order": { "description": "Defines the channels to use for message delivery and the order in which they will be attempted.\nSee [Conversation API reference](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=channel_priority_order&t=request) for details.", "type": "array", "items": { "$ref": "#/components/schemas/ConversationChannel" } }, "ttl": { "description": "The timeout allotted for sending the message, expressed in seconds. Passed to channels which support it and emulated by the Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with an expired TTL.\n\nThe format is an integer with the suffix `s` (for seconds). Valid integer range is 3 to 315,576,000,000 (inclusive). Example values include `10s` (10 seconds) and `86400s` (24 hours).", "type": "string" }, "channel_properties": { "description": "Channel-specific properties. The key in the map must point to a valid channel property and the maximum allowed property value length is 1024 characters.", "type": "object", "additionalProperties": { "type": "string" } }, "correlation_id": { "type": "string", "description": "An arbitrary identifier that will be propagated to callbacks related to this message, including MO messages from the recipient. The MO callbacks will always use the last correlation_id available in the conversation, similar to how `conversation_metadata` works. Only applicable to messages sent with the `CONVERSATION` processing mode. Up to 128 characters long." } } }, "SendBatchResponse": { "type": "object", "properties": { "batch_id": { "description": "The ID of the batch sent. This ID will be present in the `metadata` field of all the [delivery receipts](/docs/conversation/callbacks/#message-delivery-receipt) for messages generated from this batch request, with the key `batchId`.", "type": "string", "example": "01GCA8RWNW9FVGVSYS1BMKRW80" }, "send_after": { "description": "Time at which the batch of messages will be sent to the recipients.", "type": "string", "format": "date-time", "example": "2022-11-28T12:46:59Z" } } }, "CreateContactsRequest": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "description": "List of contacts to be created in Conversation API.", "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/ContactCreateRequest" } } } }, "CreateContactsResponse": { "type": "object", "properties": { "batch_id": { "description": "The ID of the batch sent.", "type": "string", "example": "01GCA8RWNW9FVGVSYS1BMKRW80" } } }, "DeleteContactsRequest": { "type": "object", "required": [ "contact_ids" ], "properties": { "contact_ids": { "description": "List of IDs for contacts to be deleted in Conversation API.", "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" } } } }, "DeleteContactsResponse": { "type": "object", "properties": { "batch_id": { "description": "The ID of the batch sent.", "type": "string", "example": "01GCA8RWNW9FVGVSYS1BMKRW80" } } }, "InsertConsentsRequest": { "type": "object", "required": [ "app_id", "consent_records" ], "properties": { "app_id": { "description": "The ID of the Conversation API app under which the consent records are to be stored.", "type": "string" }, "consent_records": { "type": "array", "description": "A list of consent records to create. Each record must include an `identification` field, which uniquely identifies the subject (e.g., phone number or contact ID), and a `consent_type`.\n", "items": { "type": "object", "required": [ "identification" ], "properties": { "identification": { "type": "string", "description": "Unique identifier for the subject of the consent (e.g., phone number, contact ID)." }, "consent_type": { "type": "string", "enum": [ "OPT_OUT_ALL", "OPT_OUT_NOTIFICATION", "OPT_OUT_MARKETING" ], "description": "The type of consent being inserted.\n" } } } } } }, "InsertConsentsResponse": { "type": "object", "properties": { "batch_id": { "description": "The unique ID for the batch of consent records created.", "type": "string" } } }, "CallMessageField": { "description": "Message for triggering a call.", "type": "object", "title": "Call", "properties": { "call_message": { "title": "Call Message", "type": "object", "required": [ "phone_number", "title" ], "properties": { "phone_number": { "description": "Phone number in E.164 with leading +.", "type": "string", "example": "+15551231234" }, "title": { "description": "Title shown close to the phone number.\nThe title is clickable in some cases.", "type": "string", "example": "Message text" } } } } }, "Coordinates": { "type": "object", "title": "Geographic coordinates", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "description": "The latitude.", "type": "number", "format": "float" }, "longitude": { "description": "The longitude.", "type": "number", "format": "float" } } }, "LocationMessageField": { "type": "object", "description": "Message containing geographic location.", "title": "Location", "properties": { "location_message": { "title": "Location Message", "type": "object", "required": [ "coordinates", "title" ], "properties": { "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "label": { "description": "Label or name for the position.", "type": "string" }, "title": { "description": "The title is shown close to the button or link that leads to a map showing the location. The title can be clickable in some cases.", "type": "string" } } } } }, "TextMessageField": { "type": "object", "title": "Text", "description": "A message containing only text.", "properties": { "text_message": { "type": "object", "title": "Text Message", "required": [ "text" ], "properties": { "text": { "description": "The text to be sent.", "type": "string" } } } } }, "UrlMessageField": { "description": "A generic URL message.", "type": "object", "title": "URL", "properties": { "url_message": { "title": "URL Message", "type": "object", "required": [ "title", "url" ], "properties": { "title": { "description": "The title shown close to the URL. The title can be clickable in some cases.", "type": "string" }, "url": { "description": "The url to show.", "type": "string" } } } } }, "CalendarMessageField": { "description": "Message containing details about a calendar event.", "type": "object", "title": "Calendar", "properties": { "calendar_message": { "title": "Calendar message", "type": "object", "required": [ "title", "event_start", "event_end", "event_title", "fallback_url" ], "properties": { "title": { "description": "The title is shown close to the button that leads to open a user calendar.", "type": "string" }, "event_start": { "description": "The timestamp defines start of a calendar event.", "type": "string", "format": "date-time", "example": "2025-11-30T10:00:00Z" }, "event_end": { "description": "The timestamp defines end of a calendar event.", "type": "string", "format": "date-time", "example": "2025-11-30T11:00:00Z" }, "event_title": { "description": "Title of a calendar event.", "type": "string" }, "event_description": { "description": "Description of a calendar event.", "type": "string" }, "fallback_url": { "description": "The URL that is opened when the user cannot open a calendar event directly or channel does not have support for this type.", "type": "string" } } } } }, "ShareLocationMessageField": { "description": "Message requesting location from a user.", "type": "object", "title": "Request location", "properties": { "share_location_message": { "title": "Share Location Message", "type": "object", "required": [ "title", "fallback_url" ], "properties": { "title": { "description": "The title is shown close to the button that leads to open a map to share a location.", "type": "string" }, "fallback_url": { "description": "The URL that is opened when channel does not have support for this type.", "type": "string" } } } } }, "choiceTypes": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CallMessageField" }, { "$ref": "#/components/schemas/LocationMessageField" }, { "$ref": "#/components/schemas/TextMessageField" }, { "$ref": "#/components/schemas/UrlMessageField" }, { "$ref": "#/components/schemas/CalendarMessageField" }, { "$ref": "#/components/schemas/ShareLocationMessageField" } ] }, "choiceCommonProps": { "type": "object", "properties": { "postback_data": { "description": "An optional field. This data will be returned in the ChoiceResponseMessage. The default is message_id_{text, title}." } } }, "Choice": { "description": "A choice is an action the user can take such as buttons for quick replies or other call to actions.", "type": "object", "title": "Choice message", "allOf": [ { "$ref": "#/components/schemas/choiceTypes" }, { "$ref": "#/components/schemas/choiceCommonProps" } ] }, "CardHeight": { "description": "You can set the desired size of the card in the message.", "type": "string", "x-enumDescriptions": { "UNSPECIFIED_HEIGHT": "The height of the card is unspecified.", "SHORT": "The shortest card height.", "MEDIUM": "Medium card height.", "TALL": "The tallest card height." }, "enum": [ "UNSPECIFIED_HEIGHT", "SHORT", "MEDIUM", "TALL" ] }, "MediaProperties": { "title": "Media Properties", "type": "object", "required": [ "url" ], "properties": { "thumbnail_url": { "type": "string", "description": "An optional parameter. Will be used where it is natively supported." }, "url": { "description": "Url to the media file.", "type": "string" }, "filename_override": { "description": "Overrides the media file name.", "type": "string" } } }, "CardMessage": { "description": "Message containing text, media and choices.", "title": "Card Message", "type": "object", "properties": { "choices": { "description": "You may include choices in your Card Message. The number of choices is limited to 10.", "type": "array", "items": { "$ref": "#/components/schemas/Choice" } }, "description": { "description": "This is an optional description field that is displayed below the title on the card.", "type": "string" }, "height": { "$ref": "#/components/schemas/CardHeight" }, "title": { "description": "The title of the card message.", "type": "string" }, "media_message": { "type": "object", "description": "A message containing a media component.", "allOf": [ { "$ref": "#/components/schemas/MediaProperties" } ] }, "message_properties": { "type": "object", "description": "Optional additional properties.", "properties": { "whatsapp_header": { "description": "Optional. Sets the header for the footer of a WhatsApp reply button message, if there is no media in the message. Ignored for other channels. Ignored if not transcoded to a native WhatsApp message with reply buttons.", "type": "string" } } } } }, "CardMessageField": { "description": "Field containing a Card Message", "type": "object", "title": "Card", "properties": { "card_message": { "$ref": "#/components/schemas/CardMessage" } } }, "CarouselMessageField": { "description": "Message containing a list of cards often rendered horizontally on supported channels.", "type": "object", "title": "Carousel", "properties": { "carousel_message": { "title": "Carousel Message", "type": "object", "required": [ "cards" ], "properties": { "cards": { "description": "A list of up to 10 cards.", "type": "array", "items": { "$ref": "#/components/schemas/CardMessage" } }, "choices": { "description": "Optional. Outer choices on the carousel level. The number of outer choices is limited to 3.", "type": "array", "items": { "$ref": "#/components/schemas/Choice" } } } } } }, "Choices": { "type": "object", "properties": { "choices": { "type": "array", "description": "The number of choices is limited to 10.", "items": { "$ref": "#/components/schemas/Choice" } } } }, "ChoiceMessagePropertiesField": { "type": "object", "title": "Properties", "description": "Additional properties for the message.", "properties": { "message_properties": { "type": "object", "properties": { "whatsapp_footer": { "description": "Optional. Sets the text for the footer of a WhatsApp reply button or URL button message. Ignored for other channels.", "type": "string" } } } } }, "ChoiceMessageField": { "description": "Message containing choices/actions.", "type": "object", "title": "Choice", "properties": { "choice_message": { "title": "Choice Message", "type": "object", "required": [ "choices" ], "allOf": [ { "description": "A message containing choices." }, { "$ref": "#/components/schemas/Choices" }, { "$ref": "#/components/schemas/TextMessageField" }, { "$ref": "#/components/schemas/ChoiceMessagePropertiesField" } ] } } }, "MediaMessageField": { "type": "object", "title": "Media Message", "description": "A message containing a media component, such as an image, document, or video.", "properties": { "media_message": { "$ref": "#/components/schemas/MediaProperties" } } }, "TemplateReference": { "type": "object", "title": "Template reference with concrete parameter values", "description": "The referenced template can be an omnichannel template stored in Conversation API Template Store as an AppMessage. You may also reference external channel-specific templates, such as a WhatsApp Business Template. Note that channel-specific template references are not supported when populating the `explicit_channel_omni_message` field.", "required": [ "template_id" ], "properties": { "version": { "type": "string", "description": "Used to specify what version of a template to use. Required when using `omni_channel_override` and `omni_template` fields.\nThis will be used in conjunction with `language_code`. Note that, when referencing omni-channel templates using the [Sinch Customer Dashboard](https://dashboard.sinch.com/), the latest version of a given omni-template can be identified by populating this field with `latest`." }, "language_code": { "description": "The BCP-47 language code, such as `en_US` or `sr_Latn`.\nFor more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. English is the default `language_code`.\nNote that, while many API calls involving templates accept either the dashed format (`en-US`) or the underscored format (`en_US`), some channel specific templates (for example, WhatsApp channel-specific templates) only accept the underscored format. Note that this field is required for WhatsApp channel-specific templates.", "type": "string" }, "parameters": { "description": "Required if the template has parameters. Concrete values must\nbe present for all defined parameters\nin the template. Parameters can be different for\ndifferent versions and/or languages of the template.", "type": "object", "additionalProperties": { "type": "string" } }, "template_id": { "description": "The ID of the template. Note that, in the case of WhatsApp channel-specific templates, this field must be populated by the name of the template.", "type": "string" } } }, "TemplateReferenceWithVersion": { "type": "object", "allOf": [ { "required": [ "version" ] }, { "$ref": "#/components/schemas/TemplateReference" } ] }, "TemplateMessageField": { "type": "object", "description": "Message referring to predefined template", "title": "Template Message", "properties": { "template_message": { "type": "object", "title": "Template Message", "properties": { "channel_template": { "description": "Optional. Channel specific template reference with parameters per channel.\nThe channel template if exists overrides the omnichannel template.\nAt least one of `channel_template` or `omni_template` needs to be present.\nThe key in the map must point to a valid conversation channel as\ndefined by the enum ConversationChannel.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemplateReference" } }, "omni_template": { "$ref": "#/components/schemas/TemplateReferenceWithVersion" } } } } }, "ChoiceItem": { "type": "object", "title": "Choice", "description": "A message component for interactive messages, containing a choice.", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Required parameter. Title for the choice item." }, "description": { "type": "string", "description": "Optional parameter. The description (or subtitle) of this choice item." }, "media": { "description": "Optional parameter. The media of this choice item.", "allOf": [ { "$ref": "#/components/schemas/MediaProperties" } ] }, "postback_data": { "type": "string", "description": "Optional parameter. Postback data that will be returned in the MO if the user selects this option." } } }, "ProductItem": { "type": "object", "title": "Product", "description": "A message component for interactive messages, containing a product.", "required": [ "id", "marketplace" ], "properties": { "id": { "type": "string", "description": "Required parameter. The ID for the product." }, "marketplace": { "type": "string", "description": "Required parameter. The marketplace to which the product belongs.", "example": "FACEBOOK" }, "quantity": { "type": "integer", "format": "int32", "description": "Output only. The quantity of the chosen product." }, "item_price": { "type": "number", "format": "float", "description": "Output only. The price for one unit of the chosen product." }, "currency": { "type": "string", "description": "Output only. The currency of the item_price." } } }, "ListItem": { "type": "object", "title": "List Item", "description": "Item containing either choiceItem or ProductItem", "oneOf": [ { "required": [ "choice" ], "type": "object", "properties": { "choice": { "$ref": "#/components/schemas/ChoiceItem" } }, "title": "Choice" }, { "required": [ "product" ], "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductItem" } }, "title": "Product" } ] }, "ListSection": { "type": "object", "title": "List Section", "description": "Section for interactive WhatsApp messages containing ListItem", "required": [ "items" ], "properties": { "title": { "description": "Optional parameter. Title for list section.", "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListItem" } } } }, "ListMessageField": { "type": "object", "title": "List", "description": "A message containing a list of options to choose from. All items must be of the same type.", "properties": { "list_message": { "title": "List Message", "type": "object", "required": [ "title", "sections" ], "properties": { "title": { "description": "A title for the message that is displayed near the products or choices.", "type": "string" }, "description": { "description": "This is an optional field, containing a description for the message.", "type": "string" }, "media": { "$ref": "#/components/schemas/MediaProperties" }, "sections": { "description": "List of ListSection objects containing choices to be presented in the list message.", "type": "array", "items": { "$ref": "#/components/schemas/ListSection" } }, "message_properties": { "description": "Additional properties for the message. Required if sending a product list message.", "properties": { "catalog_id": { "description": "Required if sending a product list message. The ID of the catalog to which the products belong.", "type": "string" }, "menu": { "description": "Optional. Sets the text for the menu of a choice list message.", "type": "string" }, "whatsapp_header": { "description": "Optional. Sets the text for the header of a WhatsApp choice list message. Ignored for other channels.", "type": "string" } } } } } } }, "NameInfo": { "type": "object", "title": "Name of the contact", "description": "Name information of the contact.", "required": [ "full_name" ], "properties": { "full_name": { "description": "Full name of the contact", "type": "string" }, "first_name": { "description": "First name.", "type": "string" }, "last_name": { "description": "Last name.", "type": "string" }, "middle_name": { "description": "Middle name.", "type": "string" }, "prefix": { "description": "Prefix before the name. e.g. Mr, Mrs, Dr etc.", "type": "string" }, "suffix": { "description": "Suffix after the name.", "type": "string" } } }, "PhoneNumberInfo": { "type": "object", "title": "Phone number", "description": "Phone numbers of the contact.", "required": [ "phone_number" ], "properties": { "phone_number": { "description": "Phone number with country code included.", "type": "string" }, "type": { "description": "Phone number type, e.g. WORK or HOME.", "type": "string" } } }, "AddressInfo": { "type": "object", "title": "Address information", "description": "Physical addresses of the contact.", "properties": { "city": { "description": "City Name", "type": "string" }, "country": { "description": "Country Name", "type": "string" }, "state": { "description": "Name of a state or region of a country.", "type": "string" }, "zip": { "description": "Zip/postal code", "type": "string" }, "type": { "description": "Address type, e.g. WORK or HOME", "type": "string" }, "country_code": { "description": "Two letter country code.", "type": "string" } } }, "EmailInfo": { "type": "object", "title": "Email information", "description": "Email addresses of the contact.", "required": [ "email_address" ], "properties": { "email_address": { "description": "Email address.", "type": "string" }, "type": { "description": "Email address type. e.g. WORK or HOME.", "type": "string" } } }, "OrganizationInfo": { "type": "object", "title": "Organization information", "description": "Organization information of the contact.", "properties": { "company": { "description": "Company name", "type": "string" }, "department": { "description": "Department at the company", "type": "string" }, "title": { "description": "Corporate title, e.g. Software engineer", "type": "string" } } }, "UrlInfo": { "type": "object", "title": "URL Info", "description": "A URL/website", "required": [ "url" ], "properties": { "url": { "description": "The URL to be referenced", "type": "string" }, "type": { "description": "Optional. URL type, e.g. Org or Social", "type": "string" } } }, "ContactInfoMessageField": { "type": "object", "description": "Message containing contact information.", "title": "Contact Info", "properties": { "contact_info_message": { "title": "Contact Info Message", "type": "object", "required": [ "name", "phone_numbers" ], "properties": { "name": { "$ref": "#/components/schemas/NameInfo" }, "phone_numbers": { "description": "Phone numbers of the contact", "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberInfo" } }, "addresses": { "description": "Physical addresses of the contact", "type": "array", "items": { "$ref": "#/components/schemas/AddressInfo" } }, "email_addresses": { "description": "Email addresses of the contact", "type": "array", "items": { "$ref": "#/components/schemas/EmailInfo" } }, "organization": { "$ref": "#/components/schemas/OrganizationInfo" }, "urls": { "description": "URLs/websites associated with the contact", "type": "array", "items": { "$ref": "#/components/schemas/UrlInfo" } }, "birthday": { "description": "Date of birth in YYYY-MM-DD format.", "type": "string" } } } } }, "AppMessageTypes": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CardMessageField" }, { "$ref": "#/components/schemas/CarouselMessageField" }, { "$ref": "#/components/schemas/ChoiceMessageField" }, { "$ref": "#/components/schemas/LocationMessageField" }, { "$ref": "#/components/schemas/MediaMessageField" }, { "$ref": "#/components/schemas/TemplateMessageField" }, { "$ref": "#/components/schemas/TextMessageField" }, { "$ref": "#/components/schemas/ListMessageField" }, { "$ref": "#/components/schemas/ContactInfoMessageField" } ] }, "TemplateReferenceField": { "type": "object", "title": "Template (Reference)", "properties": { "template_reference": { "$ref": "#/components/schemas/TemplateReferenceWithVersion" } } }, "OmniMessageOverride": { "oneOf": [ { "$ref": "#/components/schemas/TextMessageField" }, { "$ref": "#/components/schemas/MediaMessageField" }, { "$ref": "#/components/schemas/TemplateReferenceField" }, { "$ref": "#/components/schemas/ChoiceMessageField" }, { "$ref": "#/components/schemas/CardMessageField" }, { "$ref": "#/components/schemas/CarouselMessageField" }, { "$ref": "#/components/schemas/LocationMessageField" }, { "$ref": "#/components/schemas/ContactInfoMessageField" }, { "$ref": "#/components/schemas/ListMessageField" } ] }, "WhatsAppInteractiveTextHeader": { "type": "object", "description": "Header of the interactive message with text.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "x-enumDescriptions": { "text": "The text of the header." }, "enum": [ "text" ] }, "text": { "type": "string", "description": "Text for the header. Formatting allows emojis, but not Markdown." } } }, "WhatsAppInteractiveHeaderMedia": { "type": "object", "description": "Media object for the header.", "required": [ "link" ], "properties": { "link": { "type": "string", "description": "URL for the media." } } }, "WhatsAppInteractiveImageHeader": { "type": "object", "description": "Header of the interactive message with image.", "required": [ "type", "image" ], "properties": { "type": { "type": "string", "x-enumDescriptions": { "image": "The image associated with the header." }, "enum": [ "image" ] }, "image": { "$ref": "#/components/schemas/WhatsAppInteractiveHeaderMedia" } } }, "WhatsAppInteractiveDocumentHeader": { "type": "object", "description": "Header of the interactive message with document.", "required": [ "type", "document" ], "properties": { "type": { "type": "string", "x-enumDescriptions": { "document": "The document associated with the header." }, "enum": [ "document" ] }, "document": { "$ref": "#/components/schemas/WhatsAppInteractiveHeaderMedia" } } }, "WhatsAppInteractiveVideoHeader": { "type": "object", "description": "Header of the interactive message with video.", "required": [ "type", "video" ], "properties": { "type": { "type": "string", "x-enumDescriptions": { "video": "The video associated with the header." }, "enum": [ "video" ] }, "video": { "$ref": "#/components/schemas/WhatsAppInteractiveHeaderMedia" } } }, "WhatsAppInteractiveBody": { "type": "object", "description": "Body of the interactive message.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The content of the message (1024 characters maximum). Emojis and Markdown are supported." } } }, "WhatsAppInteractiveFooter": { "type": "object", "description": "Footer of the interactive message.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The footer content (60 characters maximum). Emojis, Markdown and links are supported." } } }, "ChannelSpecificCommonProps": { "type": "object", "properties": { "header": { "description": "The header of the interactive message.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/WhatsAppInteractiveTextHeader" }, { "$ref": "#/components/schemas/WhatsAppInteractiveImageHeader" }, { "$ref": "#/components/schemas/WhatsAppInteractiveDocumentHeader" }, { "$ref": "#/components/schemas/WhatsAppInteractiveVideoHeader" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/WhatsAppInteractiveTextHeader", "image": "#/components/schemas/WhatsAppInteractiveImageHeader", "document": "#/components/schemas/WhatsAppInteractiveDocumentHeader", "video": "#/components/schemas/WhatsAppInteractiveVideoHeader" } } }, "body": { "$ref": "#/components/schemas/WhatsAppInteractiveBody" }, "footer": { "$ref": "#/components/schemas/WhatsAppInteractiveFooter" } } }, "FlowChannelSpecificMessage": { "allOf": [ { "$ref": "#/components/schemas/ChannelSpecificCommonProps" }, { "type": "object", "title": "WhatsApp Flow channel specific message", "description": "A message type for sending WhatsApp Flows.", "required": [ "flow_id", "flow_cta" ], "properties": { "flow_id": { "type": "string", "description": "ID of the Flow." }, "flow_token": { "type": "string", "description": "Generated token which is an identifier." }, "flow_mode": { "type": "string", "description": "The mode in which the flow is.", "default": "published", "enum": [ "draft", "published" ], "x-enumDescriptions": { "draft": "The flow is in draft mode.", "published": "The flow is published." } }, "flow_cta": { "type": "string", "description": "Text which is displayed on the Call To Action button (20 characters maximum, emoji not supported)." }, "flow_action": { "type": "string", "default": "navigate", "enum": [ "navigate", "data_exchange" ], "x-enumDescriptions": { "navigate": "The navigate flow action.", "data_exchange": "The data exchange flow action." } }, "flow_action_payload": { "type": "object", "properties": { "screen": { "type": "string", "description": "The ID of the screen displayed first. This must be an entry screen." }, "data": { "type": "object", "description": "Data for the first screen." } } } } } ] }, "WhatsAppPaymentSettingsPix": { "type": "object", "deprecated": true, "required": [ "dynamic_pix" ], "properties": { "dynamic_pix": { "type": "object", "description": "The dynamic Pix payment settings.", "required": [ "code", "merchant_name", "key", "key_type" ], "properties": { "code": { "type": "string", "description": "The dynamic Pix code to be used by the buyer to pay." }, "merchant_name": { "type": "string", "description": "Account holder name." }, "key": { "type": "string", "description": "Pix key." }, "key_type": { "type": "string", "description": "Pix key type.", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ], "x-enumDescriptions": { "CPF": "The CPF key type.", "CNPJ": "The CNPJ key type.", "EMAIL": "The EMAIL key type.", "PHONE": "The PHONE key type.", "EVP": "The EVP key type." } } } } } }, "WhatsAppPaymentSettingsPaymentLink": { "type": "object", "deprecated": true, "required": [ "payment_link" ], "properties": { "payment_link": { "type": "object", "description": "The payment link payment settings.", "required": [ "uri" ], "properties": { "uri": { "type": "string", "description": "The payment link to be used by the buyer to pay." } } } } }, "WhatsAppPaymentSettingsBoleto": { "type": "object", "deprecated": true, "required": [ "boleto" ], "properties": { "boleto": { "type": "object", "description": "The Boleto payment settings.", "required": [ "digitable_line" ], "properties": { "digitable_line": { "type": "string", "description": "The Boleto digitable line which will be copied to the clipboard when the user taps the Boleto button." } } } } }, "WhatsAppPaymentSettingsButtonPix": { "type": "object", "description": "The dynamic Pix payment settings button.", "required": [ "type", "code", "merchant_name", "key", "key_type" ], "properties": { "type": { "type": "string", "enum": [ "pix_dynamic_code" ], "x-enumDescriptions": { "pix_dynamic_code": "The dynamic Pix code button identifier" } }, "code": { "type": "string", "description": "The dynamic Pix code to be used by the buyer to pay." }, "merchant_name": { "type": "string", "description": "Account holder name." }, "key": { "type": "string", "description": "Pix key." }, "key_type": { "type": "string", "description": "Pix key type.", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ], "x-enumDescriptions": { "CPF": "The CPF key type.", "CNPJ": "The CNPJ key type.", "EMAIL": "The EMAIL key type.", "PHONE": "The PHONE key type.", "EVP": "The EVP key type." } } } }, "WhatsAppPaymentSettingsButtonPaymentLink": { "type": "object", "description": "The payment link payment settings.", "required": [ "type", "uri" ], "properties": { "type": { "type": "string", "enum": [ "payment_link" ], "x-enumDescriptions": { "payment_link": "The payment link button identifier" } }, "uri": { "type": "string", "description": "The payment link to be used by the buyer to pay." } } }, "WhatsAppPaymentSettingsButtonBoleto": { "type": "object", "description": "The Boleto payment settings.", "required": [ "type", "digitable_line" ], "properties": { "type": { "type": "string", "enum": [ "boleto" ], "x-enumDescriptions": { "boleto": "The Boleto button identifier" } }, "digitable_line": { "type": "string", "description": "The Boleto digitable line which will be copied to the clipboard when the user taps the Boleto button." } } }, "WhatsAppPaymentButton": { "description": "WhatsApp Payment Button", "oneOf": [ { "$ref": "#/components/schemas/WhatsAppPaymentSettingsButtonPix" }, { "$ref": "#/components/schemas/WhatsAppPaymentSettingsButtonPaymentLink" }, { "$ref": "#/components/schemas/WhatsAppPaymentSettingsButtonBoleto" } ], "discriminator": { "propertyName": "type", "mapping": { "pix_dynamic_code": "#/components/schemas/WhatsAppPaymentSettingsButtonPix", "payment_link": "#/components/schemas/WhatsAppPaymentSettingsButtonPaymentLink", "boleto": "#/components/schemas/WhatsAppPaymentSettingsButtonBoleto" } } }, "PaymentOrderDetailsChannelSpecificMessage": { "allOf": [ { "$ref": "#/components/schemas/ChannelSpecificCommonProps" }, { "type": "object", "title": "WhatsApp Payment Order Details channel specific message.", "description": "A message type for sending WhatsApp Payment Requests.", "required": [ "payment" ], "properties": { "payment": { "type": "object", "description": "The payment order details content.", "required": [ "type", "reference_id", "type_of_goods", "total_amount_value", "order" ], "properties": { "type": { "type": "string", "description": "The country/currency associated with the payment message.", "enum": [ "br", "sg" ], "x-enumDescriptions": { "br": "Brazil", "sg": "Singapore" } }, "reference_id": { "type": "string", "description": "Unique reference ID." }, "type_of_goods": { "type": "string", "description": "The type of good associated with this order.", "enum": [ "digital-goods", "physical-goods" ], "x-enumDescriptions": { "digital-goods": "Digital goods.", "physical-goods": "Physical goods." } }, "payment_settings": { "deprecated": true, "description": "The payment settings. Use `payment_buttons` in place of this deprecated field.", "oneOf": [ { "$ref": "#/components/schemas/WhatsAppPaymentSettingsPix" }, { "$ref": "#/components/schemas/WhatsAppPaymentSettingsPaymentLink" }, { "$ref": "#/components/schemas/WhatsAppPaymentSettingsBoleto" } ] }, "payment_buttons": { "type": "array", "description": "Array of payment buttons (1 to 2 items).", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/WhatsAppPaymentButton" } }, "total_amount_value": { "type": "integer", "description": "Integer representing the total amount of the transaction." }, "order": { "type": "object", "description": "The payment order.", "required": [ "items", "subtotal_value", "tax_value" ], "properties": { "catalog_id": { "type": "string", "description": "Unique ID of the Facebook catalog being used by the business." }, "expiration_time": { "type": "string", "description": "UTC timestamp indicating when the order should expire.\nThe timestamp must be given in seconds.\nThe minimum threshold for the timestamp is 300 seconds." }, "expiration_description": { "type": "string", "description": "Description of the expiration." }, "subtotal_value": { "type": "integer", "description": "Value representing the subtotal amount of this order." }, "tax_value": { "type": "integer", "description": "Value representing the tax amount for this order." }, "tax_description": { "type": "string", "description": "Description of the tax for this order." }, "shipping_value": { "type": "integer", "description": "Value representing the shipping amount for this order." }, "shipping_description": { "type": "string", "description": "Shipping description for this order." }, "discount_value": { "type": "integer", "description": "Value of the discount for this order." }, "discount_description": { "type": "string", "description": "Description of the discount for this order." }, "discount_program_name": { "type": "string", "description": "Discount program name for this order." }, "items": { "type": "array", "description": "The items list for this order.", "items": { "type": "object", "required": [ "retailer_id", "name", "amount_value", "quantity" ], "properties": { "retailer_id": { "type": "string", "description": "Unique ID of the retailer." }, "name": { "type": "string", "description": "Item's name as displayed to the user." }, "amount_value": { "type": "integer", "description": "Price per item." }, "quantity": { "type": "integer", "description": "Number of items in this order." }, "sale_amount_value": { "type": "integer", "description": "Discounted price per item." } } } } } } } } } } ] }, "PaymentOrderStatusChannelSpecificMessage": { "allOf": [ { "$ref": "#/components/schemas/ChannelSpecificCommonProps" }, { "type": "object", "title": "WhatsApp Payment Order Status channel specific message.", "description": "A message type for sending WhatsApp Payment Status Requests.", "required": [ "payment" ], "properties": { "payment": { "type": "object", "description": "The payment order status message content", "required": [ "reference_id", "order" ], "properties": { "reference_id": { "type": "string", "description": "Unique ID used to query the current payment status." }, "order": { "type": "object", "description": "The payment order.", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "The new payment message status.", "enum": [ "pending", "processing", "partially-shipped", "shipped", "completed", "canceled" ], "x-enumDescriptions": { "pending": "The order is pending.", "processing": "The order is processing.", "partially-shipped": "A portion of the order has been shipped.", "shipped": "The order has been shipped.", "completed": "The order is complete.", "canceled": "The order was canceled." } }, "description": { "type": "string", "description": "The description of payment message status update (120 characters maximum)." } } } } } } } ] }, "KakaoTalkChannelSpecificMessage": { "type": "object", "properties": { "push_alarm": { "type": "boolean", "default": true, "description": "Set to `true` if a push alarm should be sent to a device." }, "adult": { "type": "boolean", "default": false, "description": "Set to `true` if a message contains adult content. Set to `false` by default." } } }, "KakaoTalkButton": { "type": "object", "properties": { "type": { "description": "Button type", "type": "string" }, "name": { "description": "Text displayed on the button", "type": "string", "maxLength": 8 } }, "required": [ "type", "name" ] }, "KakaoTalkWebLinkButton": { "title": "KakaoTalk Web Link Button", "description": "A button that opens a web link.", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkButton" }, { "type": "object", "properties": { "type": { "enum": [ "WL" ] }, "link_mo": { "type": "string", "description": "URL opened on a mobile device" }, "link_pc": { "type": "string", "description": "URL opened on a desktop device" } }, "required": [ "link_mo" ] } ] }, "KakaoTalkAppLinkButton": { "title": "KakaoTalk App Link Button", "description": "A button that opens an app link (e.g. call button)", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkButton" }, { "type": "object", "properties": { "type": { "enum": [ "AL" ] }, "scheme_ios": { "type": "string", "description": "App link opened on an iOS device (e.g. `tel://PHONE_NUMBER`)" }, "scheme_android": { "type": "string", "description": "App link opened on an Android device (e.g. `tel://PHONE_NUMBER`)" } }, "required": [ "scheme_ios", "scheme_android" ] } ] }, "KakaoTalkBotKeywordButton": { "title": "KakaoTalk Bot Keyword Button", "description": "A button that sends a keyword specified in `name` property", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkButton" }, { "type": "object", "properties": { "type": { "enum": [ "BK" ] } } } ] }, "KakaoTalkRegularPriceCommerce": { "description": "Information about a product with regular price", "type": "object", "properties": { "type": { "enum": [ "REGULAR_PRICE_COMMERCE" ], "x-enumDescriptions": { "REGULAR_PRICE_COMMERCE": "Commerce with regular price" } }, "title": { "description": "Product title", "type": "string", "maxLength": 30 }, "regular_price": { "description": "Regular price of the product", "type": "integer", "minimum": 0, "maximum": 99999999 } }, "required": [ "type", "title", "regular_price" ] }, "KakaoTalkDiscountFixedCommerce": { "description": "Information about a product with fixed discount", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkRegularPriceCommerce" }, { "type": "object", "properties": { "type": { "enum": [ "FIXED_DISCOUNT_COMMERCE" ], "x-enumDescriptions": { "FIXED_DISCOUNT_COMMERCE": "Commerce with fixed discount" } }, "discount_price": { "description": "Discounted price of the product", "type": "integer", "minimum": 0, "maximum": 99999999 }, "discount_fixed": { "description": "Fixed discount", "type": "integer", "minimum": 0, "maximum": 999999 } }, "required": [ "discount_price", "discount_fixed" ] } ] }, "KakaoTalkDiscountRateCommerce": { "description": "Information about a product with discount rate", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkRegularPriceCommerce" }, { "type": "object", "properties": { "type": { "enum": [ "PERCENTAGE_DISCOUNT_COMMERCE" ], "x-enumDescriptions": { "PERCENTAGE_DISCOUNT_COMMERCE": "Commerce with percentage discount" } }, "discount_price": { "description": "Discounted price of the product", "type": "integer", "minimum": 0, "maximum": 99999999 }, "discount_rate": { "description": "Discount rate (%)", "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "discount_price", "discount_rate" ] } ] }, "KakaoTalkCoupon": { "properties": { "type": { "description": "Coupon type", "type": "string" }, "description": { "description": "Coupon description", "type": "string", "maxLength": 12 }, "link_mo": { "description": "Coupon URL opened on a mobile device", "type": "string" }, "link_pc": { "description": "Coupon URL opened on a desktop device", "type": "string" }, "scheme_android": { "description": "Channel coupon URL (format: `alimtalk=coupon://...`)", "type": "string" }, "scheme_ios": { "description": "Channel coupon URL (format: `alimtalk=coupon://...`)", "type": "string" } }, "required": [ "type" ] }, "KakaoTalkFixedDiscountCoupon": { "title": "KakaoTalk fixed discount coupon", "description": "

Fixed discount coupon with with the following title: \"discount_fixed 원 할인 쿠폰\" (translates to: \"discount_fixed won discount coupon\")

\n

One of the following fields is required: link_mo, scheme_android, scheme_ios

", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkCoupon" }, { "type": "object", "properties": { "type": { "enum": [ "FIXED_DISCOUNT_COUPON" ] }, "discount_fixed": { "description": "Fixed discount", "type": "integer", "minimum": 0, "maximum": 999999 } }, "required": [ "discount_fixed" ] } ] }, "KakaoTalkDiscountRateCoupon": { "title": "KakaoTalk discount rate coupon", "description": "

Percentage discount coupon with the following title: \"discount_rate% 할인 쿠폰\" (translates to: \"discount_rate% discount coupon\")

\n

One of the following fields is required: link_mo, scheme_android, scheme_ios

", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkCoupon" }, { "type": "object", "properties": { "type": { "enum": [ "PERCENTAGE_DISCOUNT_COUPON" ] }, "discount_rate": { "description": "Discount rate (%)", "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "discount_rate" ] } ] }, "KakaoTalkShippingDiscountCoupon": { "title": "KakaoTalk shipping discount coupon", "description": "

Shipping discount coupon with with the following title: \"배송비 할인 쿠폰\" (translates to: \"shipping fee discount coupon\")

One of the following fields is required: link_mo, scheme_android, scheme_ios

\n", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkCoupon" }, { "type": "object", "properties": { "type": { "enum": [ "SHIPPING_DISCOUNT_COUPON" ] } } } ] }, "KakaoTalkFreeCoupon": { "title": "KakaoTalk free coupon", "description": "

Free coupon with the following title: \"title 무료 쿠폰\" (translates to: \"title free coupon\")

\n

One of the following fields is required: link_mo, scheme_android, scheme_ios

", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkCoupon" }, { "type": "object", "properties": { "type": { "enum": [ "FREE_COUPON" ] }, "title": { "description": "Coupon title", "type": "string", "maxLength": 7 } }, "required": [ "title" ] } ] }, "KakaoTalkUpCoupon": { "title": "KakaoTalk UP coupon", "description": "

UP coupon with the following title: \"title UP 쿠폰\" (translates to: \"title UP coupon\")

\n

One of the following fields is required: link_mo, scheme_android, scheme_ios

", "allOf": [ { "$ref": "#/components/schemas/KakaoTalkCoupon" }, { "type": "object", "properties": { "type": { "enum": [ "UP_COUPON" ] }, "title": { "description": "Coupon title", "type": "string", "maxLength": 7 } }, "required": [ "title" ] } ] }, "KakaoTalkCommerceMessage": { "type": "object", "title": "KakaoTalk commerce message", "description": "A message type for sending KakaoTalk commerce messages", "properties": { "buttons": { "description": "Buttons list", "type": "array", "minItems": 1, "maxItems": 2, "items": { "oneOf": [ { "$ref": "#/components/schemas/KakaoTalkWebLinkButton" }, { "$ref": "#/components/schemas/KakaoTalkAppLinkButton" }, { "$ref": "#/components/schemas/KakaoTalkBotKeywordButton" } ] } }, "additional_content": { "description": "Additional information", "type": "string", "maxLength": 34 }, "image": { "description": "Product image", "type": "object", "properties": { "image_url": { "type": "string", "description": "URL to the product image" }, "image_link": { "type": "string", "description": "URL opened when a user clicks on the image" } }, "required": [ "image_url" ] }, "commerce": { "description": "Product information", "oneOf": [ { "$ref": "#/components/schemas/KakaoTalkRegularPriceCommerce" }, { "$ref": "#/components/schemas/KakaoTalkDiscountFixedCommerce" }, { "$ref": "#/components/schemas/KakaoTalkDiscountRateCommerce" } ] }, "coupon": { "description": "Discount coupon", "oneOf": [ { "$ref": "#/components/schemas/KakaoTalkFixedDiscountCoupon" }, { "$ref": "#/components/schemas/KakaoTalkDiscountRateCoupon" }, { "$ref": "#/components/schemas/KakaoTalkShippingDiscountCoupon" }, { "$ref": "#/components/schemas/KakaoTalkFreeCoupon" }, { "$ref": "#/components/schemas/KakaoTalkUpCoupon" } ] } }, "required": [ "image", "commerce", "buttons" ] }, "KakaoTalkCommerceChannelSpecificMessage": { "allOf": [ { "$ref": "#/components/schemas/KakaoTalkChannelSpecificMessage" }, { "$ref": "#/components/schemas/KakaoTalkCommerceMessage" }, { "type": "object", "title": "KakaoTalk commerce channel specific message", "description": "A message type for sending KakaoTalk commerce messages" } ] }, "KakaoTalkCarouselCommerceChannelSpecificMessage": { "allOf": [ { "$ref": "#/components/schemas/KakaoTalkChannelSpecificMessage" }, { "type": "object", "title": "KakaoTalk carousel commerce channel specific message", "description": "A message type for sending KakaoTalk carousel commerce messages", "properties": { "carousel": { "description": "Carousel content", "type": "object", "properties": { "head": { "description": "Carousel introduction", "type": "object", "properties": { "header": { "description": "Carousel introduction title", "type": "string", "maxLength": 20 }, "content": { "description": "Carousel introduction description", "type": "string", "maxLength": 50 }, "image_url": { "description": "URL to the image displayed in the introduction", "type": "string" }, "link_mo": { "description": "URL opened on a mobile device", "type": "string" }, "link_pc": { "description": "URL opened on a desktop device", "type": "string" }, "scheme_ios": { "description": "App link opened on an iOS device (e.g. `tel://PHONE_NUMBER`)", "type": "string" }, "scheme_android": { "description": "App link opened on an Android device (e.g. `tel://PHONE_NUMBER`)", "type": "string" } }, "required": [ "header", "content", "image_url" ] }, "list": { "description": "List of carousel cards", "type": "array", "minItems": 2, "maxItems": 10, "items": { "$ref": "#/components/schemas/KakaoTalkCommerceMessage" } }, "tail": { "description": "\"More\" button", "type": "object", "properties": { "link_mo": { "description": "URL opened on a mobile device", "type": "string" }, "link_pc": { "description": "URL opened on a desktop device", "type": "string" }, "scheme_ios": { "description": "App link opened on an iOS device (e.g. `tel://PHONE_NUMBER`)", "type": "string" }, "scheme_android": { "description": "App link opened on an Android device (e.g. `tel://PHONE_NUMBER`)", "type": "string" } }, "required": [ "link_mo" ] } }, "required": [ "list" ] } }, "required": [ "carousel" ] } ] }, "LineNotificationMessageTemplateEmphasizedItem": { "type": "object", "description": "Template emphasized item", "required": [ "item_key", "content" ], "properties": { "item_key": { "description": "Item key. See [LINE documentation](https://developers.line.biz/en/docs/partner-docs/line-notification-messages/template/?r=jp#items) for available keys", "type": "string" }, "content": { "description": "Item value", "type": "string", "maxLength": 15 } } }, "LineNotificationMessageTemplateItem": { "type": "object", "description": "Template item", "required": [ "item_key", "content" ], "properties": { "item_key": { "description": "Item key. See [LINE documentation](https://developers.line.biz/en/docs/partner-docs/line-notification-messages/template/?r=jp#items) for available keys", "type": "string" }, "content": { "description": "Item value", "type": "string", "maxLength": 300 } } }, "LineNotificationMessageTemplateButton": { "type": "object", "description": "Template button", "required": [ "button_key", "url" ], "properties": { "button_key": { "type": "string", "description": "Button key. See [LINE documentation](https://developers.line.biz/en/docs/partner-docs/line-notification-messages/template/?r=jp#buttons) for available keys" }, "url": { "type": "string", "maxLength": 1000, "description": "Button URL" } } }, "LineNotificationMessageTemplateBody": { "type": "object", "description": "Template body", "properties": { "emphasized_item": { "$ref": "#/components/schemas/LineNotificationMessageTemplateEmphasizedItem" }, "items": { "type": "array", "description": "List of template items", "items": { "$ref": "#/components/schemas/LineNotificationMessageTemplateItem" }, "maxItems": 15 }, "buttons": { "type": "array", "description": "List of template buttons", "items": { "$ref": "#/components/schemas/LineNotificationMessageTemplateButton" }, "maxItems": 2 } } }, "LineNotificationMessageTemplateChannelSpecificMessage": { "type": "object", "title": "LINE notification message (template) channel specific message", "description": "A message type for sending LINE notification messages (template)", "required": [ "template_key" ], "properties": { "template_key": { "description": "Template key. See [LINE documentation](https://developers.line.biz/en/docs/partner-docs/line-notification-messages/template/?r=jp#templates) for available keys", "type": "string" }, "body": { "$ref": "#/components/schemas/LineNotificationMessageTemplateBody" } } }, "ChannelSpecificMessage": { "type": "object", "title": "Channel specific message", "description": "A message containing a channel specific message (not supported by OMNI types).", "required": [ "message_type", "message" ], "properties": { "message_type": { "type": "string", "x-enumDescriptions": { "FLOWS": "The WhatsApp Flows message type.", "ORDER_DETAILS": "The WhatsApp order details message type.", "ORDER_STATUS": "The WhatsApp order status message type.", "COMMERCE": "KakaoTalk commerce channel specific message type", "CAROUSEL_COMMERCE": "KakaoTalk carousel commerce channel specific message type", "NOTIFICATION_MESSAGE_TEMPLATE": "LINE notification message template type" }, "description": "The type of the channel specific message.", "enum": [ "FLOWS", "ORDER_DETAILS", "ORDER_STATUS", "COMMERCE", "CAROUSEL_COMMERCE", "NOTIFICATION_MESSAGE_TEMPLATE" ] }, "message": { "oneOf": [ { "$ref": "#/components/schemas/FlowChannelSpecificMessage" }, { "$ref": "#/components/schemas/PaymentOrderDetailsChannelSpecificMessage" }, { "$ref": "#/components/schemas/PaymentOrderStatusChannelSpecificMessage" }, { "$ref": "#/components/schemas/KakaoTalkCommerceChannelSpecificMessage" }, { "$ref": "#/components/schemas/KakaoTalkCarouselCommerceChannelSpecificMessage" }, { "$ref": "#/components/schemas/LineNotificationMessageTemplateChannelSpecificMessage" } ] } } }, "AgentType": { "description": "Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT.", "enum": [ "UNKNOWN_AGENT_TYPE", "HUMAN", "BOT" ], "x-enumDescriptions": { "UNKNOWN_AGENT_TYPE": "The default AgentType. When the agent type is unknown.", "HUMAN": "Human agent.", "BOT": "Bot agent." }, "type": "string", "default": "UNKNOWN_AGENT_TYPE" }, "Agent": { "description": "Represents an agent that is involved in a conversation.", "type": "object", "title": "Agent", "properties": { "display_name": { "description": "Agent's display name", "type": "string" }, "type": { "$ref": "#/components/schemas/AgentType" }, "picture_url": { "description": "The Agent's picture url.", "type": "string" } } }, "AppMessageCommonProps": { "type": "object", "properties": { "explicit_channel_message": { "description": "Allows you to specify a channel and define a corresponding channel specific message payload that will override the standard Conversation API message types. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. The message content must be provided in a string format. You may use the [transcoding endpoint](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Transcoding/) to help create your message. For more information about how to construct an explicit channel message for a particular channel, see that [channel's corresponding documentation](https://developers.sinch.com/docs/conversation/channel-support/) (for example, using explicit channel messages with [the WhatsApp channel](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/#explicit-channel-messages)).", "type": "object", "additionalProperties": { "type": "string" } }, "explicit_channel_omni_message": { "description": "Override the message's content for specified channels. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. The content defined under the specified channel will be sent on that channel.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/OmniMessageOverride" } }, "channel_specific_message": { "description": "Channel specific messages, overriding any transcoding. The structure of this property is more well-defined than the open structure of the `explicit_channel_message` property, and may be easier to use.\nThe key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChannelSpecificMessage" } }, "agent": { "$ref": "#/components/schemas/Agent" } } }, "AppMessage": { "type": "object", "title": "Message originating from app", "description": "A message originating from a Conversation API app", "allOf": [ { "$ref": "#/components/schemas/AppMessageTypes" }, { "$ref": "#/components/schemas/AppMessageCommonProps" } ] }, "ProcessingStrategy": { "description": "Overrides the app's [Processing Mode](https://developers.sinch.com/docs/conversation/processing-modes/). Default value is `DEFAULT`.", "enum": [ "DEFAULT", "DISPATCH_ONLY" ], "x-enumDescriptions": { "DEFAULT": "The request will inherit the app's configured processing mode.", "DISPATCH_ONLY": "Forces the request to be processed in dispatch mode (without storing contacts and conversations), regardless of the app's configured processing mode. Please note that user replies will still be processed in the app's default processing mode and that the `conversation_metadata` and `correlation_id` fields are not supported when using this option with an app in `CONVERSATION` mode." }, "type": "string", "default": "DEFAULT" }, "ConversationChannel": { "type": "string", "title": "Channel Identifier", "description": "The identifier of the channel you want to include. Must be one of the enum values.", "example": "WHATSAPP", "x-enumDescriptions": { "WHATSAPP": "The WhatsApp channel.", "RCS": "The RCS channel.", "SMS": "The SMS channel.", "MESSENGER": "The Facebook Messenger channel.", "VIBERBM": "The Viber Business Messages channel.", "MMS": "The MMS channel.", "INSTAGRAM": "The Instagram channel.", "TELEGRAM": "The Telegram channel.", "KAKAOTALK": "The KakaoTalk channel.", "KAKAOTALKCHAT": "The KakaoTalk chat channel (used primarily in ConsultationTalk).", "LINE": "The LINE channel.", "WECHAT": "The WeChat channel.", "APPLEBC": "The Apple Messages for Business channel." }, "enum": [ "WHATSAPP", "RCS", "SMS", "MESSENGER", "VIBERBM", "MMS", "INSTAGRAM", "TELEGRAM", "KAKAOTALK", "KAKAOTALKCHAT", "LINE", "WECHAT", "APPLEBC" ] }, "ChannelRecipientIdentity": { "type": "object", "required": [ "identity", "channel" ], "properties": { "channel": { "$ref": "#/components/schemas/ConversationChannel" }, "identity": { "description": "The channel recipient identity.", "type": "string" } } }, "ChannelIdentities": { "required": [ "channel_identities" ], "type": "object", "properties": { "channel_identities": { "description": "A list of specific channel identities.\nThe API will use these identities when sending to specific channels.", "type": "array", "items": { "$ref": "#/components/schemas/ChannelRecipientIdentity" } } } }, "IdentifiedByField": { "type": "object", "title": "Channel Identities", "properties": { "identified_by": { "title": "Channel Identity List", "type": "object", "description": "The identity as specified by the channel.", "allOf": [ { "$ref": "#/components/schemas/ChannelIdentities" } ] } } }, "ContactIDField": { "type": "object", "title": "Contact ID", "properties": { "contact_id": { "title": "Contact ID string", "description": "The ID of the contact.", "type": "string", "example": "{CONTACT_ID}" } } }, "RecipientBase": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/IdentifiedByField" }, { "$ref": "#/components/schemas/ContactIDField" } ] }, "RecipientRequest": { "description": "Identifies the recipient. If [Dispatch Mode](https://developers.sinch.com/docs/conversation/processing-modes/) is used, you must use the `identified_by` field.", "allOf": [ { "$ref": "#/components/schemas/RecipientBase" } ] }, "ChannelIdentity": { "description": "A unique identity of message recipient on a particular channel.\nFor example, the channel identity on SMS, WHATSAPP or VIBERBM is a MSISDN phone number.", "type": "object", "title": "Channel Identity", "required": [ "identity", "channel" ], "properties": { "app_id": { "description": "Required if using a channel that uses app-scoped channel identities. Currently, FB Messenger, Instagram, LINE, and WeChat use app-scoped channel identities, which means contacts will have different channel identities on different Conversation API apps. These can be thought of as virtual identities that are app-specific and, therefore, the app_id must be included in the API call.", "type": "string" }, "channel": { "$ref": "#/components/schemas/ConversationChannel" }, "identity": { "description": "The channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business.", "type": "string" } } }, "ContactLanguage": { "type": "string", "enum": [ "AF", "SQ", "AR", "AZ", "BN", "BG", "CA", "ZH", "ZH_CN", "ZH_HK", "ZH_TW", "HR", "CS", "DA", "NL", "EN", "EN_GB", "EN_US", "ET", "FIL", "FI", "FR", "DE", "EL", "GU", "HA", "HE", "HI", "HU", "ID", "GA", "IT", "JA", "KN", "KK", "KO", "LO", "LV", "LT", "MK", "MS", "ML", "MR", "NB", "FA", "PL", "PT", "PT_BR", "PT_PT", "PA", "RO", "RU", "SR", "SK", "SL", "ES", "ES_AR", "ES_ES", "ES_MX", "SW", "SV", "TA", "TE", "TH", "TR", "UK", "UR", "UZ", "VI", "ZU" ], "x-enumDescriptions": { "AF": "Afrikaans", "SQ": "Albanian", "AR": "Arabic", "AZ": "Azerbaijani", "BN": "Bengali", "BG": "Bulgarian", "CA": "Catalan", "ZH": "Chinese", "ZH_CN": "Chinese (CHN)", "ZH_HK": "Chinese (HKG)", "ZH_TW": "Chinese (TAI)", "HR": "Croatian", "CS": "Czech", "DA": "Danish", "NL": "Dutch", "EN": "English", "EN_GB": "English (UK)", "EN_US": "English (US)", "ET": "Estonian", "FIL": "Filipino", "FI": "Finnish", "FR": "French", "DE": "German", "EL": "Greek", "GU": "Gujarati", "HA": "Hausa", "HE": "Hebrew", "HI": "Hindi", "HU": "Hungarian", "ID": "Indonesian", "GA": "Irish", "IT": "Italian", "JA": "Japanese", "KN": "Kannada", "KK": "Kazakh", "KO": "Korean", "LO": "Lao", "LV": "Latvian", "LT": "Lithuanian", "MK": "Macedonian", "MS": "Malay", "ML": "Malayalam", "MR": "Marathi", "NB": "Norwegian", "FA": "Persian", "PL": "Polish", "PT": "Portuguese", "PT_BR": "Portuguese (BR)", "PT_PT": "Portuguese (PT)", "PA": "Punjabi", "RO": "Romanian", "RU": "Russian", "SR": "Serbian", "SK": "Slovak", "SL": "Slovenian", "ES": "Spanish", "ES_AR": "Spanish (ARG)", "ES_ES": "Spanish (SPA)", "ES_MX": "Spanish (MEX)", "SW": "Swahili", "SV": "Swedish", "TA": "Tamil", "TE": "Telugu", "TH": "Thai", "TR": "Turkish", "UK": "Ukrainian", "UR": "Urdu", "UZ": "Uzbek", "VI": "Vietnamese", "ZU": "Zulu" } }, "ContactCreateRequest": { "description": "A participant in a conversation typically representing a person. It is associated with a collection of channel identities.", "type": "object", "title": "Contact creation request", "required": [ "channel_identities", "language" ], "properties": { "channel_identities": { "description": "List of channel identities. Array must contain at least one item.", "type": "array", "items": { "$ref": "#/components/schemas/ChannelIdentity" } }, "channel_priority": { "description": "List of channels defining the channel priority. The channel at the top of the list is tried first.", "type": "array", "items": { "$ref": "#/components/schemas/ConversationChannel" } }, "display_name": { "type": "string", "description": "The display name. A default 'Unknown' will be assigned if left empty." }, "email": { "description": "Email of the contact.", "type": "string" }, "external_id": { "description": "Contact identifier in an external system.", "type": "string" }, "language": { "$ref": "#/components/schemas/ContactLanguage" }, "metadata": { "description": "Metadata associated with the contact. Up to 1024 characters long.", "type": "string" } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The token is sent in the `Authorization` header preceded by `Bearer`. It's required for all requests made to the REST API.\nFor more information, see [Authentication](/docs/conversation/api-reference/batch-api/#authentication).\n" } } } }