Conversation

Endpoints for working with the conversation log.

List conversations

This operation lists all conversations that are associated with an app and/or a contact.

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
only_active
required
boolean

Required. True if only active conversations should be listed.

app_id
string

The ID of the app involved in the conversations. Note that either app_id or contact_id is required in order for the operation to function correctly.

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.

page_size
integer <int32>

The maximum number of conversations to fetch. Defaults to 10 and the maximum is 20.

page_token
string

Next page token previously returned if any.

active_channel
string (Channel Identifier)

Only fetch conversations from the active_channel

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
Example: active_channel=WHATSAPP
Responses
200

A successful response.

Response Schema: application/json
Array of objects (Conversation)

List of conversations matching the search query.

next_page_token
string

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

total_size
integer <int32>
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}/conversations
Request samples
Response samples
application/json
{
  • "conversations": [
    • {
      }
    ],
  • "next_page_token": "string",
  • "total_size": 0
}

Create a conversation

Creates a new empty conversation. It is generally not needed to create a conversation explicitly since sending or receiving a message automatically creates a new conversation if it does not already exist between the given app and contact. Creating empty conversation is useful if the metadata of the conversation should be populated when the first message in the conversation is a contact message or the first message in the conversation comes out-of-band and needs to be injected with InjectMessage endpoint.

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

The conversation to create. ID will be generated for the conversation and any ID in the given conversation will be ignored.

app_id
required
string

The ID of the participating app.

contact_id
required
string

The ID of the participating contact.

active
boolean

Flag for whether this conversation is active.

active_channel
string (Channel Identifier)

The identifier of the channel you want to include. Must be one of the enum values.

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
id
string

The ID of the conversation.

metadata
string

Arbitrary data set by the Conversation API clients. Up to 1024 characters long.

metadata_json
object

Arbitrary data set by the Conversation API clients and/or provided in the conversation_metadata field of a SendMessageRequest. A valid JSON object.

Responses
200

A successful response.

Response Schema: application/json
active
boolean

Flag for whether this conversation is active.

active_channel
string (Channel Identifier)

The identifier of the channel you want to include. Must be one of the enum values.

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
app_id
string

The ID of the participating app.

contact_id
string

The ID of the participating contact.

id
string

The ID of the conversation.

last_received
string <date-time>

The timestamp of the latest message in the conversation. The timestamp will be Thursday January 01, 1970 00:00:00 UTC if the conversation contains no messages.

metadata
string

Arbitrary data set by the Conversation API clients. Up to 1024 characters long. NOTE: This field has been deprecated due to changes in the system architecture or functionality. It is no longer actively maintained and may be removed in future versions. Please avoid relying on this field in new code.

metadata_json
object

Arbitrary data set by the Conversation API clients and/or provided in the conversation_metadata field of a SendMessageRequest. A valid JSON object.

correlation_id
string

Arbitrary correlation ID related to the MT message set by the Conversation API user.

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}/conversations
Request samples
application/json
{
  • "active": true,
  • "active_channel": "WHATSAPP",
  • "app_id": "{APP_ID}",
  • "contact_id": "{CONTACT_ID}",
  • "id": "string",
  • "metadata": "string",
  • "metadata_json": { }
}
Response samples
application/json
{
  • "active": true,
  • "active_channel": "WHATSAPP",
  • "app_id": "string",
  • "contact_id": "string",
  • "id": "string",
  • "last_received": "2019-08-24T14:15:22Z",
  • "metadata": "string",
  • "metadata_json": { },
  • "correlation_id": "string"
}

Get a conversation

Retrieves a conversation by id. A conversation has two participating entities, an app and a contact.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

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

conversation_id
required
string

The unique ID of the conversation. This is generated by the system.

Responses
200

A successful response.

Response Schema: application/json
active
boolean

Flag for whether this conversation is active.

active_channel
string (Channel Identifier)

The identifier of the channel you want to include. Must be one of the enum values.

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
app_id
string

The ID of the participating app.

contact_id
string

The ID of the participating contact.

id
string

The ID of the conversation.

last_received
string <date-time>

The timestamp of the latest message in the conversation. The timestamp will be Thursday January 01, 1970 00:00:00 UTC if the conversation contains no messages.

metadata
string

Arbitrary data set by the Conversation API clients. Up to 1024 characters long. NOTE: This field has been deprecated due to changes in the system architecture or functionality. It is no longer actively maintained and may be removed in future versions. Please avoid relying on this field in new code.

metadata_json
object

Arbitrary data set by the Conversation API clients and/or provided in the conversation_metadata field of a SendMessageRequest. A valid JSON object.

correlation_id
string

Arbitrary correlation ID related to the MT message set by the Conversation API user.

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}/conversations/{conversation_id}
Request samples
Response samples
application/json
{
  • "active": true,
  • "active_channel": "WHATSAPP",
  • "app_id": "string",
  • "contact_id": "string",
  • "id": "string",
  • "last_received": "2019-08-24T14:15:22Z",
  • "metadata": "string",
  • "metadata_json": { },
  • "correlation_id": "string"
}

Delete a conversation

Deletes a conversation together with all the messages sent as part of 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.

conversation_id
required
string

The unique ID of the conversation. This is generated by the system.

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}/conversations/{conversation_id}
Request samples
Response samples
application/json
{
  • "code": 400,
  • "message": "Malformed request",
  • "status": "INVALID_REQUEST",
  • "details": [ ]
}

Update a conversation

This operation updates a conversation which can, for instance, be used to update the metadata associated with a 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.

conversation_id
required
string

The unique ID of the conversation. This is generated by the system.

query Parameters
update_mask
Array of strings

The set of field mask paths.

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.

Request Body schema: application/json
required

The updated conversation.

active
boolean

Flag for whether this conversation is active.

active_channel
string (Channel Identifier)

The identifier of the channel you want to include. Must be one of the enum values.

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
app_id
string

The ID of the participating app.

contact_id
string

The ID of the participating contact.

id
string

The ID of the conversation.

metadata
string

Arbitrary data set by the Conversation API clients. Up to 1024 characters long. NOTE: This field has been deprecated due to changes in the system architecture or functionality. It is no longer actively maintained and may be removed in future versions. Please avoid relying on this field in new code.

metadata_json
object

Arbitrary data set by the Conversation API clients and/or provided in the conversation_metadata field of a SendMessageRequest. A valid JSON object.

correlation_id
string

Arbitrary correlation ID related to the MT message set by the Conversation API user.

Responses
200

A successful response.

Response Schema: application/json
active
boolean

Flag for whether this conversation is active.

active_channel
string (Channel Identifier)

The identifier of the channel you want to include. Must be one of the enum values.

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
app_id
string

The ID of the participating app.

contact_id
string

The ID of the participating contact.

id
string

The ID of the conversation.

last_received
string <date-time>

The timestamp of the latest message in the conversation. The timestamp will be Thursday January 01, 1970 00:00:00 UTC if the conversation contains no messages.

metadata
string

Arbitrary data set by the Conversation API clients. Up to 1024 characters long. NOTE: This field has been deprecated due to changes in the system architecture or functionality. It is no longer actively maintained and may be removed in future versions. Please avoid relying on this field in new code.

metadata_json
object

Arbitrary data set by the Conversation API clients and/or provided in the conversation_metadata field of a SendMessageRequest. A valid JSON object.

correlation_id
string

Arbitrary correlation ID related to the MT message set by the Conversation API user.

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}/conversations/{conversation_id}
Request samples
application/json
{
  • "app_id": "string ",
  • "metadata": "string",
  • "active_channel": "WHATSAPP",
  • "active": true
}
Response samples
application/json
{
  • "active": true,
  • "active_channel": "WHATSAPP",
  • "app_id": "string",
  • "contact_id": "string",
  • "id": "string",
  • "last_received": "2019-08-24T14:15:22Z",
  • "metadata": "string",
  • "metadata_json": { },
  • "correlation_id": "string"
}

List recent conversations

This operation lists conversations and their most recent message, ordered by when the most recent message was sent for that 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.

query Parameters
app_id
required
string

The application ID

only_active
boolean

True if only active conversations should be listed. Default is false.

page_size
integer <int32>

The maximum number of conversations to fetch. Defaults to 10 and the maximum value is 50.

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.

order
string

Whether to sort conversations by newest message first or oldest. Default is DESC (newest first)

Enum: "ASC" "DESC"
Responses
200

A successful response.

Response Schema: application/json
Array of objects (ConversationRecentMessage)

List of recent conversations

next_page_token
string

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

total_size
integer <int32>
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}/conversations:recent
Request samples
Response samples
application/json
{
  • "conversations": [
    • {
      }
    ],
  • "next_page_token": "string",
  • "total_size": 0
}

Inject an event

This operation injects a conversation event in to a specific conversation. It only supports injecting App events in CONVERSATION mode.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

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

conversation_id
required
string

The unique ID of the conversation. This is generated by the system.

Request Body schema: application/json
required

Inject event request

required
App Event Type (object)

The content of the events.

accept_time
required
string <date-time>

The processed time of the message in UTC timezone. Must be less than current_time and greater than (current_time - 30 days).

conversation_id
string

Optional. The ID of the event's conversation. Will not be present for apps in Dispatch Mode.

contact_id
string

Optional. The ID of the contact. Will not be present for apps in Dispatch Mode.

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.

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.

Responses
200

A succcessful response.

Response Schema: application/json
event_id
string

Event id.

accepted_time
string <date-time>
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}/conversations/{conversation_id}:inject-event
Request samples
application/json
{
  • "id": "string",
  • "direction": "TO_APP",
  • "channel_identity": {
    • "channel": "MESSENGER",
    • "identity": "{{FACEBOOK_USER_NAME}}",
    • "app_id": "{{APP_ID}}"
    },
  • "app_event": {
    • "composing_event": { }
    },
  • "accept_time": "YYYY-MM-DDTHH:MM:SS"
}
Response samples
application/json
{
  • "event_id": "string",
  • "accepted_time": "YYYY-MM-DDTHH:MM:SS"
}

Stop conversation

This operation stops the referenced conversation, if the conversation is still active. A new conversation will be created if a new message is exchanged between the app or contact that was part of the stopped 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.

conversation_id
required
string

The unique ID of the conversation. This is generated by the system.

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.

post/v1/projects/{project_id}/conversations/{conversation_id}:stop
Request samples
Response samples
application/json
{
  • "code": 400,
  • "message": "Malformed request",
  • "status": "INVALID_REQUEST",
  • "details": [ ]
}

Inject a message

This operation injects a conversation message in to a specific 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.conversation_id
required
string

The ID of the conversation.

Request Body schema: application/json
required

Message to be injected.

One of:

A message on a particular channel.

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

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

The ID of the contact registered in the conversation provided.

direction
required
string (ConversationDirection)
Default: "UNDEFINED_DIRECTION"
Enum: "UNDEFINED_DIRECTION" "TO_APP" "TO_CONTACT"
accept_time
required
string <date-time>

The processed time of the message in UTC timezone. Must be less than current_time and greater than (current_time - 30 days)

conversation_id
string

The ID of the conversation.

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.

metadata
string

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

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.

post/v1/projects/{project_id}/conversations/{message.conversation_id}:inject-message
Request samples
application/json
{
  • "direction": "TO_CONTACT",
  • "channel_identity": {
    • "channel": "{{CHANNEL_NAME}}",
    • "identity": "{{CHANNEL_IDENTITY}}"
    },
  • "app_message": {
    • "text_message": {
      }
    },
  • "contact_id": "string",
  • "accept_time": "YYYY-MM-DDTHH:MM:SS"
}
Response samples
application/json
{
  • "code": 400,
  • "message": "Malformed request",
  • "status": "INVALID_REQUEST",
  • "details": [ ]
}