Sinch Developer Documentation

Building blocks to enable rich customer communication


High level presentation of Sinch Conversation API and overview of its key concepts.

Introduction Beta

In its most basic use case, the Sinch Conversation API offers one single API endpoint for sending and receiving messages across the most popular channels using one unified format. For more advanced messaging use cases, it offers conversations, contacts, switching between Bot and Human chats and much more for the advanced chatbot and conversational messaging application developer.

Different message channel (bearer) features and functions are supported through built-in transcoding. As a developer, you have the option to use either a global message template and for it to be automatically transcoded to each message channel format, or simply ignore transcoding and specify an exact layout for the channel you are interested in.

The benefits of this approach are that a developer needs to only become familiar with one Messaging API and yet have the power of conversations across all supported channels, still offering full control over channel specific features if required.

Further, it doesn't matter which conversation channel the customer engages over, or switch between: a single callback contains all aspects of the conversation for easy integration into the Sinch portfolio of services, or any third-party platform.

Put simply, with the Sinch Conversation API, you are always in control of your customer conversation whether it be over SMS, RCS, WhatsApp or Facebook Messenger. Of course, the API will support additional channels as they become popular.

Currently, Sinch Conversation API is in closed beta. If you are interested in the early access program please contact a Sinch representative.

Key concepts

ER DiagramER Diagram


The project entity, in the ER-diagram above, is the root entity from the Conversation API's point-of-view. All the Conversation API resources are grouped under a project, which acts as a container. Each project, under the hood, belongs to a Sinch account created when creating an account in the Sinch Portal.


The app entity corresponds to the API user, 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.
The app is tied to a set of webhooks which defines the destination for various events coming from the Conversation API.
The easiest way to create and configure a Conversation API app is through the Sinch Portal
An app has the following configurable properties:

Display nameThe name visible in Sinch Portal
Conversation metadata report viewSpecifies the amount of conversation metadata that will be returned as part of each callback.
Retention PolicyThe retention policy specifies for how long messages, sent to or from an app, should be stored by the Conversation API
Retention policy

Each App has a retention policy that specifies for how long messages - sent to or from the App - should be stored.
The retention policy can be changed, programmatically, via the API by updating the corresponding app, or via the
Sinch Portal by editing the corresponding app.

A retention policy is defined by the following properties:

Retention Policy TypeType of the policy. See options below the table. The default is MESSAGE_EXPIRE_POLICY.
TTL daysThe days before a message or conversation is eligible for deletion. The allowed values are [1,3650] and the default value is 180 days.
Retention policy types
  • MESSAGE_EXPIRE_POLICY - this option will remove all messages, sent or received by the app, older than the TTL days specified in the policy.

  • CONVERSATION_EXPIRE_POLICY - this option only takes the last message in a conversation into consideration when deciding if a conversation should be removed or not. The entire conversation will be removed if the last message is older than the TTL days specified in the policy. The entire conversation will be kept otherwise.

  • PERSIST_RETENTION_POLICY - this option persists all messages, and conversations until they are explicitly deleted. Note that this option will be subject to additional charges in the future.

Channel credential

A channel credential is the authentication means used to authenticate against an underlying connected channel. A channel credential is tied to one app.
The order of the channel credentials registered for an app is significant. It defines the channel priority order on app level used when defining which channels to send first.
The app channel priority is overridden by contact channel priority order and by message specific channel priority order.

A channel credential has the following configurable properties:

ChannelWhich channel these credentials are used with.
CredentialSpecifies the type and values for the credentials used for a channel.
Callback SecretOptional. A secret for certain channels where Conversation API can validate callbacks coming from the channels.


A webhook is a POST capable URL destination for receiving callbacks from the Conversation API.
Beside URL, each webhook includes a set of triggers which dictates which events are to be sent to the webhook.

A webhook has the following configurable properties:

TargetThe target URL where events should be sent to
Target typeType of the target URL. Currently only DISMISS and HTTP are supported values. DISMISS indicates the events will not be sent
SecretOptional secret to be used to sign the content of Conversation API callbacks. Can be used to verify the integrity of the callbacks. See Validating Callbacks for details.
TriggersA set of triggers that this webhook is listening to. Example triggers include MESSAGE_DELIVERY for message delivery receipts and MESSAGE_INBOUND for inbound contact messages

Conversation API Callbacks provides more information about managing webhooks and the format of the callbacks.


The contact entity is a collection entity that groups together underlying connected channel recipient identities. It is tied to a specific project and is therefore considered public to all apps sharing the same project.

A contact has the following configurable properties:

Channel identitiesList of channel identities specifying how the contact is identified on underlying channels
Channel prioritySpecifies the channel priority order used when sending messages to this contact. This can be overridden by message specific channel priority order.
Display nameOptional display name used in chat windows and other UIs
EmailOptional Email of the contact
External idOptional identifier of the contact in external systems
MetadataOptional metadata associated with the contact.

Channel recipient identity

A channel recipient identity is an identifier for the contact for a specific channel. E.g. an international phone number is used as identifier for SMS and RCS while a PSID (Page-Scoped ID) is used as the identifier for Facebook Messenger.

Some channels use app-scoped channel identity. Currently, Facebook Messenger and Viber Bot are using app-scoped channel identities, which means contacts will have different channel identities for different apps.
For Facebook Messenger this means that the contact channel identity is associated with the app linked to the Facebook page for which this PSID is issued.

A channel recipient identity has the following configurable properties:

ChannelThe channel that this identity is used on
Channel recipient identityThe actual identity, e.g. an international phone number or email address.
App idThe Conversation API's app ID if this is app-scoped channel identity.


A collection entity that groups several conversation messages. It is tied to one specific app and one specific contact.

Conversation message

An individual message, part of a specific conversation.


There are currently three entities which can hold metadata: message, conversation and contact. The metadata is an opaque field for the Conversation API and can be used by the API clients to retrieve a context when receiving a callback from the API. The metadata fields are currently restricted to 1024 characters.

Supported channels

  • SMS
  • WhatsApp
  • RCS
  • Facebook messenger
  • Viber Business Messages
  • Viber Bot

Read more about them at Channel Support.

And more on the roadmap for 2021!


Currently Sinch Conversation API is available in:


The Conversation API uses OAuth2 Access Tokens to authenticate API calls. The first step to obtaining an Access Token is to create an Access Key in the Sinch portal under Settings -> Access Keys. A client_id and client_secret will be provided when creating an Access Key in the portal. The project ID will also be visible on the Access Key page in the portal. The created Access Key can be used in the different authentication flows in both regions. The following snippet illustrates how to obtain an Access Token that can be used to authenticate towards the Conversation API in the US.

curl -d grant_type=client_credentials --user <client_id>:<client_secret>



It is not possible to use the Access Token obtained from the US endpoint to authenticate towards the Conversation API in the EU. One should instead obtain a valid Access Token from the corresponding EU endpoint:

A call to the Conversation API, in the US, can then be done by including the obtained Access Token, valid for US, in the request header. See below for an example:

curl -H "Authorization: Bearer <access token>"<Project ID>/apps

Support for Basic Authentication

It is also possible to use Basic Authentication to authenticate towards the Conversation API. The recommendation is to use the OAuth2 flow, as described above, for increased security and throughput. The username and password correspond to the client_id and client_secret obtained when creating an Access Key. See below for an example of how to authenticate towards the Conversation API, in the US, using Basic Authentication. It is possible to authenticate towards the Conversation API, in the EU, in the same way since the created Access Key is valid for the EU region as well.

curl<Project ID>/apps --user <client_id>:<client_secret>

Postman collection

Sinch offers a Postman collection for easy setup and testing during development:

After importing the collection, fill in the following variables:

  • PROJECT with your Project ID

  • APP with your App ID

  • CLIENT_ID with your client ID

  • CLIENT_SECRET with your client secret.

For testing purposes fill WEBHOOK_URL by simply visiting
and use the generated link - the one under the 'Your unique URL' label.

Values for other variables can be obtained by calling corresponding requests:

  • CONTACT - ID of contact created by calling 'Create contact' request

  • WEBHOOK_ID - ID of webhook created by calling 'Create webhook' request

  • CONVERSATION - a Conversation is created automatically when sending a new message (for example with 'Text Message' request). Send a message, then call 'List conversations of App/Contact' to get the ID of conversation for this variable.


When requests are erroneous, the Sinch Conversation API will respond with standard HTTP status codes, such as 4xx for client errors and 5xx for server errors. All responses include a JSON body of the form:

  "error": {
    "code": 401,
    "message": "Request had invalid credentials.",
    "status": "UNAUTHENTICATED",
    "details": [{
      "@type": "",

The table below describes the fields of the error object:

NameDescriptionJSON Type
CodeHTTP status codeNumber
MessageA developer-facing error messageString
StatusResponse status nameString
DetailsList of detailed error descriptionsArray of objects

Common error responses

400Malformed request
401Incorrect credentials
403Correct credentials but you dont have access to the requested resource
500Something went wrong on our end, try again with exponential back-off
503Something went wrong on our end, try again with exponential back-off

Edit on GitHub

Updated 3 days ago


High level presentation of Sinch Conversation API and overview of its key concepts.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.