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

At least one of app_id or contact_id must be present.

contact_id
string

At least one of app_id or contact_id must be present.

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.

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

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}/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 (ConversationChannel) 
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"  
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 (ConversationChannel) 
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"  
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.


 
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.


 
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}/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": { }
}
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 (ConversationChannel) 
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"  
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.


 
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.


 
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}/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": { }
}
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.


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}/conversations/{conversation_id}
Request samples 
Response samples 
application/json
null
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.paths
Array of strings
The set of field mask paths.


 
metadata_update_strategy
string (MetadataUpdateStrategy) 
 Default:  "REPLACE"
Update strategy for the conversation_metadata field.


 Enum: 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 (ConversationChannel) 
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"  
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.


 
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 (ConversationChannel) 
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"  
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.


 
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.


 
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


patch/v1/projects/{project_id}/conversations/{conversation_id}
Request samples 
application/json
{
  • "metadata": "string"
}
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": { }
}
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.


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


post/v1/projects/{project_id}/conversations/{conversation_id}:stop
Request samples 
Response samples 
application/json
null
Inject messages
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
Required. The ID of the conversation.


 
Request Body schema: application/json
required
Message to be injected.


accept_time
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)


 
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 registered in the conversation provided.


 
object (ContactMessage) 
Message originating from a contact


 
direction
string (ConversationDirection) 
 Enum: "UNDEFINED_DIRECTION" "TO_APP" "TO_CONTACT"  
metadata
string
Optional. Metadata associated with the contact.
Up to 1024 characters long.


 
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


post/v1/projects/{project_id}/conversations/{message.conversation_id}:inject-message
Request samples 
application/json
{ }
Response samples 
application/json
null
SecurityPrivacyLegal & ComplianceCookie Statement
© 2023 Sinch. All rights reserved.