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 reports 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 in that app. 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 dashboard.

Request
Security:
Basic
or
oAuth2
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

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
object (AppMessage)

Message originating from an app

callback_url
string

Overwrites the default callback url for delivery reports 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. 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" "LINE" "WECHAT"
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.

conversation_metadata
object

Metadata that should be associated with the conversation. This metadata will be propagated on MO callbacks associated with this conversation. Note that the MO callback will always use the last metadata avaliable 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.
project_id
string

The project ID.

queue
string (MessageQueue)

Not yet supported. This field is for future use.

Enum: "NORMAL_PRIORITY" "HIGH_PRIORITY"
ttl
string

The timeout allotted for sending the message. Passed onto channels which have support for it and emulated by Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with expired TTL.

processing_strategy
string (ProcessingStrategy)

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

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

Responses
200

A successful response.

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

Get a message

Retrieves a specific message by its ID.

Request
Security:
Basic
or
oAuth2
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: 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
accept_time
string <date-time>

The time Conversation API processed the message.

object (AppMessage)

Message originating from an app

object (ChannelIdentity)

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.

object (ContactMessage)

Message originating from a contact

conversation_id
string

The ID of the conversation.

direction
string (ConversationDirection)
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.

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
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const messageId = 'YOUR_message_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/messages/${messageId}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "accept_time": "2019-08-24T14:15:22Z",
  • "app_message": {
    • "message": {
      },
    • "explicit_channel_message": { },
    • "additionalProperties": {
      }
    },
  • "channel_identity": {
    • "app_id": "string",
    • "channel": "WHATSAPP",
    • "identity": "string"
    },
  • "contact_id": "string",
  • "contact_message": {
    • "choice_response_message": {
      },
    • "fallback_message": {
      },
    • "location_message": {
      },
    • "media_card_message": {
      },
    • "media_message": {
      },
    • "reply_to": {
      },
    • "text_message": {
      }
    },
  • "conversation_id": "string",
  • "direction": "UNDEFINED_DIRECTION",
  • "id": "string",
  • "metadata": "string",
  • "injected": true
}

Delete a message

Delete a specific message by its ID.

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

Request
Security:
Basic
or
oAuth2
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: 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
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const messageId = 'YOUR_message_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/messages/${messageId}`,
    {
      method: 'DELETE',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
null

List messages

This operation lists all messages sent or received via particular Processing Modes.

  • When using CONVERSATION mode, this operation lists messages associated with a conversation or a contact.
  • When using DISPATCH mode, this operation lists messages associated with an app.

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.

Request
Security:
Basic
or
oAuth2
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

One of conversation_id or contact_id needs to be present if messages_source is CONVERSATION_SOURCE.

contact_id
string

One of conversation_id or contact_id needs to be present if messages_source is CONVERSATION_SOURCE.

app_id
string

Id of the app. Required only when messages_source is DISPATCH_SOURCE.

page_size
integer <int32>

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

page_token
string

Next page token previously returned if any.

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

Responses
200

A successful response.

Response Schema: application/json
Array of objects (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
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/messages`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "messages": [
    • {
      }
    ],
  • "next_page_token": "string"
}