openapi: 3.0.2 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://{region}.conversation.api.sinch.com" variables: region: default: us enum: - us - eu - br description: The {region} variable must be set to us, eu, or br, and it must match the region in which you created your Conversation API app. 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 associated with that app. If the recipient is not associated with an existing contact, a new contact will be created. 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 [Sinch Customer Dashboard](https://dashboard.sinch.com/settings/access-keys). 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" patch: description: Update a specific message metadata by its ID. tags: - Messages summary: Update message metadata operationId: Messages_UpdateMessageMetadata requestBody: $ref: "#/components/requestBodies/UpdateMessageMetadataRequest" 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" 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. "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: Id of the conversation. Available only when `messages_source` is `CONVERSATION_SOURCE`. - $ref: "#/components/parameters/query_contact_id" description: Id of the contact. Available only when `messages_source` is `CONVERSATION_SOURCE`. - name: app_id description: Id of the app. in: query schema: type: string - name: channel_identity description: Channel identity of the contact. in: query schema: type: string - name: start_time description: Filter messages with `accept_time` after this timestamp. Must be before `end_time` if that is specified. in: query schema: type: string format: date-time - name: end_time description: Filter messages with `accept_time` before this timestamp. in: query schema: type: string format: date-time - description: |- Maximum number of messages to fetch. Defaults to 10 and the maximum is 1000. name: page_size in: query schema: type: integer format: int32 - description: |- Next page token previously returned if any. When specifying this token, make sure to use the same values for the other parameters from the request that originated the token, otherwise the paged results may be inconsistent. 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" - description: Only fetch messages from the `channel`. name: channel in: query schema: $ref: "#/components/schemas/ConversationChannel" get: description: |- This operation lists all messages sent or received via particular [Processing Modes](/docs/conversation/processing-modes/). Setting the `messages_source` parameter to `CONVERSATION_SOURCE` allows for querying messages in `CONVERSATION` mode, and setting it to `DISPATCH_SOURCE` will allow for queries of messages in `DISPATCH` mode. Combining multiple parameters is supported for more detailed filtering of messages, but some of them are not supported depending on the value specified for `messages_source`. The description for each field will inform if that field may not be supported. 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 the app specified by the App ID. Note that this operation will not delete contacts (which are stored at the project level) nor any channel-specific resources (for example, WhatsApp Sender Identities will not be deleted). operationId: App_DeleteApp responses: "200": description: A successful response. "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. Note that this is a `PATCH` operation, so any specified field values will replace existing values. Therefore, **if you'd like to add additional configurations to an existing Conversation API app, ensure that you include existing values AND new values in the call**. For example, if you'd like to add new `channel_credentials`, you can [get](/docs/conversation/api-reference/conversation/tag/App/#tag/App/operation/App_GetApp) your existing Conversation API app, extract the existing `channel_credentials` list, append your new configuration to that list, and include the updated `channel_credentials` list in this update call. operationId: App_UpdateApp parameters: - $ref: '#/components/parameters/update_mask' 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. Note that, if a WhatsApp contact is returned, the `display_name` field of that contact may be populated with the WhatsApp display name (if the name is already stored on the server and the `display_name` field has not been overwritten by the user). 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 - description: "Optional. Contact identifier in an external system. If used, `channel` and `identity` query parameters can't be used." name: external_id in: query schema: type: string - description: "Optional. Specifies a channel, and must be set to one of the enum values. If set, the `identity` parameter must be set and `external_id` can't be used. Used in conjunction with `identity` to uniquely identify the specified channel identity." name: channel in: query schema: { $ref: "#/components/schemas/ConversationChannel" } - description: "Optional. If set, the `channel` parameter must be set and `external_id` can't be used. Used in conjunction with `channel` to uniquely identify the specified channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business." name: identity 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: Most Conversation API contacts are [created automatically](/docs/conversation/contact-management/) when a message is sent to a new recipient. You can also create a new contact manually using this API call. 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. Note the following: - If a WhatsApp contact is returned, the `display_name` field of that contact may be populated with the WhatsApp display name (if the name is already stored on the server and the `display_name` field has not been overwritten by the user). - If you receive an Inbound Message callback for an MO message on the Instagram channel, the corresponding payload will not include the Instagram username. You may use the `contact_id` and `channel_identity` values included in the callback to retreive the username (detailed in the `display_name` field) with this Conversation API operation. 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. "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' 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. Only supported on `MESSENGER`, `INSTAGRAM`, `VIBER` and `LINE` channels. Note that, in order to retrieve a WhatsApp display name, you can use the Get a Contact or List Contacts operations, which will populate the `display_name` field of each returned contact with the WhatsApp display name (if the name is already stored on the server and the `display_name` field has not been overwritten by the user). 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 - description: Only fetch conversations from the `active_channel` name: active_channel in: query schema: $ref: "#/components/schemas/ConversationChannel" 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. "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' - description: Update strategy for the `conversation_metadata` field. name: metadata_update_strategy in: query schema: $ref: "#/components/schemas/MetadataUpdateStrategy" 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:recent': get: description: |- This operation lists conversations and their most recent message, ordered by when the most recent message was sent for that conversation. tags: - Conversation summary: List recent conversations operationId: Conversation_ListRecentConversations parameters: - $ref: "#/components/parameters/project_id" - name: app_id description: The application ID required: true in: query schema: type: string - name: only_active description: True if only active conversations should be listed. Default is false. in: query schema: type: boolean - name: page_size description: |- The maximum number of conversations to fetch. Defaults to 10 and the maximum value is 50. in: query schema: type: integer format: int32 - name: page_token description: |- Next page token previously returned if any. When specifying this token, make sure to use the same values for the other parameters from the request that originated the token, otherwise the paged results may be inconsistent. in: query schema: type: string - name: order in: query description: Whether to sort conversations by newest message first or oldest. Default is DESC (newest first) required: false schema: type: string enum: - ASC - DESC responses: "200": $ref: "#/components/responses/listRecentConversationResponse" "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}:inject-event': parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/conversation_id" post: summary: Inject an event description: This operation injects a conversation event in to a specific conversation. It only supports injecting App events in `CONVERSATION` mode. tags: - Conversation operationId: Events_InjectEvent requestBody: $ref: "#/components/requestBodies/InjectEventRequest" responses: "200": $ref: "#/components/responses/injectEventResponse" "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. "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: 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 a message operationId: Conversation_InjectMessage requestBody: $ref: "#/components/requestBodies/InjectMessageRequest" responses: "200": description: A successful response. "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 queue 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}/events/{event_id}: parameters: - $ref: "#/components/parameters/project_id" - $ref: "#/components/parameters/event_id" get: description: Get event from ID tags: - Events summary: Get an event operationId: Events_GetEvent responses: "200": $ref: "#/components/responses/getEventResponse" "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 event by its ID. tags: - Events summary: Delete an event operationId: Events_DeleteEvents responses: "200": description: A successful response. "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: parameters: - $ref: "#/components/parameters/project_id" get: summary: List events description: List all events in a project tags: - Events operationId: Events_ListEvents parameters: - name: conversation_id description: Resource name (id) of the conversation. One of conversation_id or contact_id needs to be present. in: query schema: type: string - name: contact_id description: Resource name (id) of the contact. One of conversation_id or contact_id needs to be present. in: query schema: type: string - name: page_size description: |- Maximum number of events to fetch. Defaults to 10 and the maximum is 20. in: query schema: type: integer format: int32 - name: page_token description: |- Next page token previously returned if any. When specifying this token, make sure to use the same values for the other parameters from the request that originated the token, otherwise the paged results may be inconsistent. in: query schema: type: string responses: "200": $ref: "#/components/responses/listEventsResponse" "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}/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" 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. "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 receipts 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**. Most contact creation and maintenance is handled by the Conversation API's automatic [contact management](/docs/conversation/contact-management/) processes. However, you can also use API calls to manually manage your contacts. 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: |- A capability query checks the options available for reaching the [contact](/docs/conversation/keyconcepts/#contact) on the channels on which it has a channel identity. Capability queries can only be executed for contacts that already exist in a project and app. For executing the request, either the contact ID or the channel recipient identities of the contact are required. The request is executed asynchronously, therefore the service responds immediately. The result of the capability query is sent to the registered [webhook](/docs/conversation/keyconcepts/#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. Note that either `app_id` or `contact_id` is required in order for the operation to function correctly. 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. Note that either `app_id` or `contact_id` is required in order for the operation to function correctly. 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](/docs/conversation/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 order: name: order description: Order of the recent conversations. in: query schema: x-enumDescriptions: DESC: Descending order. Newest first. ASC: Ascending order. Oldest first. default: DESC 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: description: The set of field mask paths. name: update_mask 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 event_id: description: The unique ID of the event. name: event_id required: true in: path 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." sendOmniTemplate: summary: Send message using an omnichannel template value: app_id: "{APP_ID}" recipient: contact_id: "{CONTACT_ID}" message: template_message: omni_template: template_id: "YOUR_omni_template_id" version: "latest" language_code: en_US parameters: {} sendExplicitChannelOmniMessage: summary: Send explicit channel message, overriding omni message value: app_id: "{APP_ID}" recipient: contact_id: "{CONTACT_ID}" message: explicit_channel_omni_message: SMS: template_reference: template_id: "YOUR_omni_template_id" version: "latest" language_code: en_US parameters: {} 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" createConversationRequest: summary: Create a new conversation value: active: true active_channel: "WHATSAPP" app_id: "{APP_ID}" contact_id: "{CONTACT_ID}" id: "string" metadata: "string" metadata_json: { } updateConversationRequest: summary: Update a conversation value: app_id: "string " metadata: "string" active_channel: "WHATSAPP" active: true updateMessageMetadataRequest: summary: Update certain fields of a message. For now only metadata update is allowed. value: metadata: "New metadata value" 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" updateContactRequest: summary: Update contact value: channel_identities: - channel: "MESSENGER" identity: "{{FACEBOOK_USER_NAME}}" app_id: "{{APP_ID}}" - channel: "VIBER" identity: "{{PHONE_NUMBER}}" app_id: "{{APP_ID}}" channel_priority: - "MESSENGER" - "VIBER" email: "string" language: "FR" metadata : "string" updateContactResponse: summary: Updated contact value: channel_identities: - channel: "MESSENGER" identity: "{{FACEBOOK_USER_NAME}}" app_id: "{{APP_ID}}" - channel: "VIBER" identity: "{{PHONE_NUMBER}}" app_id: "{{APP_ID}}" channel_priority: - "MESSENGER" - "VIBER" display_name: "string" external_id: "string" email: "string" language: "EN_US" metadata : "string" mergeContactResponse: summary: Merged contact value: id: "ID_of_target_contact" channel_identities: - channel: "TELEGRAM" identity: "{TELEGRAM_ID}" app_id: "" - channel: "WHATSAPP" identity: "{WHATSAPP_ID}" app_id: "" channel_priority: - "TELEGRAM" - "WHATSAPP" display_name: "{CONTACT_DISPLAY_NAME}" email: "" external_id: "" metadata: "" language: "ZU" 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" injectMessageRequest: summary: Inject a message into a specific conversation value: direction: "TO_CONTACT" channel_identity: channel: "{{CHANNEL_NAME}}" identity: "{{CHANNEL_IDENTITY}}" app_message: text_message: text: "string" contact_id: "string" accept_time: "YYYY-MM-DDTHH:MM:SS" injectEventRequest: summary: Inject Event Request value: id: "string" direction: "TO_APP" channel_identity: channel: "MESSENGER" identity: "{{FACEBOOK_USER_NAME}}" app_id: "{{APP_ID}}" app_event: composing_event: {} accept_time: "YYYY-MM-DDTHH:MM:SS" injectEventResponse: summary: Inject event response value: event_id: string accepted_time: "YYYY-MM-DDTHH:MM:SS" responses: 400Error: description: Malformed request. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. content: application/json: schema: $ref: "#/components/schemas/runtimeError" example: code: 400 message: Malformed request status: INVALID_REQUEST details: [] 401Error: description: Incorrect credentials. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. content: application/json: schema: {} 403Error: description: Correct credentials but you don't have access to the requested resource. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. 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. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. 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. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information. 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. More information is available in [delivery report callbacks](/docs/conversation/callbacks/). 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" examples: updatedContact: $ref: "#/components/examples/updateContactResponse" 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" listRecentConversationResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListRecentConversationsResponse" 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" examples: mergedContact: $ref: "#/components/examples/mergeContactResponse" getChannelProfileResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/GetChannelProfileResponse" queryCapabilityResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/QueryCapabilityResponse" getEventResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ConversationEvent" listEventsResponse: description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ListEventsResponse" injectEventResponse: description: A succcessful response. content: application/json: schema: $ref: "#/components/schemas/InjectEventResponse" examples: injectEventResponse: $ref: "#/components/examples/injectEventResponse" 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/CreateConversationRequest" examples: createNewConversation: $ref: "#/components/examples/createConversationRequest" 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/InjectMessageRequest" examples: injectNewMessage: $ref: "#/components/examples/injectMessageRequest" description: Message to be injected. required: true InjectEventRequest: content: application/json: schema: $ref: "#/components/schemas/InjectConversationEventRequest" examples: injectEventRequest: $ref: "#/components/examples/injectEventRequest" description: Inject event request 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" examples: updateContact: $ref: "#/components/examples/updateContactRequest" description: The contact to be updated required: true UpdateConversationRequest: content: application/json: schema: $ref: "#/components/schemas/Conversation" examples: updateConversationRequest: $ref: "#/components/examples/updateConversationRequest" description: The updated conversation. required: true UpdateMessageMetadataRequest: content: application/json: schema: $ref: "#/components/schemas/UpdateMessageMetadataRequest" examples: updateMessageMetadataRequest: $ref: "#/components/examples/updateMessageMetadataRequest" description: Update message metadata request. 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" OmniMessage: $ref: "#/components/examples/sendOmniTemplate" ExplicitChannelOmniMessage: $ref: "#/components/examples/sendExplicitChannelOmniMessage" required: true schemas: protobufAny: type: object properties: type_url: type: string value: type: string format: byte runtimeError: type: object properties: error: type: object properties: code: type: integer format: int32 details: type: array items: $ref: "#/components/schemas/protobufAny" 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/ConversationChannelCredentialRequest" 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" callback_settings: $ref: "#/components/schemas/CallbackSettings" message_retry_settings: $ref: "#/components/schemas/MessageRetrySettings" delivery_report_based_fallback: $ref: "#/components/schemas/DeliveryReportBasedFallback" AppUpdateRequest: description: |- The request sent to the API endpoint to update the configuration of an 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/ConversationChannelCredentialRequest" 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" callback_settings: $ref: "#/components/schemas/CallbackSettings" message_retry_settings: $ref: "#/components/schemas/MessageRetrySettings" delivery_report_based_fallback: $ref: "#/components/schemas/DeliveryReportBasedFallback" AppResponse: description: |- The response showing information about the app. type: object title: Conversation API app properties: channel_credentials: type: array items: $ref: "#/components/schemas/ConversationChannelCredentials" 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" queue_stats: $ref: "#/components/schemas/QueueStats" callback_settings: $ref: "#/components/schemas/CallbackSettings" delivery_report_based_fallback: $ref: "#/components/schemas/DeliveryReportBasedFallback" message_retry_settings: $ref: "#/components/schemas/MessageRetrySettings" AppMessageObject: type: object title: App properties: app_message: $ref: "#/components/schemas/AppMessage" AppMessage: type: object description: Message originating from an app allOf: - $ref: "#/components/schemas/AppMessageTypes" - $ref: "#/components/schemas/AppMessageCommonProps" AppMessageTypes: type: object oneOf: - $ref: "#/components/schemas/CardMessageField" - $ref: "#/components/schemas/CarouselMessageField" - $ref: "#/components/schemas/ChoiceMessageField" - $ref: "#/components/schemas/LocationMessageField" - $ref: "#/components/schemas/MediaMessageField" - $ref: "#/components/schemas/TemplateMessageField" - $ref: "#/components/schemas/TextMessageField" - $ref: "#/components/schemas/ListMessageField" - $ref: "#/components/schemas/ContactInfoMessageField" AppMessageCommonProps: type: object properties: explicit_channel_message: description: |- Allows you to specify a channel and define a corresponding channel specific message payload that will override the standard Conversation API message types. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. The message content must be provided in string format. You may use the [transcoding endpoint](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Transcoding/) to help create your message. For more information about how to construct an explicit channel message for a particular channel, see that [channel's corresponding documentation](https://developers.sinch.com/docs/conversation/channel-support/) (for example, using explicit channel messages with [the WhatsApp channel](https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/#explicit-channel-messages)). type: object explicit_channel_omni_message: description: |- Override the message's content for specified channels. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. The content defined under the specified channel will be sent on that channel. type: object additionalProperties: $ref: "#/components/schemas/OmniMessageOverride" channel_specific_message: description: |- Channel specific messages, overriding any transcoding. The structure of this property is more well-defined than the open structure of the `explicit_channel_message` property, and may be easier to use. The key in the map must point to a valid conversation channel as defined in the enum `ConversationChannel`. type: object additionalProperties: $ref: "#/components/schemas/ChannelSpecificMessage" agent: $ref: "#/components/schemas/Agent" AppEventField: type: object title: App Event Type properties: app_event: description: Event originating from an app type: object title: App Event oneOf: - $ref: "#/components/schemas/ComposingEventField" - $ref: "#/components/schemas/ComposingEndEventField" - $ref: "#/components/schemas/CommentReplyEventField" - $ref: "#/components/schemas/AgentJoinedEventField" - $ref: "#/components/schemas/AgentLeftEventField" - $ref: "#/components/schemas/GenericEventField" BasicAuthCredentials: 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 format: password username: description: Basic auth username. type: string CallMessageField: description: Message for triggering a call. type: object title: Call properties: call_message: title: Call Message type: object required: - "phone_number" - "title" properties: phone_number: description: Phone number in E.164 with leading +. type: string example: "+15551231234" title: description: |- Title shown close to the phone number. 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 CardMessageField: description: "Field containing a Card Message" type: object title: Card properties: card_message: $ref: "#/components/schemas/CardMessage" CardMessage: description: "Message containing text, media and choices." title: Card Message type: object properties: choices: description: You may include choices in your Card Message. The number of choices is limited to 10. type: array items: $ref: "#/components/schemas/Choice" description: description: This is an optional description field that is displayed below the title on the card. type: string height: $ref: "#/components/schemas/CardHeight" media_message: $ref: "#/components/schemas/CardMessageMediaMessage" title: description: The title of the card message. type: string CarouselMessageField: description: Message containing a list of cards often rendered horizontally on supported channels. type: object title: Carousel properties: carousel_message: title: Carousel Message type: object required: - "cards" properties: cards: description: A list of up to 10 cards. type: array items: $ref: "#/components/schemas/CardMessage" choices: description: Optional. Outer choices on the carousel level. The number of outer choices is limited to 3. type: array items: $ref: "#/components/schemas/Choice" 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 Choices: type: object properties: choices: type: array description: The number of choices is limited to 10. items: $ref: "#/components/schemas/Choice" Choice: description: A choice is an action the user can take such as buttons for quick replies or other call to actions. type: object title: Choice message allOf: - $ref: "#/components/schemas/choiceTypes" - $ref: "#/components/schemas/choiceCommonProps" choiceTypes: type: object oneOf: - $ref: "#/components/schemas/CallMessageField" - $ref: "#/components/schemas/LocationMessageField" - $ref: "#/components/schemas/TextMessageField" - $ref: "#/components/schemas/UrlMessageField" choiceCommonProps: type: object properties: postback_data: description: An optional field. This data will be returned in the ChoiceResponseMessage. The default is message_id_{text, title}. ChoiceMessageField: description: Message containing choices/actions. type: object title: Choice properties: choice_message: title: Choice Message type: object required: - "choices" allOf: - $ref: "#/components/schemas/Choices" - $ref: "#/components/schemas/TextMessageField" ChoiceResponseMessageField: description: Represents a response to a choice message. type: object title: Choice Response properties: choice_response_message: title: Choice Response Message type: object 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 description: Optional. Used for OAuth2 authentication. required: - "client_id" - "client_secret" - "endpoint" properties: client_id: description: The Client ID that will be used in the OAuth2 Client Credentials flow. type: string client_secret: description: The Client Secret that will be used in the OAuth2 Client Credentials flow. type: string format: password endpoint: description: The endpoint that will be used in the OAuth2 Client Credentials flow. Expected to return a JSON with an access token and `expires_in` value (in seconds). The `expires_in` value, which must be a minimum of 30 seconds and a maximum of 3600 seconds, is how long Sinch will save the access token before asking for a new one. type: string CommentReplyEventField: type: object title: Comment Reply Event Type properties: comment_reply_event: title: Comment Reply Event description: Represents a response to a comment event. type: object required: - "text" properties: text: description: The text of the comment reply. type: string ComposingEventField: type: object title: Composing properties: composing_event: title: Composing Event Type type: object description: An empty object. Represents a typing indicator. ComposingEndEventField: type: object title: Composing End Event Type properties: composing_end_event: title: Composing End Event type: object description: An empty object. Represents a typing end indicator. ConversationDeletedEventField: type: object title: Conversation Deleted Event Type properties: conversation_deleted_event: title: Conversation Deleted Event type: object description: An empty object. Represents a conversation deleted by the contact. AgentJoinedEventField: type: object title: Agent Joined Event Type properties: agent_joined_event: title: Agent Joined Event type: object properties: agent: $ref: "#/components/schemas/Agent" required: - "agent" AgentLeftEventField: type: object title: Agent Left Event Type properties: agent_left_event: title: Agent Left Event type: object properties: agent: $ref: "#/components/schemas/Agent" required: - "agent" GenericEventField: type: object title: Generic Type properties: generic_event: title: Generic Event type: object properties: payload: description: Arbitrary data set to the event. A valid JSON object. type: object description: Event that contains only a flexible payload field. required: - "payload" Agent: description: Represents an agent that is involved in a conversation. type: object title: Agent properties: display_name: description: Agent's display name type: string type: $ref: "#/components/schemas/AgentType" picture_url: description: The Agent's picture url. type: string AgentType: description: Agent's classification. It can be UNKNOWN_AGENT_TYPE, HUMAN or BOT. enum: - UNKNOWN_AGENT_TYPE - HUMAN - BOT x-enumDescriptions: UNKNOWN_AGENT_TYPE: The default AgentType. When the agent type is unknown. HUMAN: Human agent. BOT: Bot agent. type: string default: UNKNOWN_AGENT_TYPE ContactCreateRequest: description: A participant in a conversation typically representing a person. It is associated with a collection of channel identities. type: object title: Contact creation request required: - "channel_identities" - "language" properties: channel_identities: description: List of channel identities. Array must contain at least one item. type: array items: $ref: "#/components/schemas/ChannelIdentity" channel_priority: description: List of channels defining the channel priority. The channel at the top of the list is tried first. type: array items: $ref: "#/components/schemas/ConversationChannel" display_name: type: string description: The display name. A default 'Unknown' will be assigned if left empty. email: description: Email of the contact. type: string external_id: description: Contact identifier in an external system. type: string language: $ref: "#/components/schemas/ContactLanguage" metadata: description: Metadata associated with the contact. Up to 1024 characters long. type: string 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 ContactIDField: type: object title: Contact ID properties: contact_id: title: Contact ID string description: The ID of the contact. type: string example: "{CONTACT_ID}" ContactLanguage: type: string enum: - AF - SQ - AR - AZ - BN - BG - CA - ZH - ZH_CN - ZH_HK - ZH_TW - HR - CS - DA - NL - EN - EN_GB - EN_US - ET - FIL - FI - FR - DE - EL - GU - HA - HE - HI - HU - ID - GA - IT - JA - KN - KK - KO - LO - LV - LT - MK - MS - ML - MR - NB - FA - PL - PT - PT_BR - PT_PT - PA - RO - RU - SR - SK - SL - ES - ES_AR - ES_ES - ES_MX - SW - SV - TA - TE - TH - TR - UK - UR - UZ - VI - ZU x-enumDescriptions: AF: Afrikaans SQ: Albanian AR: Arabic AZ: Azerbaijani BN: Bengali BG: Bulgarian CA: Catalan ZH: Chinese ZH_CN: Chinese (CHN) ZH_HK: Chinese (HKG) ZH_TW: Chinese (TAI) HR: Croatian CS: Czech DA: Danish NL: Dutch EN: English EN_GB: English (UK) EN_US: English (US) ET: Estonian FIL: Filipino FI: Finnish FR: French DE: German EL: Greek GU: Gujarati HA: Hausa HE: Hebrew HI: Hindi HU: Hungarian ID: Indonesian GA: Irish IT: Italian JA: Japanese KN: Kannada KK: Kazakh KO: Korean LO: Lao LV: Latvian LT: Lithuanian MK: Macedonian MS: Malay ML: Malayalam MR: Marathi NB: Norwegian FA: Persian PL: Polish PT: Portuguese PT_BR: Portuguese (BR) PT_PT: Portuguese (PT) PA: Punjabi RO: Romanian RU: Russian SR: Serbian SK: Slovak SL: Slovenian ES: Spanish ES_AR: Spanish (ARG) ES_ES: Spanish (SPA) ES_MX: Spanish (MEX) SW: Swahili SV: Swedish TA: Tamil TE: Telugu TH: Thai TR: Turkish UK: Ukrainian UR: Urdu UZ: Uzbek VI: Vietnamese ZU: Zulu ContactMessage: description: Message originating from a contact type: object allOf: - $ref: "#/components/schemas/ContactMessageTypes" - $ref: "#/components/schemas/ContactMessageCommonProps" ContactMessageTypes: oneOf: - $ref: "#/components/schemas/ChannelSpecificContactMessage" - $ref: "#/components/schemas/ChoiceResponseMessageField" - $ref: "#/components/schemas/FallbackMessageField" - $ref: "#/components/schemas/LocationMessageField" - $ref: "#/components/schemas/MediaCardMessageField" - $ref: "#/components/schemas/MediaMessageField" - $ref: "#/components/schemas/ProductResponseMessage" - $ref: "#/components/schemas/TextMessageField" ContactMessageCommonProps: type: object allOf: - $ref: "#/components/schemas/ReplyToField" 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. NOTE: This field has been deprecated due to changes in the system architecture or functionality. It is no longer actively maintained and may be removed in future versions. Please avoid relying on this field in new code. 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 correlation_id: type: string description: Arbitrary correlation ID related to the MT message set by the Conversation API user. 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 - KAKAOTALKCHAT - LINE - WECHAT - APPLEBC CredentialOrdinalNumber: type: integer description: The ordinal number of the credential. This field is used when the application supports multiple credential integrations per channel. Currently, this is only applicable to the `LINE` channel. For other channels, this value will always be set to `0`. In the case in which there are multiple credential integrations per channel on a single app, this field must have a unique value for each multi-credential channel entry. default: 0 minimum: 0 maximum: 255 CreateConversationRequest: required: - app_id - contact_id description: The conversation to create. 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 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 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 - LINE ConversationChannelCredentialRequest: type: object description: Enables access to the underlying messaging channel. allOf: - $ref: "#/components/schemas/ChannelCredentialsTypes" - $ref: "#/components/schemas/ChannelCredentialsRequestCommonTypes" ChannelCredentialsTypes: type: object oneOf: - $ref: "#/components/schemas/StaticBearerCredentialsField" - $ref: "#/components/schemas/StaticTokenCredentialsField" - $ref: "#/components/schemas/MMSCredentialsField" - $ref: "#/components/schemas/KakaoTalkCredentialsField" - $ref: "#/components/schemas/TelegramCredentialsField" - $ref: "#/components/schemas/LineCredentialsField" - $ref: "#/components/schemas/LineEnterpriseCredentialsField" - $ref: "#/components/schemas/WeChatCredentialsField" - $ref: "#/components/schemas/InstagramCredentialsField" - $ref: "#/components/schemas/AppleBcCredentialsField" - $ref: "#/components/schemas/KakaoTalkChatCredentialsField" ChannelCredentialsRequestCommonTypes: type: object 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 format: password channel: $ref: "#/components/schemas/ConversationChannel" credential_ordinal_number: $ref: "#/components/schemas/CredentialOrdinalNumber" ChannelCredentialsCommonTypes: type: object 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 format: password channel: $ref: "#/components/schemas/ConversationChannel" state: $ref: "#/components/schemas/ChannelIntegrationState" channel_known_id: description: Additional identifier set by the channel that represents an specific id used by the channel. type: string credential_ordinal_number: $ref: "#/components/schemas/CredentialOrdinalNumber" ConversationChannelCredentials: type: object description: Enables access to the underlying messaging channel. allOf: - $ref: "#/components/schemas/ChannelCredentialsTypes" - $ref: "#/components/schemas/ChannelCredentialsCommonTypes" ConversationDirection: type: string default: UNDEFINED_DIRECTION enum: - UNDEFINED_DIRECTION - TO_APP - TO_CONTACT ConversationMergeStrategy: type: string default: MERGE enum: - MERGE InjectMessageRequest: description: A message on a particular channel. type: object title: Conversation Message Injected allOf: - $ref: "#/components/schemas/ConversationMessageTypesInject" - $ref: "#/components/schemas/InjectMessageCommonProps" InjectMessageCommonProps: type: object required: - channel_identity - contact_id - direction - accept_time 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 channel_identity: $ref: "#/components/schemas/ChannelIdentity" contact_id: description: The ID of the contact registered in the conversation provided. type: string direction: $ref: "#/components/schemas/ConversationDirection" conversation_id: type: string description: The ID of the conversation. injected: description: Flag for whether this message was injected. type: boolean readOnly: true sender_id: description: For Contact Messages the sender ID is the contact sent the message to. For App Messages the sender that was used to send the message, if applicable. type: string processing_mode: $ref: "#/components/schemas/ProcessingMode" 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 allOf: - $ref: "#/components/schemas/ConversationMessageTypes" - $ref: "#/components/schemas/ConversationMessageCommonProps" ConversationMessageTypes: type: object oneOf: - type: object properties: app_message: $ref: "#/components/schemas/AppMessage" title: "App Message" - type: object properties: contact_message: $ref: "#/components/schemas/ContactMessage" title: "Contact Message" ConversationMessageTypesInject: type: object oneOf: - required: - app_message type: object properties: app_message: $ref: "#/components/schemas/AppMessage" title: "App Message to be injected" - required: - contact_message type: object properties: contact_message: $ref: "#/components/schemas/ContactMessage" title: "Contact Message to be injected" ConversationMessageCommonProps: type: object properties: accept_time: description: The time Conversation API processed the message. type: string format: date-time readOnly: true channel_identity: $ref: "#/components/schemas/ChannelIdentity" contact_id: description: The ID of the contact. type: string 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 sender_id: description: For Contact Messages the sender ID is the contact sent the message to. For App Messages the sender that was used to send the message, if applicable. type: string processing_mode: $ref: "#/components/schemas/ProcessingMode" ConversationMetadataReportView: type: string default: NONE description: |- NONE - Omit metadata. FULL - Include all metadata assigned to the conversation. 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 FallbackMessageField: description: Fallback message. Used when original contact message can not be handled. type: object title: Fallback properties: fallback_message: title: Fallback Message type: object properties: raw_message: description: Optional. The raw fallback message if provided by the channel. type: string reason: $ref: "#/components/schemas/Reason" IdentifiedByField: type: object title: Channel Identities properties: identified_by: title: Channel Identity List type: object description: The identity as specified by the channel. required: - channel_identities properties: channel_identities: type: array items: $ref: "#/components/schemas/ChannelRecipientIdentity" KakaoTalkCredentialsField: type: object title: KakaoTalk properties: kakaotalk_credentials: type: object title: KakaoTalk Credentials 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 LocationMessageField: type: object description: Message containing geographic location. title: Location properties: location_message: title: Location Message type: object required: - coordinates - title properties: coordinates: $ref: "#/components/schemas/Coordinates" label: description: Label or name for the position. type: string title: description: The title is shown close to the button or link that leads to a map showing the location. The title can be clickable in some cases. type: string MMSCredentialsField: type: object title: MMS properties: mms_credentials: type: object title: MMS Credentials 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/BasicAuthCredentials" CardMessageMediaMessage: type: object title: Media message description: A message containing an image media component. required: - url properties: url: description: Url to the media file. type: string MediaCardMessageField: type: object title: Media Card description: A message containing a media component, such as an image or video. properties: media_card_message: type: object title: Media Card Message required: - url properties: caption: description: "Caption for the media on supported channels." type: string url: description: Url to the media file. type: string MediaMessageField: type: object title: Media description: A message containing a media component, such as an image, document, or video. properties: media_message: title: Media Message type: object required: - url properties: thumbnail_url: type: string description: An optional parameter. Will be used where it is natively supported. url: description: Url to the media file. type: string filename_override: description: Overrides the media file name. type: string ChoiceItem: type: object title: Choice description: A message component for interactive messages, containing a choice. required: - title properties: title: type: string description: Required parameter. Title for the choice item. description: type: string description: Optional parameter. The description (or subtitle) of this choice item. media: type: object description: Optional parameter. The media of this choice item. $ref: "#/components/schemas/MediaMessageField" postback_data: type: string description: Optional parameter. Postback data that will be returned in the MO if the user selects this option. ProductItem: type: object title: Product description: A message component for interactive messages, containing a product. required: - id - marketplace properties: id: type: string description: Required parameter. The ID for the product. marketplace: type: string description: Required parameter. The marketplace to which the product belongs. example: FACEBOOK quantity: type: integer format: int32 description: Output only. The quantity of the chosen product. item_price: type: number format: float description: Output only. The price for one unit of the chosen product. currency: type: string description: Output only. The currency of the item_price. ListItem: type: object title: List Item description: Item containing either choiceItem or ProductItem oneOf: - required: - choice type: object properties: choice: $ref: "#/components/schemas/ChoiceItem" title: Choice - required: - product type: object properties: product: $ref: "#/components/schemas/ProductItem" title: Product ProductResponseMessage: type: object title: Product Response Message description: Represents an interactive WhatsApp message containing ProductItem objects required: - products properties: products: description: "The selected products." type: array items: $ref: "#/components/schemas/ProductItem" title: description: "Optional parameter. Text that may be sent with selected products." type: string catalog_id: description: "Optional parameter. The catalog id that the selected products belong to." type: string ListSection: type: object title: List Section description: Section for interactive WhatsApp messages containing ListItem required: - items properties: title: description: "Optional parameter. Title for list section." type: string items: type: array items: $ref: "#/components/schemas/ListItem" ListMessageField: type: object title: List description: A message containing a list of options to choose from properties: list_message: title: List Message type: object required: - title - sections properties: title: description: "A title for the message that is displayed near the products or choices." type: string description: description: "This is an optional field, containing a description for the message." type: string 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: Select the priority type for the message default: NORMAL_PRIORITY example: NORMAL_PRIORITY enum: - NORMAL_PRIORITY - HIGH_PRIORITY QueueStats: type: object properties: outbound_size: description: |- The current size of the App's MT queue. type: integer format: int64 readOnly: true outbound_limit: description: |- The limit of the App's MT queue. The default limit is 500000 messages. type: integer format: int64 readOnly: true 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: enum: - UNKNOWN - INTERNAL_ERROR - RATE_LIMITED - RECIPIENT_INVALID_CHANNEL_IDENTITY - RECIPIENT_NOT_REACHABLE - RECIPIENT_NOT_OPTED_IN - OUTSIDE_ALLOWED_SENDING_WINDOW - CHANNEL_FAILURE - CHANNEL_BAD_CONFIGURATION - CHANNEL_CONFIGURATION_MISSING - MEDIA_TYPE_UNSUPPORTED - MEDIA_TOO_LARGE - MEDIA_NOT_REACHABLE - NO_CHANNELS_LEFT - TEMPLATE_NOT_FOUND - TEMPLATE_INSUFFICIENT_PARAMETERS - TEMPLATE_NON_EXISTING_LANGUAGE_OR_VERSION - DELIVERY_TIMED_OUT - DELIVERY_REJECTED_DUE_TO_POLICY - CONTACT_NOT_FOUND - BAD_REQUEST - UNKNOWN_APP - NO_CHANNEL_IDENTITY_FOR_CONTACT - CHANNEL_REJECT - NO_PERMISSION - NO_PROFILE_AVAILABLE - UNSUPPORTED_OPERATION 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: enum: - UNSPECIFIED_SUB_CODE - ATTACHMENT_REJECTED - MEDIA_TYPE_UNDETERMINED - INACTIVE_SENDER 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: description: Identifies the recipient. allOf: - $ref: "#/components/schemas/RecipientBase" RecipientRequest: type: object description: Identifies the recipient. If [Dispatch Mode](https://developers.sinch.com/docs/conversation/processing-modes/) is used, you must use the `identified_by` field. allOf: - $ref: "#/components/schemas/RecipientBase" RecipientBase: type: object oneOf: - $ref: "#/components/schemas/ContactIDField" - $ref: "#/components/schemas/IdentifiedByField" ReplyToField: 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 properties: reply_to: title: Reply To type: object 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: enum: - MESSAGE_EXPIRE_POLICY - CONVERSATION_EXPIRE_POLICY - PERSIST_RETENTION_POLICY 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](/docs/conversation/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](/docs/conversation/processing-modes/). enum: - CONVERSATION - DISPATCH 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. Note that this functionality is available for open 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 CallbackSettings: description: This object contains additional settings related to callback processing. type: object properties: secret_for_overridden_callback_urls: description: Optional. Secret can be used to sign contents of delivery receipts for a message that was sent with the default callback URL overridden (using the [`callback_url` field](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/Messages/#tag/Messages/operation/Messages_SendMessage!path=callback_url&t=request)). You can then use the secret to verify the signature. type: string format: password DeliveryReportBasedFallback: description: This object contains additional settings related to [delivery report based fallback](/docs/conversation/keyconcepts/#delivery-report-base-message-fallback). Note that this **paid** functionality is available for open beta testing. type: object properties: enabled: description: Optional. A flag specifying whether this app has enabled fallback message delivery upon no positive delivery report. This feature is applicable only to messages which are sent to a recipient with more than one channel identity. Identities must be defined on channels which support at least the 'DELIVERED' message state. **Please note that this functionality requires payment.** type: boolean default: false delivery_report_waiting_time: description: Optional. The time, in seconds, after which a message without a positive delivery report will fallback to the next channel. The valid values for this field are [60 - 259200]. type: integer format: int32 MessageRetrySettings: description: This object contains settings related to message retry mechanism. type: object properties: retry_duration: description: The maximum duration, in seconds, during which the system will retry sending a message in the event of a temporary processing failure. Time is counted after the first message processing failure. At least one retry is guaranteed. Subsequent retry instances are randomized with exponential backoff. If the next retry timestamp exceeds the configured time, one final retry will be performed on the cut-off time. The valid values for this field are [30 - 3600]. type: integer format: int32 default: 3600 StaticBearerCredentialsField: type: object title: Static Bearer Authentication properties: static_bearer: description: This object is required for channels which use a bearer-type of credential for authentication. type: object required: - claimed_identity - token title: Static Bearer Credentials properties: claimed_identity: description: The claimed identity for the channel. type: string token: description: The static bearer token for the channel. type: string format: password StaticTokenCredentialsField: type: object title: Static Token Authentication properties: static_token: type: object description: This object is required for channels which use a static token credential for authentication. required: - token title: Static Token Credentials properties: token: description: The static token for the channel. type: string format: password TelegramCredentialsField: type: object title: Telegram properties: telegram_credentials: type: object title: Telegram Credentials 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}}" format: password LineCredentialsField: type: object title: LINE properties: line_credentials: type: object title: LINE Credentials required: - token - secret description: If the `channel` property is set to `LINE` for this entry of the `channel_credentials` array, you must include either the `line_credentials` object or the `line_enterprise_credentials` object in the entry as well. 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. format: password example: "{{LINE_SECRET}}" is_default: type: boolean description: When an app contains multiple LINE or LINE Enterprise credentials, one of the credentials needs to be defined as the default. Setting this property to `true` marks the corresponding credentials as the default credentials. default: false LineCredentialsJapanField: type: object title: LINE Credentials Japan properties: line_credentials_japan: type: object title: LINE Credentials Japan required: - token - secret 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. format: password example: "{{LINE_SECRET}}" LineCredentialsThailandField: type: object title: LINE Credentials Thailand properties: line_credentials_thailand: type: object title: LINE Credentials Thailand required: - token - secret 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. format: password example: "{{LINE_SECRET}}" LineEnterpriseCredentialsField: type: object title: LINE Enterprise properties: line_enterprise_credentials: type: object title: LINE Enterprise Credentials description: If the `channel` property is set to `LINE` for this entry of the `channel_credentials` array, you must include either the `line_credentials` object or the `line_enterprise_credentials` object in the entry as well. oneOf: - $ref: "#/components/schemas/LineCredentialsJapanField" - $ref: "#/components/schemas/LineCredentialsThailandField" properties: is_default: type: boolean description: When an app contains multiple LINE or LINE Enterprise credentials, one of the credentials needs to be defined as the default. Setting this property to `true` marks the corresponding credentials as the default credentials. default: false WeChatCredentialsField: type: object title: WeChat properties: wechat_credentials: type: object title: WeChat Credentials 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. format: password 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}}" InstagramCredentialsField: type: object title: Instagram properties: instagram_credentials: type: object title: Instagram Credentials required: - token description: If you are including the INSTAGRAM channel in the `channel_identifier` property, you must include this object. properties: token: type: string description: The static token. format: password business_account_id: type: string description: Required if using the Sinch Facebook App. AppleBcCredentialsField: type: object title: Apple Business Chat properties: applebc_credentials: type: object title: Apple Business Chat Credentials required: - business_chat_account_id description: If you are including the AppleBC channel in the `channel_identifier` property, you must include this object. properties: business_chat_account_id: type: string description: The ID that identifies a Business Chat Account (BCA). merchant_id: type: string description: Merchant ID, required if our client wants to use Apple Pay. apple_pay_certificate_reference: type: string description: Certificate reference, required if our client wants to use Apple Pay. apple_pay_certificate_password: type: string format: password description: Certificate password, required if our client wants to use Apple Pay. KakaoTalkChatCredentialsField: type: object title: KakaoTalkChat properties: kakaotalkchat_credentials: type: object title: KakaoTalkChat Credentials required: - kakaotalk_plus_friend_id description: If you are including the KakaoTalkChat channel in the `channel_identifier` property, you must include this object. properties: kakaotalk_plus_friend_id: type: string description: Kakaotalk Plus friend ID. api_key: type: string description: InfoBank API KEY. TemplateMessageField: type: object description: Message referring to predefined template title: Template Message properties: template_message: type: object title: Template Message properties: channel_template: description: |- Optional. Channel specific template reference with parameters per channel. 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: allOf: - required: - version - $ref: "#/components/schemas/TemplateReference" TemplateReferenceField: type: object title: Template (Reference) properties: template_reference: allOf: - required: - version - $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 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`. Note that, when creating/updating a template using the [Sinch Customer Dashboard](https://dashboard.sinch.com/), the latest version of a given template can be identified by populating this field with `latest`. type: string TextMessageField: type: object title: Text description: A message containing only text. properties: text_message: type: object title: Text Message required: - text properties: text: description: The text to be sent. type: string UrlMessageField: description: A generic URL message. type: object title: URL properties: url_message: title: URL Message type: object required: - title - url properties: title: description: The title shown close to the URL. The title can be clickable in some cases. type: string url: description: The url to show. type: string 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 format: password 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 - 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. - `CONTACT_IDENTITIES_DUPLICATION`: Subscribe to get an event when contact identity duplications are found during message or event processing. - `CHANNEL_EVENT`: Subscribe to direct channel event. - `SMART_CONVERSATION`: Subscribe to Smart conversation analysis. - `RECORD_NOTIFICATION`: Subscribe to Record Notifications. - `MESSAGE_SUBMIT`: Subscribe to message submit Notifications. 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 - CONTACT_IDENTITIES_DUPLICATION - CHANNEL_EVENT - SMART_CONVERSATION - RECORD_NOTIFICATION - MESSAGE_SUBMIT ConversationMessagesView: type: string default: WITH_METADATA x-enumDescriptions: WITH_METADATA: View the message with metadata. WITHOUT_METADATA: View the message without 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: $ref: "#/components/schemas/Recipient" 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: $ref: "#/components/schemas/Recipient" 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: $ref: "#/components/schemas/Recipient" 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 receipts for this message The REST URL should be of the form: `http://host[:port]/path` type: string channel_priority_order: description: |- Optional. A single element array that dictates on what channel should the Conversation API try to send the event. It overrides any default set on the contact. Providing more than one option has no effect. type: array items: $ref: "#/components/schemas/ConversationChannel" event: $ref: "#/components/schemas/AppEventField" event_metadata: description: Optional. Eventual metadata that should be associated to the event. type: string queue: $ref: "#/components/schemas/MessageQueue" recipient: $ref: "#/components/schemas/RecipientRequest" 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 receipts for this message. Note that you may [define a `secret_for_overridden_callback_urls` at the app level](https://developers.sinch.com/docs/conversation/api-reference/conversation/tag/App/#tag/App/operation/App_UpdateApp!path=callback_settings/secret_for_overridden_callback_urls&t=request); this secret will be used to sign the contents of delivery receipts when the default callback URL is overridden by this property. The REST URL should be of the form: `http://host[:port]/path` type: string channel_priority_order: description: |- Explicitly define the channels and order in which they are tried when sending the message. All channels provided in this field must be configured in the corresponding Conversation API app, or the request will be rejected. 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). Up to 1024 characters long. type: string conversation_metadata: description: |- Metadata that will be associated with the conversation in `CONVERSATION` mode and with the specified recipient identities in `DISPATCH` mode. This metadata will be propagated on MO callbacks associated with the respective conversation or user identity. Up to 2048 characters long. Note that the MO callback will always use the last metadata available. 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: $ref: "#/components/schemas/RecipientRequest" ttl: description: |- The timeout allotted for sending the message, expressed in seconds. Passed to channels which support it and emulated by the Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with an expired TTL. The format is an integer with the suffix `s` (for seconds). Valid integer range is 3 to 315,576,000,000 (inclusive). Example values include `10s` (10 seconds) and `86400s` (24 hours). type: string processing_strategy: $ref: "#/components/schemas/ProcessingStrategy" correlation_id: type: string description: |- An arbitrary identifier that will be propagated to callbacks related to this message, including MO messages from the recipient. The `correlation_id` is associated with the conversation in `CONVERSATION` mode and with the specified recipient identities in `DISPATCH` mode. The MO callbacks will always include the last `correlation_id` available, (which is similar to how the `conversation_metadata` property functions). Up to 128 characters long. conversation_metadata_update_strategy: $ref: '#/components/schemas/MetadataUpdateStrategy' message_content_type: $ref: '#/components/schemas/MessageContentType' MessageContentType: description: This field classifies the message content for use with Sinch's [consent management functionality](https://developers.sinch.com/docs/conversation/consent-management/). Note that this field is currently only used with Sinch's consent management functionality, and is not referenced elsewhere by the Conversation API. type: string x-enumDescriptions: CONTENT_UNKNOWN: The default content type, when the content is not clearly defined, can be any type of content. CONTENT_MARKETING: Type that indicates that the content is related to Marketing, like marketing campaign messages. CONTENT_NOTIFICATION: Type that indicates that the content is related to Notifications, like charges and alerts. default: CONTENT_UNKNOWN ProcessingStrategy: description: Overrides the app's [Processing Mode](/docs/conversation/processing-modes/). Default value is `DEFAULT`. enum: - DEFAULT - DISPATCH_ONLY x-enumDescriptions: DEFAULT: The request will inherit the app's configured processing mode. DISPATCH_ONLY: Forces the request to be processed in dispatch mode (without storing contacts and conversations), regardless of the app's configured processing mode. Please note that user replies will still be processed in the app's default processing mode and that the `conversation_metadata` and `correlation_id` fields are not supported when using this option with an app in `CONVERSATION` mode. type: string default: DEFAULT MetadataUpdateStrategy: enum: - REPLACE - MERGE_PATCH description: Update strategy for the `conversation_metadata` field. Only supported in `CONVERSATION` processing mode. 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. type: string default: REPLACE 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 NameInfo: type: object title: Name of the contact description: Name information of the contact. required: - full_name properties: full_name: description: Full name of the contact type: string first_name: description: First name. type: string last_name: description: Last name. type: string middle_name: description: Middle name. type: string prefix: description: Prefix before the name. e.g. Mr, Mrs, Dr etc. type: string suffix: description: Suffix after the name. type: string PhoneNumberInfo: type: object title: Phone number description: Phone numbers of the contact. required: - phone_number properties: phone_number: description: Phone number with country code included. type: string type: description: Phone number type, e.g. WORK or HOME. type: string AddressInfo: type: object title: Address information description: Physical addresses of the contact. properties: city: description: City Name type: string country: description: Country Name type: string state: description: Name of a state or region of a country. type: string zip: description: Zip/postal code type: string type: description: Address type, e.g. WORK or HOME type: string country_code: description: Two letter country code. type: string EmailInfo: type: object title: Email information description: Email addresses of the contact. required: - email_address properties: email_address: description: Email address. type: string type: description: Email address type. e.g. WORK or HOME. type: string OrganizationInfo: type: object title: Organization information description: Organization information of the contact. properties: company: description: Company name type: string department: description: Department at the company type: string title: description: Corporate title, e.g. Software engineer type: string UrlInfo: type: object title: URL Info description: A URL/website required: - url properties: url: description: The URL to be referenced type: string type: description: Optional. URL type, e.g. Org or Social type: string ContactInfoMessageField: type: object description: Message containing contact information. title: Contact Info properties: contact_info_message: title: Contact Info Message type: object required: - name - phone_numbers properties: name: $ref: "#/components/schemas/NameInfo" phone_numbers: description: Phone numbers of the contact type: array items: $ref: "#/components/schemas/PhoneNumberInfo" addresses: description: Physical addresses of the contact type: array items: $ref: "#/components/schemas/AddressInfo" email_addresses: description: Email addresses of the contact type: array items: $ref: "#/components/schemas/EmailInfo" organization: $ref: "#/components/schemas/OrganizationInfo" urls: description: URLs/websites associated with the contact type: array items: $ref: "#/components/schemas/UrlInfo" birthday: description: Date of birth in YYYY-MM-DD format. type: string ChannelIntegrationStatus: description: Status of the channel credentials integration x-enumDescriptions: PENDING: Initial status when the channel has been activated in the front-end. ACTIVE: Credentials have been successfully validated and exchanged for a long-lived token. This status is used by default for channels in which the credential can't be validated. FAILING: Failed to validate credentials and acquire a long-lived token. default: PENDING type: string enum: - PENDING - ACTIVE - FAILING ChannelIntegrationState: type: object title: Channel Integration State description: State of the channel credentials integration. required: - status properties: status: $ref: "#/components/schemas/ChannelIntegrationStatus" description: description: Description in case the integration fails type: string ConversationEvent: type: object title: Conversation Event description: An event on a particular channel. required: - id - channel_identity - processing_mode properties: direction: $ref: "#/components/schemas/ConversationDirection" event: type: object description: The content of the events. oneOf: - $ref: "#/components/schemas/AppEventField" - $ref: "#/components/schemas/ContactEventField" - $ref: "#/components/schemas/ContactMessageEventField" id: type: string description: The ID of the event. conversation_id: type: string description: Optional. The ID of the event's conversation. Will not be present for apps in Dispatch Mode. contact_id: type: string description: Optional. The ID of the contact. Will not be present for apps in Dispatch Mode. channel_identity: $ref: "#/components/schemas/ChannelIdentity" accept_time: type: string format: date-time processing_mode: $ref: "#/components/schemas/ProcessingMode" InjectConversationEventRequest: description: Inject Event request type: object title: Inject event request required: - event - accept_time properties: event: type: object description: The content of the events. oneOf: - $ref: "#/components/schemas/AppEventField" conversation_id: type: string description: Optional. The ID of the event's conversation. Will not be present for apps in Dispatch Mode. contact_id: type: string description: Optional. The ID of the contact. Will not be present for apps in Dispatch Mode. channel_identity: $ref: "#/components/schemas/ChannelIdentity" accept_time: type: string description: The processed time of the message in UTC timezone. Must be less than current_time and greater than (current_time - 30 days). format: date-time processing_mode: $ref: "#/components/schemas/ProcessingMode" ContactEventField: type: object title: Contact Event Type properties: contact_event: title: Contact Event type: object description: Message originating from a contact oneOf: - $ref: "#/components/schemas/ComposingEventField" - $ref: "#/components/schemas/ComposingEndEventField" - $ref: "#/components/schemas/ConversationDeletedEventField" - $ref: "#/components/schemas/CommentEventField" - $ref: "#/components/schemas/GenericEventField" ContactMessageEventField: type: object title: Contact Message Event Type properties: contact_message_event: type: object title: Contact Message Event oneOf: - $ref: "#/components/schemas/PaymentStatusUpdateEventField" CommentEventField: type: object title: Comment Event Type properties: comment_event: type: object title: Comment Event description: The user sent a comment outside of the main conversation context required: - text properties: id: type: string description: Optional. An identifier for the comment. text: type: string description: Required. The text of the comment. comment_type: type: string description: Optional. The type of the comment. commented_on: type: string description: Optional. The origin of the comment user: type: string description: Optional. The user that triggered the comment event PaymentStatusUpdateEventField: type: object title: Payment Status Update Event Type properties: payment_status_update_event: type: object title: Payment Status Update Event description: Message specific only for Payments feature to reflect current state of particular Payment Flow. properties: reference_id: type: string description: This is the partner supplied ID to identify the order for payments payment_status: $ref: "#/components/schemas/PaymentStatus" payment_transaction_status: $ref: "#/components/schemas/PaymentTransactionStatus" payment_transaction_id: type: string description: Unique id of the transaction for which one of the transaction payment_transaction_status is present in event. PaymentStatus: description: Status reflecting how payment flow goes x-enumDescriptions: PAYMENT_STATUS_UNKNOWN: The status value was not set. Treat it as null or not present field. PAYMENT_STATUS_NEW: The partner sent an order_details message but the user didn’t start a payment yet. PAYMENT_STATUS_PENDING: The user started the payment process and the payment object was created. PAYMENT_STATUS_CAPTURED: The payment was captured. PAYMENT_STATUS_CANCELED: The payment was canceled by the user and no retry is possible. PAYMENT_STATUS_FAILED: The payment attempt failed but the user can retry. enum: - PAYMENT_STATUS_UNKNOWN - PAYMENT_STATUS_NEW - PAYMENT_STATUS_PENDING - PAYMENT_STATUS_CAPTURED - PAYMENT_STATUS_CANCELED - PAYMENT_STATUS_FAILED default: PAYMENT_STATUS_UNKNOWN type: string PaymentTransactionStatus: description: Group of statuses of the user-initiated transaction changes. x-enumDescriptions: PAYMENT_STATUS_TRANSACTION_UNKNOWN: The transaction status value was not set. Treat it as null or not present field. PAYMENT_STATUS_TRANSACTION_PENDING: The transaction has started. PAYMENT_STATUS_TRANSACTION_FAILED: Transaction failed. PAYMENT_STATUS_TRANSACTION_SUCCESS: Transaction completed successfully. PAYMENT_STATUS_TRANSACTION_CANCELED: Transaction got cancelled. default: PAYMENT_STATUS_TRANSACTION_UNKNOWN type: string enum: - PAYMENT_STATUS_TRANSACTION_UNKNOWN - PAYMENT_STATUS_TRANSACTION_PENDING - PAYMENT_STATUS_TRANSACTION_FAILED - PAYMENT_STATUS_TRANSACTION_SUCCESS - PAYMENT_STATUS_TRANSACTION_CANCELED ListEventsResponse: type: object properties: events: description: List of ConversationsEvents. type: array items: $ref: "#/components/schemas/ConversationEvent" readOnly: true next_page_token: type: string description: Token that should be included in the next request to fetch the next page. ListRecentConversationsResponse: type: object properties: conversations: description: List of recent conversations type: array items: $ref: "#/components/schemas/ConversationRecentMessage" 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 ConversationRecentMessage: type: object properties: conversation: $ref: "#/components/schemas/Conversation" last_message: $ref: "#/components/schemas/ConversationMessage" InjectEventRequest: type: object title: Inject Event Request properties: event: $ref: "#/components/schemas/InjectConversationEventRequest" InjectEventResponse: type: object properties: event_id: type: string description: Event id. accepted_time: type: string format: date-time UpdateMessageMetadataRequest: type: object title: Update message request required: - metadata properties: metadata: type: string OmniMessageOverride: oneOf: - $ref: '#/components/schemas/TextMessageField' - $ref: '#/components/schemas/MediaMessageField' - $ref: '#/components/schemas/TemplateReferenceField' - $ref: '#/components/schemas/ChoiceMessageField' - $ref: '#/components/schemas/CardMessageField' - $ref: '#/components/schemas/CarouselMessageField' - $ref: '#/components/schemas/LocationMessageField' - $ref: '#/components/schemas/ContactInfoMessageField' - $ref: '#/components/schemas/ListMessageField' ChannelSpecificMessage: type: object title: Channel specific message description: A message containing a channel specific message (not supported by OMNI types). required: - message_type - message properties: message_type: type: string description: The type of the channel specific message. enum: - FLOWS - ORDER_DETAILS - ORDER_STATUS message: oneOf: - $ref: '#/components/schemas/FlowChannelSpecificMessage' - $ref: '#/components/schemas/PaymentOrderDetailsChannelSpecificMessage' - $ref: '#/components/schemas/PaymentOrderStatusChannelSpecificMessage' ChannelSpecificContactMessage: type: object title: Channel Specific Message description: A contact message containing a channel specific message (not supported by OMNI types). required: - message_type - message properties: message_type: type: string description: The message type. enum: - nfm_reply message: description: The message content. oneOf: - $ref: '#/components/schemas/WhatsAppInteractiveNfmReplyChannelSpecificContactMessage' ChannelSpecificCommonProps: type: object properties: header: description: The header of the interactive message. type: object oneOf: - $ref: "#/components/schemas/WhatsAppInteractiveTextHeader" - $ref: "#/components/schemas/WhatsAppInteractiveImageHeader" - $ref: "#/components/schemas/WhatsAppInteractiveDocumentHeader" - $ref: "#/components/schemas/WhatsAppInteractiveVideoHeader" discriminator: propertyName: type mapping: text: "#/components/schemas/WhatsAppInteractiveTextHeader" image: "#/components/schemas/WhatsAppInteractiveImageHeader" document: "#/components/schemas/WhatsAppInteractiveDocumentHeader" video: "#/components/schemas/WhatsAppInteractiveVideoHeader" body: $ref: "#/components/schemas/WhatsAppInteractiveBody" footer: $ref: "#/components/schemas/WhatsAppInteractiveFooter" FlowChannelSpecificMessage: allOf: - $ref: "#/components/schemas/ChannelSpecificCommonProps" - type: object title: Flow channel specific message description: A message type for sending WhatsApp Flows. required: - flow_id - flow_cta properties: flow_id: type: string description: ID of the Flow. flow_token: type: string description: Generated token which is an identifier. flow_mode: type: string description: The mode in which the flow is. default: published enum: - draft - published flow_cta: type: string description: Text which is displayed on the Call To Action button (20 characters maximum, emoji not supported). flow_action: type: string default: navigate enum: - navigate - data_exchange flow_action_payload: type: object properties: screen: type: string description: The ID of the screen displayed first. This must be an entry screen. data: type: object description: Data for the first screen. PaymentOrderDetailsChannelSpecificMessage: allOf: - $ref: "#/components/schemas/ChannelSpecificCommonProps" - type: object title: Payment Order Details channel specific message. description: A message type for sending WhatsApp Payment Requests. required: - payment properties: payment: type: object description: The payment order details content. required: - type - reference_id - type_of_goods - total_amount_value - order properties: type: type: string description: The type of the payment message. enum: - br reference_id: type: string description: Unique reference ID. type_of_goods: type: string description: The type of good associated with this order. enum: - digital-goods - physical-goods payment_settings: type: object description: The payment settings. required: - dynamic_pix properties: dynamic_pix: type: object description: The dynamic Pix payment settings. required: - code - merchant_name - key - key_type properties: code: type: string description: The dynamic Pix code to be used by the buyer to pay. merchant_name: type: string description: Account holder name. key: type: string description: Pix key. key_type: type: string description: Pix key type. enum: - CPF - CNPJ - EMAIL - PHONE - EVP total_amount_value: type: integer description: Integer representing the total amount of the transaction. order: type: object description: The payment order. required: - items - subtotal_value - tax_value properties: catalog_id: type: string description: Unique ID of the Facebook catalog being used by the business. expiration_time: type: string description: Expiration timestamp for the order. expiration_description: type: string description: Description of the expiration. subtotal_value: type: integer description: Value representing the subtotal amount of this order. tax_value: type: integer description: Value representing the tax amount for this order. tax_description: type: string description: Description of the tax for this order. shipping_value: type: integer description: Value representing the shipping amount for this order. shipping_description: type: string description: Shipping description for this order. discount_value: type: integer description: Value of the discount for this order. discount_description: type: string description: Description of the discount for this order. discount_program_name: type: string description: Discount program name for this order. items: type: array description: The items list for this order. items: type: object required: - retailer_id - name - amount_value - quantity properties: retailer_id: type: string description: Unique ID of the retailer. name: type: string description: Item's name as displayed to the user. amount_value: type: integer description: Price per item. quantity: type: integer description: Number of items in this order. sale_amount_value: type: integer description: Discounted price per item. PaymentOrderStatusChannelSpecificMessage: allOf: - $ref: "#/components/schemas/ChannelSpecificCommonProps" - type: object title: Payment Order Status channel specific message. description: A message type for sending WhatsApp Payment Status Requests. required: - payment properties: payment: type: object description: The payment order status message content required: - reference_id - order properties: reference_id: type: string description: Unique ID used to query the current payment status. order: type: object description: The payment order. required: - status properties: status: type: string description: The new payment message status. enum: - pending - processing - partially-shipped - shipped - completed - canceled description: type: string description: The description of payment message status update (120 characters maximum). WhatsAppInteractiveBody: type: object description: Body of the interactive message. required: - text properties: text: type: string description: The content of the message (1024 characters maximum). Emojis and Markdown are supported. WhatsAppInteractiveTextHeader: type: object description: Header of the interactive message with text. required: - type - text properties: type: type: string enum: - text text: type: string description: Text for the header. Formatting allows emojis, but not Markdown. WhatsAppInteractiveImageHeader: type: object description: Header of the interactive message with image. required: - type - image properties: type: type: string enum: - image image: $ref: "#/components/schemas/WhatsAppInteractiveHeaderMedia" WhatsAppInteractiveDocumentHeader: type: object description: Header of the interactive message with document. required: - type - document properties: type: type: string enum: - document document: $ref: "#/components/schemas/WhatsAppInteractiveHeaderMedia" WhatsAppInteractiveVideoHeader: type: object description: Header of the interactive message with video. required: - type - video properties: type: type: string enum: - video video: $ref: "#/components/schemas/WhatsAppInteractiveHeaderMedia" WhatsAppInteractiveHeaderMedia: type: object description: Media object for the header. required: - link properties: link: type: string description: URL for the media. WhatsAppInteractiveFooter: type: object description: Footer of the interactive message. required: - text properties: text: type: string description: The footer content (60 characters maximum). Emojis, Markdown and links are supported. WhatsAppInteractiveNfmReplyChannelSpecificContactMessage: type: object title: WhatsApp Interactive Nfm Reply Channel Specific Contact Message description: A WhatsApp interactive contact message containing the nfm_reply. required: - type - nfm_reply properties: type: type: string description: The interactive message type. default: nfm_reply enum: - nfm_reply nfm_reply: type: object description: The nfm reply message body. $ref: "#/components/schemas/WhatsAppInteractiveNfmReply" WhatsAppInteractiveNfmReply: type: object title: Nfm Reply description: The interactive nfm reply message. required: - name - response_json - body properties: name: type: string description: The nfm reply message type. enum: - flow - address_message response_json: type: string description: The JSON specific data. body: type: string description: The message body. securitySchemes: Basic: type: http scheme: basic description: For more information about basic authentication, see [Basic Authentication](/docs/conversation/api-reference/#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