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 Channel Identities (object) (RecipientRequest)

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

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

Message originating from an app

callback_url
string

Overwrites the default callback url for delivery receipts for this message. To sign the contents of delivery receipts for which the default callback URL is overridden by this property, define a secret_for_overridden_callback_urls at the app level. 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 will be associated with the conversation in CONVERSATION mode and with the specified recipient identities in DISPATCH mode. This metadata will be propagated on MO callbacks associated with the respective conversation or user identity. Up to 2048 characters long. Note that the MO callback will always use the last metadata available. Important notes:

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

Currently only returned in the message_metadata field of an Inbound Message 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. 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_id
string

An arbitrary identifier that will be propagated to callbacks related to this message, including MO messages from the recipient. The correlation_id is associated with the conversation in CONVERSATION mode and with the specified recipient identities in DISPATCH mode. The MO callbacks will always include the last correlation_id available, (which is similar to how the conversation_metadata property functions). Up to 128 characters long.

conversation_metadata_update_strategy
string (MetadataUpdateStrategy)
Default: "REPLACE"

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

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.

message_content_type
string (MessageContentType)
Default: "CONTENT_UNKNOWN"

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.

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

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. See common error responses for more information.

401

Incorrect credentials. See common error responses for more information.

403

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

500

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

501

Something went wrong on our end, try again with exponential back-off. See common error responses for more information.

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 (object) or Carousel (object) or Choice (object) or Location (object) or Media (object) or Template Message (object) or Text (object) or List (object) or Contact Info (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 (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_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. See common error responses for more information.

401

Incorrect credentials. See common error responses for more information.

403

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

500

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

501

Something went wrong on our end, try again with exponential back-off. See common error responses for more information.

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 (object) or Carousel (object) or Choice (object) or Location (object) or Media (object) or Template Message (object) or Text (object) or List (object) or Contact Info (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 (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_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. See common error responses for more information.

401

Incorrect credentials. See common error responses for more information.

403

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

500

Correct credentials but you don't have access to the requested resource. See common error responses for more information.

501

Something went wrong on our end, try again with exponential back-off. See common error responses for more information.

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


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.


400
Malformed request. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


delete/v1/projects/{project_id}/messages/{message_id}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "message": "Malformed request",
  • "status": "INVALID_REQUEST",
  • "details": [ ]
}
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 Value Description
WITH_METADATA
View the message with metadata.


WITHOUT_METADATA
View the message 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. See common error responses for more information.


401
Incorrect credentials. See common error responses for more information.


403
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


500
Correct credentials but you don't have access to the requested resource. See common error responses for more information.


501
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.


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