Download OpenAPI specification:Download

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.

Send a message

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.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

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

Request Body schema: application/json
required

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

app_id
required
string

The ID of the app sending the message.

required
contact_id (object) or identified_by (object)

Identifies the recipient of the message. Requires either contact_id or identified_by. If Dispatch Mode is used, only identified_by is allowed.

required
Card Message (object) or Carousel Message (object) or Choice Message (object) or Location message (object) or Media message (object) or Template Message (object) or Text message (object) or List Message (object) or Contact Info Message (object) (AppMessage)

Message originating from an app

callback_url
string

Overwrites the default callback url for delivery receipts for this message The REST URL should be of the form: http://host[:port]/path

channel_priority_order
Array 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: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
object

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_metadata
string

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

conversation_metadata
object

Metadata that should be associated with the conversation. This metadata will be propagated on MO callbacks associated with this conversation. Up to 1024 characters long. Note that the MO callback will always use the last metadata available in the conversation. Important notes:

  • If you send a message with the conversation_metadata field populated, and then send another message without populating the conversation_metadata field, the original metadata will continue be propagated on the related MO callbacks.
  • If you send a message with the conversation_metadata field populated, and then send another message with a different value for conversation_metadata in the same conversation, the latest metadata value overwrites the existing one. So, future MO callbacks will include the new metadata.
  • The conversation_metadata only accepts json objects.

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

queue
string (MessageQueue)
Default: "NORMAL_PRIORITY"

Select the priority type for the message

Enum: "NORMAL_PRIORITY" "HIGH_PRIORITY"
ttl
string

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_strategy
string (ProcessingStrategy)
Default: "DEFAULT"

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

Enum Value Description
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.

correlation_id
string

An arbitrary identifier that will be propagated to callbacks related to this message, including MO replies. Only applicable to messages sent with the CONVERSATION processing mode. Up to 128 characters long.

conversation_metadata_update_strategy
string (MetadataUpdateStrategy)
Default: "REPLACE"

Update strategy for the conversation_metadata field.

Enum Value Description
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.

Responses
200

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

Response Schema: application/json
accepted_time
string <date-time>

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

message_id
string

The ID of the message.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

post/v1/projects/{project_id}/messages:send
Request samples
application/json
{
  • "app_id": "{APP_ID}",
  • "recipient": {
    • "contact_id": "{CONTACT_ID}"
    },
  • "message": {
    • "text_message": {
      }
    }
}
Response samples
application/json
{
  • "accepted_time": "2019-08-24T14:15:22Z",
  • "message_id": "string"
}

Update message metadata

Update a specific message metadata by its ID.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

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

message_id
required
string

The unique ID of the message.

query Parameters
messages_source
string
Default: "CONVERSATION_SOURCE"

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.

Enum Value Description
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.

Request Body schema: application/json
required

Update message metadata request.

metadata
required
string
Responses
200

A successful response.

Response Schema: application/json
One of:

A message on a particular channel.

Card Message (object) or Carousel Message (object) or Choice Message (object) or Location message (object) or Media message (object) or Template Message (object) or Text message (object) or List Message (object) or Contact Info Message (object) (AppMessage)

Message originating from an app

accept_time
string <date-time>

The time Conversation API processed the message.

object (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_id
string

The ID of the contact.

conversation_id
string

The ID of the conversation.

direction
string (ConversationDirection)
Default: "UNDEFINED_DIRECTION"
Enum: "UNDEFINED_DIRECTION" "TO_APP" "TO_CONTACT"
id
string

The ID of the message.

metadata
string

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

injected
boolean

Flag for whether this message was injected.

sender_id
string

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.

processing_mode
string (ProcessingMode)
Default: "CONVERSATION"

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

Enum Value Description
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 and Conversation APIs.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

patch/v1/projects/{project_id}/messages/{message_id}
Request samples
application/json
{
  • "metadata": "New metadata value"
}
Response samples
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

Retrieves a specific message by its ID.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

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

message_id
required
string

The unique ID of the message.

query Parameters
messages_source
string
Default: "CONVERSATION_SOURCE"

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.

Enum Value Description
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.

Responses
200

A successful response.

Response Schema: application/json
One of:

A message on a particular channel.

Card Message (object) or Carousel Message (object) or Choice Message (object) or Location message (object) or Media message (object) or Template Message (object) or Text message (object) or List Message (object) or Contact Info Message (object) (AppMessage)

Message originating from an app

accept_time
string <date-time>

The time Conversation API processed the message.

object (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_id
string

The ID of the contact.

conversation_id
string

The ID of the conversation.

direction
string (ConversationDirection)
Default: "UNDEFINED_DIRECTION"
Enum: "UNDEFINED_DIRECTION" "TO_APP" "TO_CONTACT"
id
string

The ID of the message.

metadata
string

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

injected
boolean

Flag for whether this message was injected.

sender_id
string

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.

processing_mode
string (ProcessingMode)
Default: "CONVERSATION"

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

Enum Value Description
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 and Conversation APIs.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

get/v1/projects/{project_id}/messages/{message_id}
Request samples 
Response samples 
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
Delete a specific message by its ID.


Note: Removing all messages of a conversation will not automatically delete the conversation.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
message_id
required
string
The unique ID of the message.


 
query Parameters
messages_source
string
 Default:  "CONVERSATION_SOURCE"
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.


 Enum Value Description
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.


 
Responses 
200
A successful response.


Response Schema: application/json
any
 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


delete/v1/projects/{project_id}/messages/{message_id}
Request samples 
Response samples 
application/json
{ }
List messages
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.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
query Parameters
conversation_id
string
Resource name (ID) of the conversation.


 
contact_id
string
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_id
string
Id of the app.


 
channel_identity
string
Channel identity of the contact.


 
start_time
string <date-time> 
Filter messages with accept_time after this timestamp. Must be before end_time if that is specified.


 
end_time
string <date-time> 
Filter messages with accept_time before this timestamp.


 
page_size
integer <int32> 
Maximum number of messages to fetch. Defaults to 10
and the maximum is 1000.


 
page_token
string
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.


 
view
string (ConversationMessagesView) 
 Default:  "WITH_METADATA"
 Enum: "WITH_METADATA" "WITHOUT_METADATA"  
messages_source
string
 Default:  "CONVERSATION_SOURCE"
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.


 Enum Value Description
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.


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


 
channel
string (Channel Identifier) 
Only fetch messages from the channel.


 Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"  
 Example:  channel=WHATSAPP
Responses 
200
A successful response.


Response Schema: application/json
Array of App Message (object) or Contact Message (object) (Conversation Message) 
List of messages associated to the referenced conversation.


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


 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


get/v1/projects/{project_id}/messages
Request samples 
Response samples 
application/json
{
  • "messages": [
    • {
      }
    ],
  • "next_page_token": "string"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.