Download OpenAPI specification:Download
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.
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.
project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
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 | ||||||||
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
The REST URL should be of the form: | ||||||||
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:
| ||||||||
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 | ||||||||
conversation_metadata | object Metadata that will be associated with the conversation in
Currently only returned in the | ||||||||
queue | string (MessageQueue) Default: "NORMAL_PRIORITY" Select the priority type for the message | ||||||||
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 | ||||||||
processing_strategy | string (ProcessingStrategy) Default: "DEFAULT" Overrides the app's Processing Mode. Default value is
| ||||||||
correlation_id | string An arbitrary identifier that will be propagated to callbacks related to this message,
including MO messages from the recipient. The | ||||||||
conversation_metadata_update_strategy | string (MetadataUpdateStrategy) Default: "REPLACE" Update strategy for the
| ||||||||
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.
|
A successful response. More information is available in delivery report callbacks.
Malformed request
Incorrect credentials
Correct credentials but you don't have access to the requested resource
Correct credentials but you don't have access to the requested resource
Something went wrong on our end, try again with exponential back-off
{- "app_id": "{APP_ID}",
- "recipient": {
- "contact_id": "{CONTACT_ID}"
}, - "message": {
- "text_message": {
- "text": "This is a text message."
}
}
}
{- "accepted_time": "2019-08-24T14:15:22Z",
- "message_id": "string"
}
Update a specific message metadata by its ID.
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. |
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.
|
Update message metadata request.
A successful response.
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 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.
|
Malformed request
Incorrect credentials
Correct credentials but you don't have access to the requested resource
Correct credentials but you don't have access to the requested resource
Something went wrong on our end, try again with exponential back-off
{- "metadata": "New metadata value"
}
{- "app_message": {
- "card_message": {
- "choices": [
- {
- "call_message": {
- "phone_number": "+15551231234",
- "title": "Message text"
}, - "postback_data": null
}
], - "description": "string",
- "height": "UNSPECIFIED_HEIGHT",
- "media_message": {
- "url": "string"
}, - "title": "string"
}, - "explicit_channel_message": { },
- "explicit_channel_omni_message": {
- "property1": {
- "text_message": {
- "text": "string"
}
}, - "property2": {
- "text_message": {
- "text": "string"
}
}
}, - "channel_specific_message": {
- "property1": {
- "message_type": "FLOWS",
- "message": {
- "header": {
- "type": "text",
- "text": "string"
}, - "body": {
- "text": "string"
}, - "footer": {
- "text": "string"
}, - "flow_id": "string",
- "flow_token": "string",
- "flow_mode": "draft",
- "flow_cta": "string",
- "flow_action": "navigate",
- "flow_action_payload": {
- "screen": "string",
- "data": { }
}
}
}, - "property2": {
- "message_type": "FLOWS",
- "message": {
- "header": {
- "type": "text",
- "text": "string"
}, - "body": {
- "text": "string"
}, - "footer": {
- "text": "string"
}, - "flow_id": "string",
- "flow_token": "string",
- "flow_mode": "draft",
- "flow_cta": "string",
- "flow_action": "navigate",
- "flow_action_payload": {
- "screen": "string",
- "data": { }
}
}
}
}, - "agent": {
- "display_name": "string",
- "type": "UNKNOWN_AGENT_TYPE",
- "picture_url": "string"
}
}, - "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"
}
Retrieves a specific message by its ID.
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. |
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.
|
A successful response.
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 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.
|
Malformed request
Incorrect credentials
Correct credentials but you don't have access to the requested resource
Correct credentials but you don't have access to the requested resource
Something went wrong on our end, try again with exponential back-off
{- "app_message": {
- "card_message": {
- "choices": [
- {
- "call_message": {
- "phone_number": "+15551231234",
- "title": "Message text"
}, - "postback_data": null
}
], - "description": "string",
- "height": "UNSPECIFIED_HEIGHT",
- "media_message": {
- "url": "string"
}, - "title": "string"
}, - "explicit_channel_message": { },
- "explicit_channel_omni_message": {
- "property1": {
- "text_message": {
- "text": "string"
}
}, - "property2": {
- "text_message": {
- "text": "string"
}
}
}, - "channel_specific_message": {
- "property1": {
- "message_type": "FLOWS",
- "message": {
- "header": {
- "type": "text",
- "text": "string"
}, - "body": {
- "text": "string"
}, - "footer": {
- "text": "string"
}, - "flow_id": "string",
- "flow_token": "string",
- "flow_mode": "draft",
- "flow_cta": "string",
- "flow_action": "navigate",
- "flow_action_payload": {
- "screen": "string",
- "data": { }
}
}
}, - "property2": {
- "message_type": "FLOWS",
- "message": {
- "header": {
- "type": "text",
- "text": "string"
}, - "body": {
- "text": "string"
}, - "footer": {
- "text": "string"
}, - "flow_id": "string",
- "flow_token": "string",
- "flow_mode": "draft",
- "flow_cta": "string",
- "flow_action": "navigate",
- "flow_action_payload": {
- "screen": "string",
- "data": { }
}
}
}
}, - "agent": {
- "display_name": "string",
- "type": "UNKNOWN_AGENT_TYPE",
- "picture_url": "string"
}
}, - "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 specific message by its ID.
Note: Removing all messages of a conversation will not automatically delete the conversation.
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. |
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.
|
A successful response.
Malformed request
Incorrect credentials
Correct credentials but you don't have access to the requested resource
Correct credentials but you don't have access to the requested resource
Something went wrong on our end, try again with exponential back-off
{- "code": 400,
- "message": "Malformed request",
- "status": "INVALID_REQUEST",
- "details": [ ]
}
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.
project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
conversation_id | string Resource name (ID) of the conversation. | ||||||
contact_id | string Resource name (ID) of the contact. Note that either | ||||||
app_id | string Id of the app. | ||||||
channel_identity | string Channel identity of the contact. | ||||||
start_time | string <date-time> Filter messages with | ||||||
end_time | string <date-time> Filter messages with | ||||||
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"
| ||||||
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.
| ||||||
only_recipient_originated | boolean If true, fetch only recipient originated messages. Available only when | ||||||
channel | string (Channel Identifier) Only fetch messages from the Example: channel=WHATSAPP |
A successful response.
Malformed request
Incorrect credentials
Correct credentials but you don't have access to the requested resource
Correct credentials but you don't have access to the requested resource
Something went wrong on our end, try again with exponential back-off
{- "messages": [
- {
- "app_message": {
- "card_message": {
- "choices": [
- {
- "call_message": {
- "phone_number": null,
- "title": null
}, - "postback_data": null
}
], - "description": "string",
- "height": "UNSPECIFIED_HEIGHT",
- "media_message": {
- "url": "string"
}, - "title": "string"
}, - "explicit_channel_message": { },
- "explicit_channel_omni_message": {
- "property1": {
- "text_message": {
- "text": "string"
}
}, - "property2": {
- "text_message": {
- "text": "string"
}
}
}, - "channel_specific_message": {
- "property1": {
- "message_type": "FLOWS",
- "message": {
- "header": {
- "type": null,
- "text": null
}, - "body": {
- "text": null
}, - "footer": {
- "text": null
}, - "flow_id": "string",
- "flow_token": "string",
- "flow_mode": "draft",
- "flow_cta": "string",
- "flow_action": "navigate",
- "flow_action_payload": {
- "screen": null,
- "data": { }
}
}
}, - "property2": {
- "message_type": "FLOWS",
- "message": {
- "header": {
- "type": null,
- "text": null
}, - "body": {
- "text": null
}, - "footer": {
- "text": null
}, - "flow_id": "string",
- "flow_token": "string",
- "flow_mode": "draft",
- "flow_cta": "string",
- "flow_action": "navigate",
- "flow_action_payload": {
- "screen": null,
- "data": { }
}
}
}
}, - "agent": {
- "display_name": "string",
- "type": "UNKNOWN_AGENT_TYPE",
- "picture_url": "string"
}
}, - "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"
}
], - "next_page_token": "string"
}