openapi: 3.1.0 info: description: |- Send and receive messages globally over SMS, RCS, WhatsApp, Viber Business, Facebook messenger and other popular channels using the Sinch Conversation API. The Conversation API endpoint uses built-in transcoding to give you the power of conversation across all supported channels and, if required, full control over channel specific features. title: Conversation 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://eu.conversation.api.sinch.com" - url: "https://us.conversation.api.sinch.com" security: - Basic: [] - oAuth2: [] paths: '/v1/projects/{project_id}/messages:send': parameters: - $ref: "#/components/parameters/project_id" post: description: |- You can send a message from a Conversation app to a contact in that app. The message is added to the active conversation with the contact if a conversation already exists. If no active conversation exists a new one is started automatically. You can find all of your IDs and authentication credentials on the [dashboard](https://dashboard.sinch.com/convapi/overview). tags: - Messages summary: Send a message operationId: Messages_SendMessage requestBody: $ref: "#/components/requestBodies/SendMessageRequest" responses: "200": $ref: "#/components/responses/sendMessageResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/messages/{message_id}': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/message_id" - $ref: "#/components/parameters/messages_source" get: description: Retrieves a specific message by its ID. tags: - Messages summary: Get a message operationId: Messages_GetMessage responses: "200": $ref: "#/components/responses/getMessageResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" delete: description: |- Delete a specific message by its ID. Note: Removing all messages of a conversation will not automatically delete the conversation. tags: - Messages summary: Delete a message operationId: Messages_DeleteMessage responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" "/v1/projects/{project_id}/messages": parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/query_conversation_id" description: One of `conversation_id` or `contact_id` needs to be present if `messages_source` is `CONVERSATION_SOURCE`. - $ref: "#/components/parameters/query_contact_id" description: One of `conversation_id` or `contact_id` needs to be present if `messages_source` is `CONVERSATION_SOURCE`. - name: app_id description: Id of the app. Required only when `messages_source` is `DISPATCH_SOURCE`. in: query schema: type: string - description: |- Maximum number of messages to fetch. Defaults to 10 and the maximum is 20. name: page_size in: query schema: type: integer format: int32 - description: Next page token previously returned if any. name: page_token in: query schema: type: string - name: view in: query schema: $ref: '#/components/schemas/ConversationMessagesView' - $ref: "#/components/parameters/messages_source" - $ref: "#/components/parameters/only_recipient_originated" get: description: |- This operation lists all messages sent or received via particular [Processing Modes](../../../../processing-modes/). - When using `CONVERSATION` mode, this operation lists messages associated with a conversation or a contact. - When using `DISPATCH` mode, this operation lists messages associated with an app. The messages are ordered by their `accept_time` property in descending order, where `accept_time` is a timestamp of when the message was enqueued by the Conversation API. This means messages received most recently will be listed first. tags: - Messages summary: List messages operationId: Messages_ListMessages responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListMessagesResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/apps': parameters: - $ref: "#/components/parameters/project_id" get: description: Get a list of all apps in the specified project. tags: - App summary: List all apps for a given project operationId: App_ListApps responses: "200": $ref: "#/components/responses/listAppsResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" post: tags: - App summary: Create an app description: You can create a new Conversation API app using the API. You can create an app for one or more channels at once. The ID of the app is generated at creation and will be returned in the response. operationId: App_CreateApp requestBody: $ref: "#/components/requestBodies/CreateAppRequest" responses: "200": $ref: "#/components/responses/createAppResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/apps/{app_id}': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/app_id" get: tags: - App summary: Get an app description: Returns a particular app as specified by the App ID. operationId: App_GetApp responses: "200": $ref: "#/components/responses/getAppResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" delete: tags: - App summary: Delete an app description: Deletes a particular app as specified by the App ID. operationId: App_DeleteApp responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" patch: tags: - App summary: Update an app description: Updates a particular app as specified by the App ID. operationId: App_UpdateApp parameters: - $ref: '#/components/parameters/update_mask.paths' requestBody: $ref: "#/components/requestBodies/UpdateAppRequest" responses: "200": $ref: "#/components/responses/updateAppResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/apps/{app_id}/webhooks': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/app_id" get: description: List all webhooks for a given app as specified by the App ID. tags: - Webhooks summary: List webhooks operationId: Webhooks_ListWebhooks responses: "200": $ref: "#/components/responses/listWebhooksResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/capability:query': parameters: - $ref: "#/components/parameters/project_id" post: description: This method is asynchronous - it immediately returns the requested Capability registration. Capability check is then delivered as a callback to registered webhooks with trigger CAPABILITY for every reachable channel. tags: - Capability summary: Capability lookup operationId: Capability_QueryCapability requestBody: $ref: "#/components/requestBodies/QueryCapabilityRequest" responses: "200": $ref: "#/components/responses/queryCapabilityResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/contacts': parameters: - $ref: "#/components/parameters/project_id" get: description: List all contacts in the project. tags: - Contact summary: List contacts operationId: Contact_ListContacts parameters: - description: |- Optional. The maximum number of contacts to fetch. The default is 10 and the maximum is 20. name: page_size in: query schema: type: integer format: int32 - description: Optional. Next page token previously returned if any. name: page_token in: query schema: type: string responses: "200": $ref: "#/components/responses/listContactsResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" post: tags: - Contact summary: Create a Contact description: You can create a new contact operationId: Contact_CreateContact requestBody: $ref: "#/components/requestBodies/CreateContactRequest" responses: "200": $ref: "#/components/responses/createContactResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/contacts/{contact_id}': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/contact_id" get: description: Returns a specific contact as specified by the contact ID. tags: - Contact summary: Get a Contact operationId: Contact_GetContact responses: "200": $ref: "#/components/responses/getContactResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" delete: description: Delete a contact as specified by the contact ID. tags: - Contact summary: Delete a Contact operationId: Contact_DeleteContact responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" patch: description: Updates a contact as specified by the contact ID. tags: - Contact summary: Update a Contact operationId: Contact_UpdateContact parameters: - $ref: '#/components/parameters/update_mask.paths' requestBody: $ref: "#/components/requestBodies/UpdateContactRequest" responses: "200": $ref: "#/components/responses/updateContactResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/contacts/{destination_id}:merge': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/destination_id" post: description: |- The remaining contact will contain all conversations that the removed contact did. If both contacts had conversations within the same App, messages from the removed contact will be merged into corresponding active conversations in the destination contact. Channel identities will be moved from the source contact to the destination contact only for channels that weren't present there before. Moved channel identities will be placed at the bottom of the channel priority list. Optional fields from the source contact will be copied only if corresponding fields in the destination contact are empty The contact being removed cannot be referenced after this call. tags: - Contact summary: Merge two contacts operationId: Contact_MergeContact requestBody: $ref: "#/components/requestBodies/MergeContactRequest" responses: "200": $ref: "#/components/responses/mergeContactResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/contacts:getChannelProfile': parameters: - $ref: "#/components/parameters/project_id" post: description: |- Get user profile from a specific channel. Supported only on `MESSENGER`, `INSTAGRAM`, and `VIBER` channels. tags: - Contact summary: Get Channel Profile operationId: Contact_GetChannelProfile requestBody: $ref: "#/components/requestBodies/GetChannelProfileRequest" responses: "200": $ref: "#/components/responses/getChannelProfileResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/conversations': parameters: - $ref: "#/components/parameters/project_id" get: description: This operation lists all conversations that are associated with an app and/or a contact. tags: - Conversation summary: List conversations operationId: Conversation_ListConversations parameters: - $ref: '#/components/parameters/query_app_id' description: At least one of `app_id` or `contact_id` must be present. - $ref: '#/components/parameters/query_contact_id' description: At least one of `app_id` or `contact_id` must be present. - description: Required. True if only active conversations should be listed. name: only_active in: query schema: type: boolean required: true - description: The maximum number of conversations to fetch. Defaults to 10 and the maximum is 20. name: page_size in: query schema: type: integer format: int32 - description: Next page token previously returned if any. name: page_token in: query schema: type: string responses: "200": $ref: "#/components/responses/listConversationsResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" post: description: |- Creates a new empty conversation. It is generally not needed to create a conversation explicitly since sending or receiving a message automatically creates a new conversation if it does not already exist between the given app and contact. Creating empty conversation is useful if the metadata of the conversation should be populated when the first message in the conversation is a contact message or the first message in the conversation comes out-of-band and needs to be injected with InjectMessage endpoint. tags: - Conversation summary: Create a conversation operationId: Conversation_CreateConversation requestBody: $ref: "#/components/requestBodies/CreateConversationRequest" responses: "200": $ref: "#/components/responses/createConversationResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/conversations/{conversation_id}': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/conversation_id" get: description: |- Retrieves a conversation by id. A conversation has two participating entities, an app and a contact. tags: - Conversation summary: Get a conversation operationId: Conversation_GetConversation responses: "200": $ref: "#/components/responses/getConversationResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" delete: description: Deletes a conversation together with all the messages sent as part of the conversation. tags: - Conversation summary: Delete a conversation operationId: Conversation_DeleteConversation responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" patch: description: |- This operation updates a conversation which can, for instance, be used to update the metadata associated with a conversation. tags: - Conversation summary: Update a conversation operationId: Conversation_UpdateConversation parameters: - $ref: '#/components/parameters/update_mask.paths' - description: Update strategy for the `conversation_metadata` field. name: metadata_update_strategy in: query schema: x-enumDescriptions: REPLACE: The default strategy. Replaces the whole `conversation_metadata` field with the new value provided. MERGE_PATCH: Patches the `conversation_metadata` field with the patch provided according to RFC 7386. default: REPLACE type: string required: false requestBody: $ref: "#/components/requestBodies/UpdateConversationRequest" responses: "200": $ref: "#/components/responses/getConversationResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/conversations/{conversation_id}:stop': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/conversation_id" post: description: |- This operation stops the referenced conversation, if the conversation is still active. A new conversation will be created if a new message is exchanged between the app or contact that was part of the stopped conversation. tags: - Conversation summary: Stop conversation operationId: Conversation_StopActiveConversation responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/conversations/{message.conversation_id}:inject-message': parameters: - $ref: '#/components/parameters/project_id' - description: Required. The ID of the conversation. name: message.conversation_id in: path required: true schema: type: string post: description: This operation injects a conversation message in to a specific conversation. tags: - Conversation summary: Inject messages operationId: Conversation_InjectMessage requestBody: $ref: "#/components/requestBodies/InjectMessageRequest" responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" /v1/projects/{project_id}/events:send: parameters: - $ref: "#/components/parameters/project_id" post: description: |- Sends an event to the referenced contact from the referenced app. Note that this operation enqueues the event in a queues so a successful response only indicates that the event has been queued. tags: - Events summary: Send an event operationId: Events_SendEvent requestBody: description: The event to be sent. content: application/json: schema: $ref: "#/components/schemas/SendEventRequest" required: true responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/SendEventResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/messages:transcode': parameters: - $ref: "#/components/parameters/project_id" post: description: |- Transcodes the message from the Conversation API format to the channel-specific formats for the requested channels. No message is sent to the contact. tags: - Transcoding summary: Transcode a message operationId: Transcoding_TranscodeMessage requestBody: description: The message to be transcoded, and the app and channels for which the message is to be transcoded. content: application/json: schema: $ref: "#/components/schemas/TranscodeMessageRequest" required: true responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/TranscodeMessageResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/optins:register': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/request_id" post: description: |- This method is asynchronous - it returns immediately the requested OptIn registration with any defaults resolved. All changes of the actual opt-in status are then delivered as callbacks to registered webhooks with trigger OPT_IN. tags: - OptIn & OptOut summary: Register an opt-in operationId: OptIn_RegisterOptIn requestBody: description: The opt-in request. content: application/json: schema: $ref: "#/components/schemas/OptIn" required: true responses: "200": $ref: "#/components/responses/OptInResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/optouts:register': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/request_id" post: description: |- This method is asynchronous - it returns immediately the requested OptOut registration with any defaults resolved. All changes of the actual opt-out status are then delivered as callbacks to registered webhooks with trigger OPT_OUT. tags: - OptIn & OptOut summary: Register an opt-out operationId: OptIn_RegisterOptOut requestBody: $ref: "#/components/requestBodies/registerOptOutRequest" responses: "200": $ref: "#/components/responses/OptOutResponse" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/webhooks': parameters: - $ref: "#/components/parameters/project_id" post: description: |- Creates a webhook for receiving callbacks on specific triggers. You can create up to 5 webhooks per app. tags: - Webhooks summary: Create a new webhook operationId: Webhooks_CreateWebhook requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook" description: Required. The Webhook to create required: true responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Webhook" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" '/v1/projects/{project_id}/webhooks/{webhook_id}': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/webhook_id" get: description: Get a webhook as specified by the webhook ID. tags: - Webhooks summary: Get a webhook operationId: Webhooks_GetWebhook responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Webhook" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" patch: description: Updates an existing webhook as specified by the webhook ID. tags: - Webhooks summary: Update an existing webhook operationId: Webhooks_UpdateWebhook parameters: - $ref: "#/components/parameters/update_mask.paths" requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook" description: Required. The Webhook to update required: true responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Webhook" "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" delete: description: Deletes a webhook as specified by the webhook ID. tags: - Webhooks summary: Delete an existing webhook operationId: Webhooks_DeleteWebhook responses: "200": description: A successful response. content: application/json: schema: {} "400": $ref: "#/components/responses/400Error" "401": $ref: "#/components/responses/401Error" "403": $ref: "#/components/responses/403Error" "500": $ref: "#/components/responses/500Error" "501": $ref: "#/components/responses/501Error" tags: - description: |- To start sending messages you must have a Conversation API [**app**](https://dashboard.sinch.com/convapi/apps). The app holds information about the channel credentials and registered webhooks to which the API delivers callbacks such as message delivery reports and contact messages. If you don't already have an app please follow the instructions in the getting started guide available in the [Sinch Dashboard](https://dashboard.sinch.com/convapi/getting-started) to create one. name: Messages - description: |- Apps are created and configured through the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps), are tied to the API user and come with a set of **channel credentials** for each underlying connected channel. The app has a list of **conversations** between itself and different **contacts** which share the same **project**. Webhooks, which the app is attached to, defines the destination for various events coming from the Conversation API. An **app** has the following configurable properties: | Field | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Display name | The name visible in the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps). | | Conversation metadata report | Specifies the amount of **conversation**metadata that's returned as part of each callback. | | Retention Policy | The retention policy specifies how long messages, sent to or from an **app**, are stored by the Conversation API. | name: App - description: |- A contact is a collection that groups together underlying connected **channel recipient identities**. It's tied to a specific **project** and is therefore considered public to all **apps** sharing the same **project**. A **contact** has the following configurable properties: | Field | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Channel identities | List of channel identities specifying how the contact is identified on underlying channels | | Channel priority | Specifies the channel priority order used when sending messages to this contact. This can be overridden by message specific channel priority order. | | Display name | Optional display name used in chat windows and other UIs | | Email | Optional Email of the contact | | External id | Optional identifier of the contact in external systems | | Metadata | Optional metadata associated with the contact. | name: Contact - description: Endpoints for working with the conversation log. name: Conversation - description: Endpoint for sending events. name: Events - description: Endpoint for transcoding generic message format to channel-specific one. name: Transcoding - description: |- By using the Opt-in & Opt-out service, it's possible to register an opt-in or an opt-out event for a [**contact**](/docs/conversation/keyconcepts#contact) with the underlying channel. In order to execute the request, either the contactId of the contact or its channel recipient identities are required. Requests are executed asynchronously, therefore the endpoint immediately returns the registered request. The result of the Opt-in or Opt-out request is posted to the webhook which has an OPT_IN or OPT_OUT trigger respectively. To read more about setting up webhooks go to [**Webhooks**](/docs/conversation/keyconcepts#webhook). name: OptIn & OptOut - description: |- A Capability Query means checking the available options to reach the contact on the channels where it has a channel identity. Capability Queries can only be executed for contacts that already exist in a project/app. For executing the request, it's required to provide either the contactId or the channel recipient identities of the contact. The request is executed asynchronously, therefore the service responds immediately. The result of the Capability Query is sent to the registered webhook for the CAPABILITY trigger. name: Capability x-explorer-enabled: false x-samples-languages: - curl - java - csharp - node - php components: parameters: # path 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 app_id: name: app_id description: The unique ID of the app. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps). in: path required: true schema: type: string contact_id: name: contact_id description: The unique ID of the contact. in: path required: true schema: type: string webhook_id: name: webhook_id description: The unique ID of the webhook. in: path required: true schema: type: string destination_id: name: destination_id description: The unique ID of the contact that should be kept when merging two contacts. in: path required: true schema: type: string conversation_id: name: conversation_id description: The unique ID of the conversation. This is generated by the system. in: path required: true schema: type: string message_id: name: message_id description: The unique ID of the message. in: path required: true schema: type: string # query parameters query_app_id: description: The ID of the app involved in the conversations. name: app_id in: query schema: type: string query_conversation_id: description: Resource name (ID) of the conversation. name: conversation_id in: query schema: type: string query_contact_id: name: contact_id description: Resource name (ID) of the contact. in: query schema: type: string messages_source: name: messages_source description: Specifies the message source for which the request will be processed. Used for operations on messages in Dispatch Mode. For more information, see [Processing Modes](../../../../processing-modes/). in: query schema: x-enumDescriptions: CONVERSATION_SOURCE: The default messages source. Retrieves messages sent in the default `CONVERSATION` processing mode, which associates the messages with a specific conversation and contact. DISPATCH_SOURCE: Retrieves messages sent in the `DISPATCH` processing mode. These types of messages are not associated with any conversation or contact. default: CONVERSATION_SOURCE type: string only_recipient_originated: description: If true, fetch only recipient originated messages. Available only when `messages_source` is `DISPATCH_SOURCE`. name: only_recipient_originated in: query schema: type: boolean update_mask.paths: description: The set of field mask paths. name: update_mask.paths in: query explode: true schema: type: array items: type: string request_id: description: ID for the asynchronous request, will be generated if not set. Currently this field is not used for idempotency but it will be added in v1. name: request_id in: query schema: type: string examples: createFacebookApp: summary: Create Facebook App value: channel_credentials: - channel: MESSENGER static_token: token: "{Facebook_Token}" display_name: Demo Facebook App createSMSApp: summary: Create SMS App value: channel_credentials: - channel: SMS static_bearer: claimed_identity: "{Service_Plan_Id}" token: "{API_Token}" display_name: Demo SMS App createWhatsAppApp: summary: Create WhatsApp App value: channel_credentials: - channel: WHATSAPP static_bearer: claimed_identity: "{WhatsApp_Sender_ID}" token: "{WhatsApp_Bearer_Token}" display_name: Demo WhatsApp App sendMessageContactId: summary: Send message with Contact ID recipient value: app_id: "{APP_ID}" recipient: contact_id: "{CONTACT_ID}" message: text_message: text: "This is a text message." sendMessageIdentifiedBy: summary: Send message with Identified_By recipient value: app_id: "{APP_ID}" recipient: identified_by: channel_identities: - channel: "{CHANNEL}" identity: "{IDENTITY}" message: text_message: text: "This is a text message." createContactWithOneChannel: summary: Create new contact with only one channel value: channel_identities: - channel: "WHATSAPP" identity: "{{WHATSAPP_PHONE_NUMBER}}" language: "EN_US" display_name: "New Contact" email: "new.contact@email.com" createContactWithManyChannels: summary: Create new contact with multiple channels value: channel_identities: - channel: "MESSENGER" identity: "{{FACEBOOK_USER_NAME}}" app_id: "{{APP_ID}}" - channel: "SMS" identity: "{{PHONE_NUMBER}}" - channel: "VIBER" identity: "{{PHONE_NUMBER}}" app_id: "{{APP_ID}}" channel_priority: - "MESSENGER" - "VIBER" - "SMS" language: "EN_US" display_name: "New Contact" email: "new.contact@email.com" updateApp: summary: Update app value: channel_credentials: - channel: "WHATSAPP" static_bearer: claimed_identity: "{{WhatsApp_Sender_Id}}" token: "{{WhatsApp_Bearer_Token}}" callback_secret: "{{Callback_Secret_1}}" - channel: "MESSENGER" static_token: token: "{{Facebook_Token}}" callback_secret: "{{Callback_Secret_2}}" - channel: "SMS" static_bearer: claimed_identity: "{{Service_Plan_Id}}" token: "{{API_Token}}" display_name: "New App Display Name" CardMessage: summary: Card message description: An example payload of a card message. value: app_id: "{{APP_ID}}" recipient: contact_id: "{{CONTACT_ID}}" message: card_message: title: Sign up for our newsletter description: Our weekly newsletter with deals and extra content! media_message: url: "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png" choices: - text_message: text: "Sign up here" CarouselMessage: summary: Carousel message description: An example payload of a carousel message. value: app_id: "{{APP_ID}}" recipient: "{{CONTACT_ID}}" message: carousel_message: cards: - title: Sign up for our weekly newsletter description: Our weekly newsletter is filled with deals and extra content! media_message: url: "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png" choices: - text_message: text: Sign up here - title: Visit our website description: You can view your account and place orders from our convenient dashboard. media_message: url: "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png" choices: - url_message: title: Website url: "https://www.sinch.com" - title: Call our customer support line description: Our dedicated support staff can answer your questions and concerns. media_message: url: "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png" choices: - call_message: title: Support line phone_number: "46732000000" ChoiceMessage: summary: Choice message description: An example payload of a choice message. value: app_id: "{{APP_ID}}" recipient: contact_id: "{{CONTACT_ID}}" message: choice_message: text_message: text: Friendly reminder of your appointment tomorrow at 10AM. Please confirm your booking by replying below. choices: - text_message: text: Confirm - text_message: text: Cancel LocationMessage: summary: Location message description: An example payload of a location message. value: app_id: "{{APP_ID}}" recipient: "{{CONTACT_ID}}" message: location_message: title: Your ride is here! label: Meet your driver at the specified address. coordinates: latitude: 55.610479 longitude: 13.002873 MediaMessage: summary: Media message description: An example message of a media message. value: app_id: "{{APP_ID}}" recipient: "{{CONTACT_ID}}" message: media_message: url: "{{URL_TO_MEDIA}}" TextMessage: summary: Text message description: An example message of a text message. value: app_id: "{{APP_ID}}" recipient: "{{CONTACT_ID}}" message: text_message: text: Greetings from Sinch Conversation API. ListMessage: summary: List message with choices description: An example message of a list message with choices value: app_id: "{{APP_ID}}" recipient: contact_id: "{{CONTACT}}" message: list_message: title: "Choose your icecream flavor" description: "The best icecream in town!" sections: - title: "Fruit flavors" items: - choice: title: "Strawberry" postback_data: "Strawberry postback" - choice: title: "Blueberry" postback_data: "Blueberry postback" - title: "Other flavors" items: - choice: title: "Chocolate" postback_data: "Chocolate postback" - choice: title: "Vanilla" postback_data: "Vanilla postback" message_properties: menu: "This is the menu text" ProductMessage: summary: List message with products description: An example message of a list message with products value: app_id: "{{APP_ID}}" recipient: contact_id: "{{CONTACT}}" message: list_message: title: "Title for the list message with products" description: "Description (or subtitle) for list message with products" sections: - title: "Facebook product catalog item set name" items: - product: id: "product_1_id" marketplace: "FACEBOOK" - product: id: "product_2_id" marketplace: "FACEBOOK" message_properties: catalog_id: "id_of_catalog" responses: 400Error: description: Malformed request content: application/json: schema: $ref: "#/components/schemas/runtimeError" example: code: 400 message: Malformed request status: INVALID_REQUEST details: [] 401Error: description: Incorrect credentials content: application/json: schema: $ref: "#/components/schemas/runtimeError" example: code: 401 message: Request had invalid credentials. status: UNAUTHENTICATED details: [] 403Error: description: Correct credentials but you don't have access to the requested resource content: application/json: schema: $ref: "#/components/schemas/runtimeError" example: code: 403 message: You do not have access to the requested resource. status: UNAUTHORIZED details: [] 500Error: description: Correct credentials but you don't have access to the requested resource content: application/json: schema: $ref: "#/components/schemas/runtimeError" example: code: 500 message: There was an internal server error. status: INTERNAL_ERROR details: [] 501Error: description: Something went wrong on our end, try again with exponential back-off content: application/json: schema: $ref: "#/components/schemas/runtimeError" example: code: 501 message: There was an internal server error. status: INTERNAL_ERROR details: [] sendMessageResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/SendMessageResponse" getMessageResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ConversationMessage" createAppResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/AppResponse" createContactResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Contact" createConversationResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Conversation" getAppResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/AppResponse" getContactResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Contact" getConversationResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Conversation" updateAppResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/AppResponse" updateContactResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Contact" listAppsResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListAppsResponse" listContactsResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListContactsResponse" listConversationsResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListConversationsResponse" listWebhooksResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListWebhooksResponse" mergeContactResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Contact" getChannelProfileResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/GetChannelProfileResponse" OptOutResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/OptOutResponse" OptInResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/OptInResponse" queryCapabilityResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/QueryCapabilityResponse" requestBodies: CreateAppRequest: content: application/json: schema: $ref: "#/components/schemas/AppCreateRequest" examples: createFacebookApp: $ref: "#/components/examples/createFacebookApp" createWhatsAppApp: $ref: "#/components/examples/createWhatsAppApp" createSMSApp: $ref: "#/components/examples/createSMSApp" description: The app to create. required: true CreateContactRequest: content: application/json: schema: $ref: "#/components/schemas/ContactCreateRequest" examples: createContactOneChannel: $ref: "#/components/examples/createContactWithOneChannel" createContactMultipleChannels: $ref: "#/components/examples/createContactWithManyChannels" description: The contact to create. required: true CreateConversationRequest: content: application/json: schema: $ref: "#/components/schemas/Conversation" description: The conversation to create. ID will be generated for the conversation and any ID in the given conversation will be ignored. required: true InjectMessageRequest: content: application/json: schema: $ref: "#/components/schemas/ConversationMessageInjected" description: Message to be injected. required: true MergeContactRequest: content: application/json: schema: $ref: "#/components/schemas/MergeContactRequest" description: The contact to be removed. required: true GetChannelProfileRequest: content: application/json: schema: $ref: "#/components/schemas/GetChannelProfileRequest" required: true QueryCapabilityRequest: content: application/json: schema: $ref: "#/components/schemas/QueryCapability" description: The query capability request. required: true UpdateAppRequest: content: application/json: schema: $ref: "#/components/schemas/AppUpdateRequest" examples: updateApp: $ref: "#/components/examples/updateApp" description: The updated app. required: true UpdateContactRequest: content: application/json: schema: $ref: "#/components/schemas/Contact" description: The updated contact. required: true UpdateConversationRequest: content: application/json: schema: $ref: "#/components/schemas/Conversation" description: The updated conversation. required: true SendMessageRequest: description: This is the request body for sending a message. `app_id`, `recipient`, and `message` are all required fields. content: application/json: schema: $ref: "#/components/schemas/SendMessageRequest" examples: ContactId: $ref: "#/components/examples/sendMessageContactId" IdentifiedBy: $ref: "#/components/examples/sendMessageIdentifiedBy" required: true registerOptOutRequest: description: The opt-out request. content: application/json: schema: $ref: "#/components/schemas/OptOut" required: true schemas: protobufAny: type: object properties: type_url: type: string value: type: string format: byte runtimeError: type: object properties: code: type: integer format: int32 details: type: array items: $ref: "#/components/schemas/protobufAny" error: type: string message: type: string status: type: string AppCreateRequest: description: |- The request sent to the API endpoint to create a new app. type: object title: Conversation API app required: - display_name - channel_credentials properties: channel_credentials: description: An array of channel credentials. The order of the credentials defines the app channel priority. type: array items: $ref: "#/components/schemas/ConversationChannelCredential" conversation_metadata_report_view: $ref: "#/components/schemas/ConversationMetadataReportView" display_name: description: The display name for the app. type: string example: Sinch Conversation API Demo App 001 retention_policy: $ref: "#/components/schemas/RetentionPolicy" dispatch_retention_policy: $ref: "#/components/schemas/DispatchRetentionPolicy" processing_mode: $ref: "#/components/schemas/ProcessingMode" smart_conversation: $ref: "#/components/schemas/SmartConversation" AppUpdateRequest: description: |- The request sent to the API endpoint to update the configuration of an app. type: object title: Conversation API app required: - display_name properties: channel_credentials: description: An array of channel credentials. The order of the credentials defines the app channel priority. type: array items: $ref: "#/components/schemas/ConversationChannelCredential" conversation_metadata_report_view: $ref: "#/components/schemas/ConversationMetadataReportView" display_name: description: The display name for the app. type: string example: Sinch Conversation API Demo App 001 retention_policy: $ref: "#/components/schemas/RetentionPolicy" dispatch_retention_policy: $ref: "#/components/schemas/DispatchRetentionPolicy" processing_mode: $ref: "#/components/schemas/ProcessingMode" smart_conversation: $ref: "#/components/schemas/SmartConversation" AppResponse: description: |- The response showing information about the app. type: object title: Conversation API app properties: channel_credentials: description: An array of channel credentials. The order of the credentials defines the app channel priority. type: array items: $ref: "#/components/schemas/ConversationChannelCredential" conversation_metadata_report_view: $ref: "#/components/schemas/ConversationMetadataReportView" display_name: description: The display name for the app. type: string example: Sinch Conversation API Demo App 001 id: description: The ID of the app. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps). type: string example: "{APP_ID}" rate_limits: $ref: "#/components/schemas/RateLimits" retention_policy: $ref: "#/components/schemas/RetentionPolicy" dispatch_retention_policy: $ref: "#/components/schemas/DispatchRetentionPolicy" processing_mode: $ref: "#/components/schemas/ProcessingMode" smart_conversation: $ref: "#/components/schemas/SmartConversation" AppMessage: type: object description: Message originating from an app properties: message: oneOf: - $ref: "#/components/schemas/CardMessage" - $ref: "#/components/schemas/CarouselMessage" - $ref: "#/components/schemas/ChoiceMessage" - $ref: "#/components/schemas/LocationMessage" - $ref: "#/components/schemas/MediaMessage" - $ref: "#/components/schemas/TemplateMessage" - $ref: "#/components/schemas/TextMessage" - $ref: "#/components/schemas/ListMessage" explicit_channel_message: description: |- Optional. Channel specific messages, overriding any transcoding. The key in the map must point to a valid conversation channel as defined by the enum ConversationChannel. type: object additionalProperties: type: object description: Additional properties of the message. properties: contact_name: type: string description: The `display_name` of the newly created contact in case it doesn't exist. BasicAuthCredential: description: It consists of a username and a password. type: object required: - "password" - "username" title: Basic Auth Credential properties: password: description: Basic auth password. type: string username: description: Basic auth username. type: string CallMessage: description: Message for triggering a call. type: object title: Call Message 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. The title is clickable in some cases. type: string example: Message text CardHeight: description: You can set the desired size of the card in the message. type: string enum: - UNSPECIFIED_HEIGHT - SHORT - MEDIUM - TALL CardMessage: description: "Message containing text, media and choices." type: object title: Card Message required: - title properties: choices: description: You may include choices in your Card Message. The number of choices is limited to 3. 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" media_message: $ref: "#/components/schemas/MediaCarouselMessage" title: description: The title field is required. type: string CarouselMessage: description: Message containing a list of cards often rendered horizontally on supported channels. Supported types for media are only images, such as .png, .jpg, .jpeg extensions. type: object title: Carousel Message 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" ChannelIdentities: required: - "channel_identities" type: object properties: channel_identities: description: |- A list of specific channel identities. The API will use these identities when sending to specific channels. type: array items: $ref: "#/components/schemas/ChannelRecipientIdentity" ChannelIdentity: description: |- A unique identity of message recipient on a particular channel. For 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, Viber Bot, Instagram, Apple Messages for Business, 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 ChannelRecipientIdentity: type: object required: - "identity" - "channel" properties: channel: $ref: "#/components/schemas/ConversationChannel" identity: description: The channel recipient identity. type: string 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 properties: call_message: $ref: "#/components/schemas/CallMessage" location_message: $ref: "#/components/schemas/LocationMessage" postback_data: description: An optional field. This data will be returned in the ChoiceResponseMessage. The default is message_id_{text, title}. type: string text_message: $ref: "#/components/schemas/TextMessage" url_message: $ref: "#/components/schemas/UrlMessage" ChoiceMessage: description: Message containing choices/actions. type: object title: Choice Message required: - "choices" properties: choices: description: The number of choices is limited to 3. type: array items: $ref: "#/components/schemas/Choice" text_message: $ref: "#/components/schemas/TextMessage" ChoiceResponseMessage: description: Represents a response to a choice message. type: object title: Choice Response Message required: - "message_id" - "postback_data" properties: message_id: description: The message id containing the choice. type: string postback_data: description: The postback_data defined in the selected choice. type: string ClientCredentials: type: object required: - "client_id" - "client_secret" - "endpoint" properties: client_id: description: The Client ID that will be used in the Client Credentials flow. type: string client_secret: description: The Client Secret that will be used in the Client Credentials flow. type: string endpoint: description: The endpoint that will be used in the Client Credentials flow. type: string CommentReplyEvent: description: Represents a response to a comment event. type: object title: Comment Reply Event required: - "text" properties: text: description: The text of the comment reply. type: string ComposingEvent: type: object description: An empty object. Represents a typing indicator. ContactCreateRequest: description: A participant in a conversation typically representing a person. It is associated with a collection of channel identities. type: object title: Contact 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 Contact: description: A participant in a conversation typically representing a person. It is associated with a collection of channel identities. type: object title: Contact properties: channel_identities: description: List of channel identities. type: array items: $ref: "#/components/schemas/ChannelIdentity" channel_priority: description: List of channels defining the channel priority. 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 id: description: The ID of the contact. type: string example: "{CONTACT_ID}" language: $ref: "#/components/schemas/ContactLanguage" metadata: description: Metadata associated with the contact. Up to 1024 characters long. type: string Contact_Id: description: The ID of the contact. type: string example: "{CONTACT_ID}" ContactLanguage: type: string 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 ContactMessage: description: Message originating from a contact type: object title: Message originating from a contact properties: choice_response_message: $ref: "#/components/schemas/ChoiceResponseMessage" fallback_message: $ref: "#/components/schemas/FallbackMessage" location_message: $ref: "#/components/schemas/LocationMessage" media_card_message: $ref: "#/components/schemas/MediaCardMessage" media_message: $ref: "#/components/schemas/MediaMessage" reply_to: $ref: "#/components/schemas/ReplyTo" text_message: $ref: "#/components/schemas/TextMessage" Conversation: description: |- A collection of messages exchanged between a contact and an app. Conversations are normally created on the fly by Conversation API once a message is sent and there is no active conversation already. There can be only one active conversation at any given time between a particular contact and an app. type: object title: Conversation properties: active: description: Flag for whether this conversation is active. type: boolean active_channel: $ref: "#/components/schemas/ConversationChannel" app_id: description: The ID of the participating app. type: string contact_id: description: The ID of the participating contact. type: string id: description: The ID of the conversation. type: string last_received: description: |- The timestamp of the latest message in the conversation. The timestamp will be Thursday January 01, 1970 00:00:00 UTC if the conversation contains no messages. type: string format: date-time readOnly: true metadata: description: |- Arbitrary data set by the Conversation API clients. Up to 1024 characters long. type: string metadata_json: description: |- Arbitrary data set by the Conversation API clients and/or provided in the `conversation_metadata` field of a SendMessageRequest. A valid JSON object. type: object 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 enum: - WHATSAPP - RCS - SMS - MESSENGER - VIBER - VIBERBM - MMS - INSTAGRAM - TELEGRAM - KAKAOTALK - LINE - WECHAT GetChannelProfileConversationChannel: type: string title: Channel Identifier description: The channel. Must be one of the supported channels for this operation. example: MESSENGER enum: - MESSENGER - INSTAGRAM - VIBER ConversationChannelCredential: description: Enables access to the underlying messaging channel. type: object title: Channel Credential required: - channel properties: callback_secret: description: |- The secret used to verify the channel callbacks for channels which support callback verification. The callback verification is not needed for Sinch-managed channels because the callbacks are not leaving Sinch internal networks. Max length is 256 characters. Note: leaving channel_callback_secret empty for channels with callback verification will disable the verification. type: string channel: $ref: "#/components/schemas/ConversationChannel" mms_credentials: $ref: "#/components/schemas/MMSCredentials" kakaotalk_credentials: $ref: "#/components/schemas/KakaoTalkCredentials" static_bearer: $ref: "#/components/schemas/StaticBearerCredential" static_token: $ref: "#/components/schemas/StaticTokenCredential" telegram_credentials: $ref: "#/components/schemas/TelegramCredentials" line_credentials: $ref: "#/components/schemas/LineCredentials" wechat_credentials: $ref: "#/components/schemas/WeChatCredentials" ConversationDirection: type: string default: UNDEFINED_DIRECTION enum: - UNDEFINED_DIRECTION - TO_APP - TO_CONTACT ConversationMergeStrategy: type: string default: MERGE enum: - MERGE ConversationMessageInjected: description: A message on a particular channel. type: object title: Conversation Message Injected properties: accept_time: description: The processed time of the message in UTC timezone. Must be less than current_time and greater than (current_time - 30 days) type: string format: date-time app_message: $ref: "#/components/schemas/AppMessage" channel_identity: $ref: "#/components/schemas/ChannelIdentity" contact_id: description: The ID of the contact registered in the conversation provided. type: string contact_message: $ref: "#/components/schemas/ContactMessage" direction: $ref: "#/components/schemas/ConversationDirection" metadata: description: |- Optional. Metadata associated with the contact. Up to 1024 characters long. type: string ConversationMessage: description: A message on a particular channel. type: object title: Conversation Message properties: accept_time: description: The time Conversation API processed the message. type: string format: date-time readOnly: true app_message: $ref: "#/components/schemas/AppMessage" channel_identity: $ref: "#/components/schemas/ChannelIdentity" contact_id: description: The ID of the contact. type: string contact_message: $ref: "#/components/schemas/ContactMessage" conversation_id: description: The ID of the conversation. type: string direction: $ref: "#/components/schemas/ConversationDirection" id: description: The ID of the message. type: string metadata: description: |- Optional. Metadata associated with the contact. Up to 1024 characters long. type: string injected: description: Flag for whether this message was injected. type: boolean readOnly: true ConversationMetadataReportView: type: string default: NONE enum: - NONE - FULL 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 FallbackMessage: description: Fallback message. Used when original contact message can not be handled. type: object title: Fallback Message properties: raw_message: description: Optional. The raw fallback message if provided by the channel. type: string reason: $ref: "#/components/schemas/Reason" Identified_By: type: object description: The identity as specified by the channel. required: - channel_identities properties: channel_identities: type: array items: $ref: "#/components/schemas/ChannelIdentity" KakaoTalkCredentials: type: object title: MMS channel credential required: - kakaotalk_plus_friend_id - kakaotalk_sender_key description: If you are including the KakaoTalk channel in the `channel_identifier` property, you must include this object. properties: kakaotalk_plus_friend_id: description: KakaoTalk Business Channel ID. type: string kakaotalk_sender_key: description: KakaoTalk Sender Key. type: string LocationMessage: type: object description: Message containing geographic location. title: Location message 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 MMSCredentials: type: object title: MMS channel credential required: - account_id - api_key description: If you are including the MMS channel in the `channel_identifier` property, you must include this object. properties: account_id: description: MMS Account ID. type: string api_key: description: MMS API Key. type: string basic_auth: $ref: "#/components/schemas/BasicAuthCredential" MediaCarouselMessage: type: object title: Media message description: A message containing an image media component. required: - url properties: caption: description: "Caption for the media on supported channels." type: string url: description: Url to the media file. type: string MediaCardMessage: type: object title: Media message description: A message containing a media component, such as an image or video. required: - url properties: caption: description: "Caption for the media on supported channels." type: string url: description: Url to the media file. type: string MediaMessage: type: object title: Media message description: A message containing a media component, such as an image, document, or video. 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 ChoiceItem: type: object title: Choice Item 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: type: object description: Optional parameter. The media of this choice item. $ref: "#/components/schemas/MediaMessage" 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 Item 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 required: - item properties: item: type: object description: "Item information" oneOf: - type: object title: choice properties: choice: $ref: "#/components/schemas/ChoiceItem" - type: object title: product properties: product: $ref: "#/components/schemas/ProductItem" ListSection: type: object title: List Section description: Section for interactive whatsapp messages containing ListItem required: - listItem properties: title: description: "Optional parameter. Title for list section." type: string items: type: array items: $ref: "#/components/schemas/ListItem" ListMessage: type: object title: List Message description: A message containing a list of options to choose from 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 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 MessageQueue: type: string description: Not yet supported. This field is for future use. default: NORMAL_PRIORITY example: NORMAL_PRIORITY enum: - NORMAL_PRIORITY - HIGH_PRIORITY OptInResponse: description: The response received for an Opt-In request. type: object properties: opt_in: $ref: "#/components/schemas/OptIn" request_id: type: string description: "ID for the asynchronous request, will be generated id if not set in request" OptIn: description: |- An Opt-In contains the identity of the recipient which gave its consent to receive messages from Conversation API apps on a given channel. type: object title: Represents an explicit Opt-In registration required: - "app_id" - "channels" - "recipient" properties: app_id: description: The app for which the Opt-In is being registered. type: string example: "{APP_ID}" channels: description: |- The channels covered by this Opt-In. The default are all the channels for a contact if recipient is contact_id or the channels in the channel_identities list. type: array items: $ref: "#/components/schemas/ConversationChannel" recipient: type: object description: The recipient to opt-in. Requires either `contact_id` or `identified_by`. If [Dispatch Mode](../../../../processing-modes/) is used, only `identified_by` is allowed. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" example: contact_id: "{CONTACT_ID}" processing_strategy: $ref: "#/components/schemas/ProcessingStrategy" OptOutResponse: description: The response received for an Opt-Out request. type: object properties: opt_out: $ref: "#/components/schemas/OptOut" request_id: type: string description: "ID for the asynchronous request, will be generated id if not set in request" OptOut: description: |- An Opt-Out contains the identity of the recipient which retract its consent to receive messages from Conversation API apps on a given channel. type: object title: Represents an explicit Opt-Out registration required: - "app_id" - "channels" - "recipient" properties: app_id: description: The app for which the Opt-Out is being registered. type: string example: "{APP_ID}" channels: description: |- The channels covered by this Opt-Out. The default are all the channels for a contact if recipient is contact_id or the channels in the channel_identities list. type: array items: $ref: "#/components/schemas/ConversationChannel" recipient: description: The recipient to opt-out. Requires either `contact_id` or `identified_by`. If [Dispatch Mode](../../../../processing-modes/) is used, only `identified_by` is allowed. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" example: contact_id: "{CONTACT_ID}" processing_strategy: $ref: "#/components/schemas/ProcessingStrategy" RateLimits: type: object properties: inbound: description: |- The number of inbound messages/events we process per second, from underlying channels to the app. The default rate limit is 25. type: integer format: int64 readOnly: true outbound: description: |- The number of messages/events we process per second, from the app to the underlying channels. Note that underlying channels may have other rate limits. The default rate limit is 25. type: integer format: int64 readOnly: true webhooks: description: |- The rate limit of callbacks sent to the webhooks registered for the app. Note that if you have multiple webhooks with shared triggers, multiple callbacks will be sent out for each triggering event. The default rate limit is 25. type: integer format: int64 readOnly: true Reason: type: object properties: code: $ref: "#/components/schemas/ReasonCode" description: description: A textual description of the reason. type: string sub_code: $ref: "#/components/schemas/ReasonSubCode" ReasonCode: x-enumDescriptions: UNKNOWN: UNKNOWN is used if no other code can be used to describe the encountered error. INTERNAL_ERROR: An internal error occurred. Please save the entire callback if you want to report an error. RATE_LIMITED: The message or event was not sent due to rate limiting. RECIPIENT_INVALID_CHANNEL_IDENTITY: The channel recipient identity was malformed. RECIPIENT_NOT_REACHABLE: It was not possible to reach the contact, or channel recipient identity, on the channel. RECIPIENT_NOT_OPTED_IN: The contact, or channel recipient identity, has not opt-ed in on the channel. OUTSIDE_ALLOWED_SENDING_WINDOW: The allowed sending window has expired. See the channel documentation for more information about how the sending window works for the different channels. CHANNEL_FAILURE: The channel failed to accept the message. The Conversation API performs multiple retries in case of transient errors. CHANNEL_BAD_CONFIGURATION: The configuration of the channel for the used App is wrong. The bad configuration caused the channel to reject the message. Please see the [channel support documentation page](/docs/conversation/channel-support/) for how to set it up correctly. CHANNEL_CONFIGURATION_MISSING: The configuration of the channel is missing from the used App. Please see the [channel support documentation](/docs/conversation/channel-support/) page for how to set it up correctly. MEDIA_TYPE_UNSUPPORTED: Some of the referenced media files is of a unsupported media type. Please read the [channel support documentation](/docs/conversation/channel-support/) page to find out the limitations on media that the different channels impose. MEDIA_TOO_LARGE: Some of the referenced media files are too large. Please read the [channel support documentation](/docs/conversation/channel-support/) to find out the limitations on file size that the different channels impose. MEDIA_NOT_REACHABLE: The provided media link was not accessible from the Conversation API or from the underlying channels. Please make sure that the media file is accessible. NO_CHANNELS_LEFT: No channels to try to send the message to. This error will occur if one attempts to send a message to a channel with no channel identities or if all applicable channels have been attempted. TEMPLATE_NOT_FOUND: The referenced template was not found. TEMPLATE_INSUFFICIENT_PARAMETERS: Sufficient template parameters was not given. All parameters defined in the template must be provided when sending a template message. TEMPLATE_NON_EXISTING_LANGUAGE_OR_VERSION: The selected language, or version, of the referenced template did not exist. Please check the available versions and languages of the template. DELIVERY_TIMED_OUT: The message delivery, or event delivery, failed due to a channel-imposed timeout. See the [channel support documentation](/docs/conversation/channel-support/) page for further details about how the different channels behave. DELIVERY_REJECTED_DUE_TO_POLICY: The message or event was rejected by the channel due to a policy. Some channels have specific policies that must be met to send a message. See the [channel support documentation](/docs/conversation/channel-support/) page for more information about when this error will be triggered. CONTACT_NOT_FOUND: The provided Contact ID did not exist. BAD_REQUEST: Conversation API validates send requests in two different stages. The first stage is right before the message is enqueued. If this first validation fails the API responds with 400 Bad Request and the request is discarded immediately. The second validation kicks in during message processing and it normally contains channel specific validation rules. Failures during second request validation are delivered as callbacks to `MESSAGE_DELIVERY (EVENT_DELIVERY)` webhooks with ReasonCode `BAD_REQUEST`. UNKNOWN_APP: The used App is missing. This error may occur when the app is removed during message processing. NO_CHANNEL_IDENTITY_FOR_CONTACT: The contact has no channel identities set up, or the contact has no channels set up for the resolved channel priorities. CHANNEL_REJECT: Generic error for channel permanently rejecting a message. Only used if no other better matching error can be used. NO_PERMISSION: No permission to perform action. NO_PROFILE_AVAILABLE: No available profile data for user. UNSUPPORTED_OPERATION: Generic error for channel unsupported operations. type: string ReasonSubCode: x-enumDescriptions: UNSPECIFIED_SUB_CODE: UNSPECIFIED_SUB_CODE is used if no other sub code can be used to describe the encountered error. ATTACHMENT_REJECTED: The message attachment was rejected by the channel due to a policy. Some channels have specific policies that must be met to receive an attachment. MEDIA_TYPE_UNDETERMINED: The specified media urls media type could not be determined. INACTIVE_SENDER: The used credentials for the underlying channel is inactivated and not allowed to send or receive messages. type: string Recipient: # Do not refer to this field until this is solved https://github.com/Redocly/redoc/issues/752 type: object title: Recipient description: Identifies the recipient of the message. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" ReplyTo: description: If the contact message was a response to a previous App message then this field contains information about that. type: object title: Reply To required: - message_id properties: message_id: type: string description: Required. The Id of the message that this is a response to RetentionPolicy: type: object description: The retention policy configured for the app. For more information about retention policies, see [Retention Policy](/docs/conversation/keyconcepts/#retention-policy). title: Retention policy for messages and conversations properties: retention_type: $ref: "#/components/schemas/RetentionPolicyType" ttl_days: description: |- Optional. The days before a message or conversation is eligible for deletion. Default value is 180. The ttl_days value has no effect when retention_type is `PERSIST_RETENTION_POLICY`. The valid values for this field are [1 - 3650]. Note that retention cleanup job runs once every twenty-four hours which can lead to delay i.e., messages and conversations are not deleted on the minute they become eligible for deletion. type: integer default: 180 format: int64 RetentionPolicyType: x-enumDescriptions: MESSAGE_EXPIRE_POLICY: The default retention policy where messages older than ttl_days are automatically deleted from Conversation API database. CONVERSATION_EXPIRE_POLICY: The conversation expire policy only considers the last message in a conversation. If the last message is older that ttl_days the entire conversation is deleted. The difference with MESSAGE_EXPIRE_POLICY is that messages with accept_time older than ttl_days are persisted as long as there is a newer message in the same conversation. PERSIST_RETENTION_POLICY: Persist policy does not delete old messages or conversations. Please note that message storage might be subject to additional charges in the future. type: string default: MESSAGE_EXPIRE_POLICY DispatchRetentionPolicy: type: object description: The retention policy configured for messages in [Dispatch Mode](../../../../processing-modes/). Currently only `MESSAGE_EXPIRE_POLICY` is available. For more information about retention policies, see [Retention Policy](/docs/conversation/keyconcepts/#retention-policy). properties: retention_type: $ref: "#/components/schemas/DispatchRetentionPolicyType" ttl_days: description: |- Optional. The days before a message is eligible for deletion. The valid range is `[0 - 7]`. In the case of a `0` day TTL, messages aren't stored at all. Note the retention cleanup job runs once every twenty-four hours, so messages are not deleted on the minute they become eligible for deletion. type: integer default: 0 format: int64 DispatchRetentionPolicyType: enum: - MESSAGE_EXPIRE_POLICY type: string default: MESSAGE_EXPIRE_POLICY ProcessingMode: description: |- Whether or not Conversation API should store contacts and conversations for the app. For more information, see [Processing Modes](../../../../processing-modes/). x-enumDescriptions: CONVERSATION: The default Processing Mode. Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation. DISPATCH: Does not associate messages with contacts and conversations. This processing mode is mostly intended for unidirectional high volume SMS use cases. The lack of contacts and conversations limits some API features as related data won't be queryable in the [Contact](/docs/conversation/api-reference/conversation/tag/Contact) and [Conversation](/docs/conversation/api-reference/conversation/tag/Conversation) APIs. type: string default: CONVERSATION SmartConversation: description: This object is required for apps that subscribe to Smart Conversations features. Smart Conversations features are currently only available to select customers for closed beta testing. type: object properties: enabled: description: Set to true to allow messages processed by this app to be analyzed by Smart Conversations. type: boolean default: false StaticBearerCredential: description: This object is required for channels which use a bearer-type of credential for authentication. type: object required: - claimed_identity - token title: Bearer Channel Credential properties: claimed_identity: description: The claimed identity for the channel. type: string token: description: The static bearer token for the channel. type: string StaticTokenCredential: type: object description: This object is required for channels which use a static token credential for authentication. required: - token title: Static Token Credential properties: token: description: The static token for the channel. type: string TelegramCredentials: type: object title: Telegram credentials object required: - token description: If you are including the Telegram Bot channel in the `channel_identifier` property, you must include this object. properties: token: type: string description: The token for the Telegram bot to which you are connecting. example: "{{TELEGRAM_BOT_TOKEN}}" LineCredentials: type: object title: LINE credentials object required: - token - secret description: If you are including the LINE channel in the `channel_identifier` property, you must include this object. properties: token: type: string description: The token for the LINE channel to which you are connecting. example: "{{LINE_TOKEN}}" secret: type: string description: The secret for the LINE channel to which you are connecting. example: "{{LINE_SECRET}}" WeChatCredentials: type: object title: WeChat credentials object required: - app_id - app_secret - token - aes_key description: If you are including the WeChat channel in the `channel_identifier` property, you must include this object. properties: app_id: type: string description: The AppID(Developer ID) for the WeChat channel to which you are connecting. example: "{{WECHAT_APPID}}" app_secret: type: string description: The AppSecret(Developer Password) for the WeChat channel to which you are connecting. example: "{{WECHAT_APPSECRET}}" token: type: string description: The Token for the WeChat channel to which you are connecting. example: "{{WECHAT_TOKEN}}" aes_key: type: string description: The Encoding AES Key for the WeChat channel to which you are connecting. example: "{{WECHAT_AESKEY}}" TemplateMessage: type: object title: Message referring to predefined template properties: channel_template: description: |- Optional. Channel specific template reference with parameters per channel. The channel template if exists overrides the omnichannel template. At least one of `channel_template` or `omni_template` needs to be present. The key in the map must point to a valid conversation channel as defined by the enum ConversationChannel. type: object additionalProperties: $ref: "#/components/schemas/TemplateReference" omni_template: $ref: "#/components/schemas/TemplateReference" TemplateReference: description: |- The referenced template can be an omnichannel template stored in Conversation API Template Store as AppMessage or it can reference external channel-specific template such as WhatsApp Business Template. type: object title: Template reference with concrete parameter values required: - template_id - version properties: language_code: description: |- The BCP-47 language code, such as `en-US` or `sr-Latn`. For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. English is the default language_code. type: string parameters: description: |- Required if the template has parameters. Concrete values must be present for all defined parameters in the template. Parameters can be different for different versions and/or languages of the template. type: object additionalProperties: type: string template_id: description: The ID of the template. type: string version: description: |- Used to specify what version of a template to use. This will be used in conjunction with `language_code`. type: string TextMessage: type: object title: Text message description: A message containing only text. required: - text properties: text: description: The text to be sent. type: string UrlMessage: description: A generic URL message. type: object title: Url Message 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 Webhook: description: Represents a destination for receiving callbacks from the Conversation API. type: object title: Webhook required: - "app_id" - "target" - "triggers" properties: app_id: description: The app that this webhook belongs to. type: string client_credentials: $ref: "#/components/schemas/ClientCredentials" id: description: The ID of the webhook. type: string readOnly: true secret: description: |- Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature. type: string target: description: |- The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden. type: string target_type: $ref: "#/components/schemas/WebhookTargetType" triggers: description: |- An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of [Webhook Triggers](/docs/conversation/callbacks#webhook-triggers) for a complete list. type: array items: $ref: "#/components/schemas/WebhookTrigger" WebhookTargetType: type: string default: HTTP enum: - DISMISS - GRPC - HTTP WebhookTrigger: description: |- - `UNSPECIFIED_TRIGGER`: Using this value will cause errors. - `MESSAGE_DELIVERY`: Subscribe to delivery receipts for a message sent. - `EVENT_DELIVERY`: Subscribe to delivery receipts for a event sent. - `MESSAGE_INBOUND`: Subscribe to inbound messages from end users on the underlying channels. - `EVENT_INBOUND`: Subscribe to inbound events from end users on the underlying channels. - `CONVERSATION_START`: Subscribe to an event that is triggered when a new conversation has been started. - `CONVERSATION_STOP`: Subscribe to an event that is triggered when a active conversation has been stopped. - `CONTACT_CREATE`: Subscribe to an event that is triggered when a new contact has been created. - `CONTACT_DELETE`: Subscribe to an event that is triggered when a contact has been deleted. - `CONTACT_MERGE`: Subscribe to an event that is triggered when a two contacts are merged. - `CONTACT_UPDATE`: Subscribe to an event that is triggered when a contact is updated. - `UNSUPPORTED`: Subscribe to callbacks that are not natively supported by the Conversation API. - `OPT_IN`: Subscribe to opt_ins. - `OPT_OUT`: Subscribe to opt_outs. - `CAPABILITY`: Subscribe to see get capability results. - `CONVERSATION_DELETE`: Subscribe to get an event when a conversation is deleted. type: string example: MESSAGE_DELIVERY enum: - UNSPECIFIED_TRIGGER - MESSAGE_DELIVERY - EVENT_DELIVERY - MESSAGE_INBOUND - EVENT_INBOUND - CONVERSATION_START - CONVERSATION_STOP - CONTACT_CREATE - CONTACT_DELETE - CONTACT_MERGE - CONTACT_UPDATE - UNSUPPORTED - OPT_IN - OPT_OUT - CAPABILITY - CONVERSATION_DELETE ConversationMessagesView: type: string default: WITH_METADATA enum: - WITH_METADATA - WITHOUT_METADATA ListAppsResponse: type: object properties: apps: description: List of apps belonging to a specific project ID. type: array items: $ref: "#/components/schemas/AppResponse" ListContactsResponse: type: object properties: contacts: description: List of contacts belonging to the specified project. type: array items: $ref: "#/components/schemas/Contact" next_page_token: description: |- Token that should be included in the next list contacts request to fetch the next page. type: string ListConversationsResponse: type: object properties: conversations: description: List of conversations matching the search query. type: array items: $ref: "#/components/schemas/Conversation" readOnly: true next_page_token: type: string description: Token that should be included in the next request to fetch the next page. total_size: type: integer format: int32 ListMessagesResponse: type: object properties: messages: description: List of messages associated to the referenced conversation. type: array items: $ref: "#/components/schemas/ConversationMessage" readOnly: true next_page_token: type: string description: Token that should be included in the next request to fetch the next page. ListWebhooksResponse: type: object properties: webhooks: type: array description: List of webhooks belonging to a specific project ID and app ID items: $ref: "#/components/schemas/Webhook" MergeContactRequest: type: object required: - source_id properties: source_id: description: Required. The ID of the contact that should be removed. type: string strategy: $ref: "#/components/schemas/ConversationMergeStrategy" GetChannelProfileRequest: type: object required: - app_id - recipient - channel properties: app_id: type: string description: The ID of the app. example: "{APP_ID}" recipient: description: The recipient to check profile information. Requires either `contact_id` or `identified_by`. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" example: contact_id: "{CONTACT_ID}" channel: $ref: "#/components/schemas/GetChannelProfileConversationChannel" GetChannelProfileResponse: type: object properties: profile_name: type: string description: The profile name. example: "John Doe" QueryCapability: type: object required: - app_id - recipient properties: app_id: description: The ID of the app to use for capability lookup. type: string example: "{APP_ID}" recipient: description: The recipient to lookup capabilities for. Requires either `contact_id` or `identified_by`. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" example: contact_id: "{CONTACT_ID}" request_id: type: string description: |- ID for the asynchronous response, will be generated if not set. Currently this field is not used for idempotency. QueryCapabilityResponse: description: |- An CapabilityResponse contains the identity of the recipient for which will be perform a capability lookup. type: object title: Represents an explicit Capability registration properties: app_id: description: The ID of the app to use for capability lookup. type: string recipient: description: The recipient to lookup capabilities for. Requires either `contact_id` or `identified_by`. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" example: contact_id: "{CONTACT_ID}" request_id: type: string description: ID for the asynchronous response, will be generated if not set. SendEventRequest: type: object required: - app_id - recipient - event properties: app_id: description: The ID of the app sending the event. type: string callback_url: description: |- Overwrites the default callback url for delivery reports for this message The REST URL should be of the form: `http://host[:port]/path` type: string channel_priority_order: description: |- Optional. Channel priority order that dictates on which channels the Conversation API should try to send the message on. The order provided here overrides any default. type: array items: $ref: "#/components/schemas/ConversationChannel" event: description: Event originating from an app type: object oneOf: - title: composing_event type: object properties: composing_event: $ref: "#/components/schemas/ComposingEvent" - type: object title: comment_reply_event properties: comment_reply_event: $ref: "#/components/schemas/CommentReplyEvent" event_metadata: description: Optional. Eventual metadata that should be associated to the event. type: string queue: $ref: "#/components/schemas/MessageQueue" recipient: description: The recipient of the event. Requires either `contact_id` or `identified_by`. If [Dispatch Mode](../../../../processing-modes/) is used, only `identified_by` is allowed. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" example: contact_id: "{CONTACT_ID}" SendEventResponse: type: object properties: accepted_time: description: Accepted timestamp. type: string format: date-time readOnly: true event_id: description: Event id. type: string readOnly: true SendMessageRequest: type: object description: This is the request body for sending a message. `app_id`, `recipient`, and `message` are all required fields. required: - "app_id" - "recipient" - "message" properties: app_id: description: The ID of the app sending the message. type: string example: "{APP_ID}" callback_url: description: |- Overwrites the default callback url for delivery reports for this message The REST URL should be of the form: `http://host[:port]/path` type: string channel_priority_order: description: |- Explicitly define the channels and order in which they are tried when sending the message. Which channels the API will try and their priority is defined by: 1. `channel_priority_order` if available. 2. `recipient.identified_by.channel_identities` if available. 3. When recipient is a `contact_id`: - if a conversation with the contact exists: the active channel of the conversation is tried first. - the existing channels for the contact are ordered by contact channel preferences if given. - lastly the existing channels for the contact are ordered by the app priority. type: array items: $ref: "#/components/schemas/ConversationChannel" channel_properties: description: |- Channel-specific properties. The key in the map must point to a valid channel property key as defined by the enum ChannelPropertyKeys. The maximum allowed property value length is 1024 characters. type: object additionalProperties: type: string message: $ref: "#/components/schemas/AppMessage" message_metadata: description: |- Metadata that should be associated with the message. Returned in the `metadata` field of a [Message Delivery Receipt](https://developers.sinch.com/docs/conversation/callbacks/#message-delivery-receipt). type: string conversation_metadata: description: |- Metadata that should be associated with the conversation. This metadata will be propagated on MO callbacks associated with this conversation. Note that the MO callback will always use the last metadata available in the conversation. Important notes: - If you send a message with the `conversation_metadata` field populated, and then send another message without populating the `conversation_metadata` field, the original metadata will continue be propagated on the related MO callbacks. - If you send a message with the `conversation_metadata` field populated, and then send another message with a different value for `conversation_metadata` in the same conversation, the latest metadata value overwrites the existing one. So, future MO callbacks will include the new metadata. - The `conversation_metadata` only accepts json objects. Currently only returned in the `message_metadata` field of an [Inbound Message](/docs/conversation/callbacks/#inbound-message) callback. type: object example: "{\"arbitrary_metadata_key\":\"arbitrary_metadata_value\"}" queue: $ref: "#/components/schemas/MessageQueue" recipient: type: object description: Identifies the recipient of the message. Requires either `contact_id` or `identified_by`. If [Dispatch Mode](../../../../processing-modes/) is used, only `identified_by` is allowed. oneOf: - type: object title: contact_id properties: contact_id: $ref: "#/components/schemas/Contact_Id" - type: object title: identified_by properties: identified_by: $ref: "#/components/schemas/Identified_By" ttl: description: |- The timeout allotted for sending the message. Passed onto channels which have support for it and emulated by Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with expired TTL. type: string processing_strategy: $ref: "#/components/schemas/ProcessingStrategy" ProcessingStrategy: description: Overrides the app's [Processing Mode](../../../../processing-modes/). Default value is `DEFAULT`. 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. type: string default: DEFAULT SendMessageResponse: type: object properties: accepted_time: description: |- Timestamp when the Conversation API accepted the message for delivery to the referenced contact. type: string format: date-time readOnly: true message_id: description: The ID of the message. type: string readOnly: true TranscodeMessageRequest: type: object required: - app_id - app_message - channels properties: app_id: description: The ID of the app used to transcode the message. type: string app_message: $ref: "#/components/schemas/AppMessage" channels: description: The list of channels for which the message shall be transcoded to. type: array items: $ref: "#/components/schemas/ConversationChannel" from: description: Optional. type: string to: description: Optional. type: string TranscodeMessageResponse: type: object properties: transcoded_message: description: |- The transcoded message for the different channels. The keys in the map correspond to channel names, as defined by the type ConversationChannel. type: object additionalProperties: type: string readOnly: true securitySchemes: Basic: type: http scheme: basic description: For more information about basic authentication, see [Basic Authentication](newdocs/docs/voice/api-reference/authentication.md#basic-authentication). oAuth2: type: oauth2 description: The user name and password are your client_id and key_secret from the [Access keys sections](https://dashboard.sinch.com/settings/access-keys) flows: clientCredentials: tokenUrl: https://auth.sinch.com/oauth2/token scopes: {} x-readme: proxy-enabled: true samples-enabled: true