Skip to content
Conversation API/
/Messages

Conversation API | Sinch (1.0)

Overview

Send and receive messages globally over SMS, RCS, WhatsApp, Viber Business, Facebook messenger and other popular channels using the Sinch Conversation API.

Note:

If you would like help setting up your Conversation API solution, and want to quickly get started sending and receiving messages, review our Getting Started guide.

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.

Download the OpenAPI specification here.

Authentication

OAuth2.0 authentication

Achieve more secure API authentication with OAuth 2.0 access tokens.

Access tokens are short lived. Typically, they will only last one hour. This is done to keep your data (and ours) safer.

In exchanging credentials, you'll get a long string called an access token. This access token will serve as your bearer token in the authorization header of API calls.

Find your credentials in the Sinch Build Dashboard.

There are two pieces of information needed to obtain an access token: the key ID and key secret corresponding to your project ID.

To get an access token, do the following:

  1. Login to the Sinch Build Dashboard to get your access keys.

  2. Click on Create Access Key and when prompted, enter a display name, then click Confirm.

    Does it have to be a new key?

    Not at all. If you have existing credentials saved, feel free to use them.

  3. A Key ID and Key Secret will display. Save the project ID, key ID, and key secret someplace safe.

    Important!

    The key secret is only viewable at the time of initial creation.

    If you accidentally misplace they key secret, no worries! Create a new key.

  4. Using the following curl command, get your access token using the key ID and key secret.

    curl https://auth.sinch.com/oauth2/token \
-d grant_type=client_credentials \
-u YOUR_Key_ID:YOUR_Key_Secret

  5. You'll see your new access token in the response. Now you're ready to use this token on calls to the API. The access token will be useable for one hour.

Short lived

The access token is meant to be short lived for enhanced security. Generate one as often as it is necessary.

Basic authentication

HTTP Basic authentication works on all Sinch REST APIs. Basic auth is often the preferred option for testing because it is simple and easy to use.

Important!

Basic authentication is intended for test purposes only, and should only be used for experimenting with APIs and building prototypes. API calls using basic authentication are heavily rate limited, and these limits may change at any time without warning. Production systems should use OAuth access tokens instead.

Basic authentication is sent in the authorization header with each call.

No matter the programming language, there are three main components for successful basic authentication in a request:

  • The designation of authorization type, which is basic
  • The username, which in Sinch's case is YOUR_Key_ID, corresponding to your project
  • The password, which is YOUR_Key_Secret, again, corresponding to the project

You can view and manage your API credentials here.

Need help?

Check out this article for a walk-through on finding your key and secret.

To use basic auth in an API call, do the following:

  1. First, create a new access key in the Sinch Build Dashboard by clicking Create Access Key.

  2. Copy your project ID, key ID, and key secret.

    Important!

    Keep your key secret somewhere safe as it is only viewable upon initial project creation. The project ID and key ID are always readily available in the Sinch Build Dashboard. If you misplace your key secret, simply generate a new key!

  3. Use your key ID as the username (sometimes called the client_id) and your key secret as the password (can be referred to as the client_secret) in every call made to a Sinch API.

Base URL

The following URLs can be used when making calls to the Conversation API (or Template Management API, which is used in coordination with the Conversation API). The Conversation Batch API endpoints, which are available for beta testing, are also listed.

ServerURL
Conversation API (US Production)https://us.conversation.api.sinch.com
Conversation API (EU Production)https://eu.conversation.api.sinch.com
Conversation API (BR Production)https://br.conversation.api.sinch.com
Template Management API (US Production)https://us.template.api.sinch.com
Template Management API (EU Production)https://eu.template.api.sinch.com
Template Management API (BR Production)https://br.template.api.sinch.com
Conversation Batch API (Beta) (US)https://us.conversationbatch.api.sinch.com
Conversation Batch API (Beta) (EU)https://eu.conversationbatch.api.sinch.com
Conversation Batch API (Beta) (BR)https://br.conversationbatch.api.sinch.com

Note that, when making a call to the Conversation API or Template Management API, you must target the regional server that corresponds to the region in which you created your Conversation API app.

Postman collection

Sinch offers a Postman collection for easy setup and testing during development. For ease of use, follow the next link Postman Collection, into a Firefox browser or, use the Import option in Postman.

After importing the collection, fill in the following variables:

VariableValue
PROJECTYour PROJECT ID
APPYour app ID
CLIENT_IDYour CLIENT_ID
CLIENT_SECRETYour client secret

For testing purposes, fill the WEBHOOK_URL by visiting https://webhook.site/ and use the generated link - the one under the Your unique URL label.

Caution:

The https://webhook.site/ URL given above should only be used for testing purposes. Using the Conversation API can generate high volumes of callbacks, which can easily exceed the TPS limits of certain webhook services. Additionally, sensitive information may be included in the callback, including message content and contact information. Ensure that you use a scalable and secure callback/webhook processor after your initial testing is complete.

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 a Text Message request, send a message, then call List conversations to get the ID of the conversation for this variable.

Errors

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

{
  "error": {
    "code": 401,
    "message": "Request had invalid credentials.",
    "status": "UNAUTHENTICATED",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.RetryInfo",
      ...
    }]
  }
}

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

StatusDescription
400Malformed request. For example, the message body of a request made to the message/send endpoint does not contain the app_id field, which is required. Alternatively, this error may be triggered if required fields are included, but populated incorrectly. For example, the app_id field is included in a message/send request, but the value is not a ULID (and, therefore, fails a basic form check).
401Incorrect credentials. For example, you may get this error if you provide incorrect client_id and client_secret values when using basic authentication. You may also get this error if you provide a bearer token generated using incorrect basic authentication credentials or if you provide an expired token (generated using the OAuth2.0 client credentials flow).
403Correct credentials but you don't have access to the requested resource. This typically occurs paired with an UNAUTHORIZED message when the provided client_id and client_secret are not associated with the project_id required for most Conversation API calls. Starting February 19, 2025, this error may also be paired with a BILLING_CREDIT_LIMIT_BREACHED message. If paired with BILLING_CREDIT_LIMIT_BREACHED message, the project is blocked due to credit reasons. In this case, check your project's billing configuration and balance.
404The resources provided for the call are insufficient to complete the call, or the server cannot locate the required resources. For example, if the app_id provided in the call doesn't match a Conversation API app contained within the corresponding project, or the region in which the app was created does not match the regional server targeted by the call. Additionally, this error occurs if you provide designate Conversation API endpoint that doesn't actually exist.
429See Rate Limits.
500Something went wrong on our end, try again with exponential back-off
501Something went wrong on our end, try again with exponential back-off
503Something went wrong on our end, try again with exponential back-off

Rate Limits

The Conversation API has two kinds of rate limits that may result in status 429 Too Many Requests:

  • Conversation API apps have a maximum MT ingress queue size of 500000 messages, which are drained towards the channel at a rate of 20 messages per second by default (this rate may be higher if the channel has been purchased with a higher capacity).
  • Projects are limited to 800 requests per second across all apps and most endpoints. Making over 800 requests per second over an extended period of time may saturate the app-specific ingress queue, resulting in rate limiting.

In addition to project and app level limitations, each channel also has rate limitations that can affect performance, and may return a 429 Too Many Requests error. In some cases (for example, the SMS channel), these rate limits can be adjusted. In others (for example, the Instagram channel), they can't be adjusted. For more information about raising project, app, or channel rate limits, contact your Sinch account manager.

Download OpenAPI description
conversation.json
conversation.yaml
Overview
support at sinch

support@sinch.com

License

MIT

Languages
Servers
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.

https://{region}.conversation.api.sinch.com/

Messages

To start sending messages you must have a Conversation API app. 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 to create one.

Operations

Send a message

Request

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.

Security
Basic or oAuth2
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

Bodyapplication/jsonrequired

This is the request body for sending a message. app_id, recipient, and message are all required fields.

app_idstringrequired

The ID of the app sending the message.

Example: "{APP_ID}"
recipientChannel Identities (object) or Contact ID (object)(RecipientRequest)required

Identifies the recipient. If Dispatch Mode is used, you must use the identified_by field.

One of:

Identifies the recipient. If Dispatch Mode is used, you must use the identified_by field.

recipient.​identified_byobject(Channel Identity List)

The identity as specified by the channel.

messageCard (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(Message originating from app)required

A message originating from a Conversation API app

One of:

Field containing a Card Message

message.​card_messageobject(Card Message)

Message containing text, media and choices.

message.​explicit_channel_messageobject

Allows you to specify a channel and define a corresponding channel specific message payload that will override the standard Conversation API message types. The key in the map must point to a valid conversation channel as defined in the enum ConversationChannel. The message content must be provided in a string format. You may use the transcoding endpoint 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 (for example, using explicit channel messages with the WhatsApp channel).

message.​explicit_channel_omni_messageobject

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.

message.​channel_specific_messageobject

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.

message.​agentobject(Agent)

Represents an agent that is involved in a conversation.

callback_urlstring

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; 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

channel_priority_orderArray of strings(Channel Identifier)

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.
Items Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

MMS

The MMS channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

KAKAOTALKCHAT

The KakaoTalk chat channel (used primarily in ConsultationTalk).

Example: ["WHATSAPP"]
channel_propertiesobject

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.

message_metadatastring

Metadata that should be associated with the message. Returned in the metadata field of a Message Delivery Receipt. Up to 1024 characters long.

conversation_metadataobject

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.
  • If you send a message in DISPATCH mode while the retention period of the app is set to 0 (note that this value is set to 0 by default), the conversation_metadata field will not be retained.

Currently only returned in the message_metadata field of an Inbound Message callback.

queuestring(MessageQueue)

Select the priority type for the message

Default "NORMAL_PRIORITY"
Enum ValueDescription
NORMAL_PRIORITY

The normal priority queue.

HIGH_PRIORITY

The high priority queue.

Example: "NORMAL_PRIORITY"
ttlstring

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).

processing_strategystring(ProcessingStrategy)

Overrides the app's Processing Mode. Default value is DEFAULT.

Default "DEFAULT"
Enum ValueDescription
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.

correlation_idstring

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. Important note: If you send a message in DISPATCH mode while the retention period of the app is set to 0 (note that this value is set to 0 by default), the correlation_id field will not be retained.

conversation_metadata_update_strategystring(MetadataUpdateStrategy)

Update strategy for the conversation_metadata field. Only supported in CONVERSATION processing mode.

Default "REPLACE"
Enum ValueDescription
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.

message_content_typestring(MessageContentType)

This field classifies the message content for use with Sinch's consent management functionality. Note that this field is currently only used with Sinch's consent management functionality, and is not referenced elsewhere by the Conversation API.

Default "CONTENT_UNKNOWN"
Enum ValueDescription
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.

curl -i -X POST \
  -u <username>:<password> \
  'https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages:send' \
  -H 'Content-Type: application/json' \
  -d '{
    "app_id": "{APP_ID}",
    "recipient": {
      "identified_by": {
        "channel_identities": [
          {
            "channel": "{CHANNEL}",
            "identity": "{IDENTITY}"
          }
        ]
      }
    },
    "message": {
      "text_message": {
        "text": "This is a text message."
      }
    }
  }'

Responses

A successful response. More information is available in delivery report callbacks.

Bodyapplication/json
accepted_timestring(date-time)read-only

Timestamp when the Conversation API accepted the message for delivery to the referenced contact.

message_idstringread-only

The ID of the message.

Response
application/json
{
  "accepted_time": "2019-08-24T14:15:22Z",
  "message_id": "string"
}

Update message metadata

Request

Update a specific message metadata by its ID.

Security
Basic or oAuth2
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

message_idstringrequired

The unique ID of the message.

Query
messages_sourcestring

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.

Default "CONVERSATION_SOURCE"
Enum ValueDescription
CONVERSATION_SOURCE

The default messages source. Retrieves messages sent in the 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.

Bodyapplication/jsonrequired

Update message metadata request.

metadatastringrequired
curl -i -X PATCH \
  -u <username>:<password> \
  'https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages/{message_id}?messages_source=CONVERSATION_SOURCE' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": "New metadata value"
  }'

Responses

A successful response.

Bodyapplication/json
One of:

A message on a particular channel.

app_messageCard (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(Message originating from app)

A message originating from a Conversation API app

One of:

Field containing a Card Message

accept_timestring(date-time)read-only

The time Conversation API processed the message.

channel_identityobject(Channel Identity)

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.

contact_idstring

The ID of the contact.

conversation_idstring

The ID of the conversation.

directionstring(ConversationDirection)
Default "UNDEFINED_DIRECTION"
Enum ValueDescription
UNDEFINED_DIRECTION

The direction is undefined.

TO_APP

Sent to the Conversation API app.

TO_CONTACT

Sent to a recipient/contact from the Conversation API app.

idstring

The ID of the message.

metadatastring

Optional. Metadata associated with the contact. Up to 1024 characters long.

injectedbooleanread-only

Flag for whether this message was injected.

sender_idstring

For Contact Messages (MO messages), the sender ID represents the recipient to which the message was sent. This may be a phone number (in the case of SMS and MMS) or a unique ID (in the case of WhatsApp). This is field is not supported on all channels, nor is it supported for MT messages.

processing_modestring(ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Default "DISPATCH"
Enum ValueDescription
CONVERSATION

Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

The default Processing Mode. 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 and Conversation APIs.

Response
application/json
{
  "app_message": {
    "card_message": { … },
    "explicit_channel_message": { … },
    "explicit_channel_omni_message": { … },
    "channel_specific_message": { … },
    "agent": { … }
  },
  "accept_time": "2019-08-24T14:15:22Z",
  "channel_identity": {
    "app_id": "string",
    "channel": "WHATSAPP",
    "identity": "string"
  },
  "contact_id": "string",
  "conversation_id": "string",
  "direction": "UNDEFINED_DIRECTION",
  "id": "string",
  "metadata": "string",
  "injected": true,
  "sender_id": "string",
  "processing_mode": "CONVERSATION"
}

Get a message

Request

Retrieves a specific message by its ID.

Security
Basic or oAuth2
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

message_idstringrequired

The unique ID of the message.

Query
messages_sourcestring

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.

Default "CONVERSATION_SOURCE"
Enum ValueDescription
CONVERSATION_SOURCE

The default messages source. Retrieves messages sent in the 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.

curl -i -X GET \
  -u <username>:<password> \
  'https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages/{message_id}?messages_source=CONVERSATION_SOURCE'

Responses

A successful response.

Bodyapplication/json
One of:

A message on a particular channel.

app_messageCard (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(Message originating from app)

A message originating from a Conversation API app

One of:

Field containing a Card Message

accept_timestring(date-time)read-only

The time Conversation API processed the message.

channel_identityobject(Channel Identity)

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.

contact_idstring

The ID of the contact.

conversation_idstring

The ID of the conversation.

directionstring(ConversationDirection)
Default "UNDEFINED_DIRECTION"
Enum ValueDescription
UNDEFINED_DIRECTION

The direction is undefined.

TO_APP

Sent to the Conversation API app.

TO_CONTACT

Sent to a recipient/contact from the Conversation API app.

idstring

The ID of the message.

metadatastring

Optional. Metadata associated with the contact. Up to 1024 characters long.

injectedbooleanread-only

Flag for whether this message was injected.

sender_idstring

For Contact Messages (MO messages), the sender ID represents the recipient to which the message was sent. This may be a phone number (in the case of SMS and MMS) or a unique ID (in the case of WhatsApp). This is field is not supported on all channels, nor is it supported for MT messages.

processing_modestring(ProcessingMode)

Whether or not Conversation API should store contacts and conversations for the app. For more information, see Processing Modes.

Default "DISPATCH"
Enum ValueDescription
CONVERSATION

Creates contacts and conversations automatically when a message is sent or received and there's no existing contact or active conversation.

DISPATCH

The default Processing Mode. 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 and Conversation APIs.

Response
application/json
{
  "app_message": {
    "card_message": { … },
    "explicit_channel_message": { … },
    "explicit_channel_omni_message": { … },
    "channel_specific_message": { … },
    "agent": { … }
  },
  "accept_time": "2019-08-24T14:15:22Z",
  "channel_identity": {
    "app_id": "string",
    "channel": "WHATSAPP",
    "identity": "string"
  },
  "contact_id": "string",
  "conversation_id": "string",
  "direction": "UNDEFINED_DIRECTION",
  "id": "string",
  "metadata": "string",
  "injected": true,
  "sender_id": "string",
  "processing_mode": "CONVERSATION"
}

Delete a message

Request

Delete a specific message by its ID. Note that this operation deletes the message from Conversation API storage; this operation does not affect messages already delivered to recipients' handsets. Also note that removing all messages of a conversation will not automatically delete the conversation.

Security
Basic or oAuth2
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

message_idstringrequired

The unique ID of the message.

Query
messages_sourcestring

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.

Default "CONVERSATION_SOURCE"
Enum ValueDescription
CONVERSATION_SOURCE

The default messages source. Retrieves messages sent in the 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.

curl -i -X DELETE \
  -u <username>:<password> \
  'https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages/{message_id}?messages_source=CONVERSATION_SOURCE'

Responses

A successful response.

Response
No content

List messages

Request

This operation lists all messages sent or received via particular 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.

Security
Basic or oAuth2
Path
project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

Query
conversation_idstring

Resource name (ID) of the conversation.

contact_idstring

Resource name (ID) of the contact. Note that either app_id or contact_id is required in order for the operation to function correctly.

app_idstring

Id of the app.

channel_identitystring

Channel identity of the contact.

start_timestring(date-time)

Filter messages with accept_time after this timestamp. Must be before end_time if that is specified.

end_timestring(date-time)

Filter messages with accept_time before this timestamp.

page_sizeinteger(int32)

Maximum number of messages to fetch. Defaults to 10 and the maximum is 1000.

page_tokenstring

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.

viewstring(ConversationMessagesView)
Default "WITH_METADATA"
Enum ValueDescription
WITH_METADATA

View the message with metadata.

WITHOUT_METADATA

View the message without metadata.

messages_sourcestring

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.

Default "CONVERSATION_SOURCE"
Enum ValueDescription
CONVERSATION_SOURCE

The default messages source. Retrieves messages sent in the 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.

only_recipient_originatedboolean

If true, fetch only recipient originated messages. Available only when messages_source is DISPATCH_SOURCE.

channelstring(Channel Identifier)

Only fetch messages from the channel.

Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

MMS

The MMS channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

KAKAOTALKCHAT

The KakaoTalk chat channel (used primarily in ConsultationTalk).

Example: channel=WHATSAPP
curl -i -X GET \
  -u <username>:<password> \
  'https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages?conversation_id=string&contact_id=string&app_id=string&channel_identity=string&start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z&page_size=0&page_token=string&view=WITH_METADATA&messages_source=CONVERSATION_SOURCE&only_recipient_originated=true&channel=WHATSAPP'

Responses

A successful response.

Bodyapplication/json
messagesArray of App Message (object) or Contact Message (object)(Conversation Message)read-only

List of messages associated to the referenced conversation.

next_page_tokenstring

Token that should be included in the next request to fetch the next page.

Response
application/json
{
  "messages": [
    { … }
  ],
  "next_page_token": "string"
}

App

Apps are created and configured through the Sinch Dashboard, 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:

FieldDescription
Display nameThe name visible in the Sinch Dashboard.
Conversation metadata reportSpecifies the amount of conversationmetadata that's returned as part of each callback.
Retention PolicyThe retention policy specifies how long messages, sent to or from an app, are stored by the Conversation API.
Operations

Contact

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 processes. However, you can also use API calls to manually manage your contacts.

A contact has the following configurable properties:

FieldDescription
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.
Operations

Conversation

Endpoints for working with the conversation log.

Operations

Events

Endpoint for sending events.

Operations

Transcoding

Endpoint for transcoding generic message format to channel-specific one.

Operations

Capability

A capability query checks the options available for reaching the 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 for the CAPABILITY trigger.

Operations

Webhooks

Operations

Project Settings

Operations