Skip to content
Conversation API/API reference/
/
List messages

Conversation API | Sinch (1.0)

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.

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}"
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.

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.

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"
recipientContact ID (object) or Channel Identities (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.​contact_idstring(Contact ID string)

The ID of the contact.

Example: "{CONTACT_ID}"
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