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.

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
app_id
required
string

The ID of the app sending the message.

required
Contact_Id (string) or Identified_By (object)

Identifies the recipient of the message. Requires either the contact_id or identified_by property.

required
object (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. Note that collection can't contain 'CHANNEL_UNSPECIFIED' value. 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"
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.

project_id
string

The project ID.

queue
string (MessageQueue)
Default: "NORMAL_PRIORITY"
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.

Responses
200A 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.

400Malformed request
401Incorrect credentials
403Correct credentials but you don't have access to the requested resource
500Correct credentials but you don't have access to the requested resource
501Something 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 message 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 conversation message ID.

Responses
200A successful response.
Response Schema: application/json
accept_time
string <date-time>

Output only.

object (Message originating from an app)
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

Required. The ID of the contact.

object (Message originating from a contact)
conversation_id
string

Required. The ID of the conversation.

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

Required. The ID of the message.

metadata
string

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

400Malformed request
401Incorrect credentials
403Correct credentials but you don't have access to the requested resource
500Correct credentials but you don't have access to the requested resource
501Something went wrong on our end, try again with exponential back-off
get/v1/projects/{project_id}/messages/{message_id}
Request samples
const fetch = require('node-fetch');

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);
Response samples
application/json
{
  • "accept_time": "2019-08-24T14:15:22Z",
  • "app_message": {
    • "message": {
      },
    • "explicit_channel_message": { },
    • "additionalProperties": "string"
    },
  • "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"
}

Deletes a message

Deletes a message that is part of a conversation. Removing the last message of a conversation will not 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 conversation message ID.

Responses
200A successful response.
Response Schema: application/json
any
400Malformed request
401Incorrect credentials
403Correct credentials but you don't have access to the requested resource
500Correct credentials but you don't have access to the requested resource
501Something went wrong on our end, try again with exponential back-off
delete/v1/projects/{project_id}/messages/{message_id}
Request samples
const fetch = require('node-fetch');

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);
Response samples
application/json
null