Send and receive messages globally over SMS, RCS, WhatsApp, Viber Business, Facebook messenger and other popular channels using the Sinch Conversation API.
The Conversation API endpoint uses built-in transcoding to give you the power of conversation across all supported channels and, if required, full control over channel specific features.
https://{region}.conversation.api.sinch.com/
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.
Apps are created and configured through the Sinch Dashboard, are tied to the API user and come with a set of channel credentials for each underlying connected channel. The app has a list of conversations between itself and different contacts which share the same project.
Webhooks, which the app is attached to, defines the destination for various events coming from the Conversation API. An app has the following configurable properties:
| Field | Description |
|---|---|
| Display name | The name visible in the Sinch Dashboard. |
| Conversation metadata report | Specifies the amount of conversationmetadata that's returned as part of each callback. |
| Retention Policy | The retention policy specifies how long messages, sent to or from an app, are stored by the Conversation API. |
A contact is a collection that groups together underlying connected channel recipient identities. It's tied to a specific project and is therefore considered public to all apps sharing the same project. Most contact creation and maintenance is handled by the Conversation API's automatic contact management processes. However, you can also use API calls to manually manage your contacts.
A contact has the following configurable properties:
| Field | Description |
|---|---|
| Channel identities | List of channel identities specifying how the contact is identified on underlying channels |
| Channel priority | Specifies the channel priority order used when sending messages to this contact. This can be overridden by message specific channel priority order. |
| Display name | Optional display name used in chat windows and other UIs |
| Optional Email of the contact | |
| External id | Optional identifier of the contact in external systems |
| Metadata | Optional metadata associated with the contact. |
List all contacts in the project. Note that, if a WhatsApp contact is returned, the display_name field of that contact may be populated with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).
The unique ID of the project. You can find this on the Sinch Dashboard.
Optional. The maximum number of contacts to fetch. The default is 10 and the maximum is 20.
Optional. Contact identifier in an external system. If used, channel and identity query parameters can't be used.
Optional. Specifies a channel, and must be set to one of the enum values. If set, the identity parameter must be set and external_id can't be used. Used in conjunction with identity to uniquely identify the specified channel identity.
| Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts
curl -i -X GET \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts?page_size=0&page_token=string&external_id=string&channel=WHATSAPP&identity=string'{ "contacts": [ { … } ], "next_page_token": "string" }
Most Conversation API contacts are created automatically when a message is sent to a new recipient. You can also create a new contact manually using this API call.
The unique ID of the project. You can find this on the Sinch Dashboard.
The contact to create.
List of channel identities. Array must contain at least one item.
Required if using a channel that uses app-scoped channel identities. Currently, FB Messenger, Instagram, LINE, and WeChat use app-scoped channel identities, which means contacts will have different channel identities on different Conversation API apps. These can be thought of as virtual identities that are app-specific and, therefore, the app_id must be included in the API call.
The identifier of the channel you want to include. Must be one of the enum values.
| Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
List of channels defining the channel priority. The channel at the top of the list is tried first.
| Items Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
| Enum Value | Description |
|---|---|
| AF | Afrikaans |
| SQ | Albanian |
| AR | Arabic |
| AZ | Azerbaijani |
| BN | Bengali |
| BG | Bulgarian |
| CA | Catalan |
| ZH | Chinese |
| ZH_CN | Chinese (CHN) |
| ZH_HK | Chinese (HKG) |
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts
curl -i -X POST \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts' \
-H 'Content-Type: application/json' \
-d '{
"channel_identities": [
{
"channel": "WHATSAPP",
"identity": "{{WHATSAPP_PHONE_NUMBER}}"
}
],
"language": "EN_US",
"display_name": "New Contact",
"email": "new.contact@email.com"
}'A successful response.
List of channels defining the channel priority.
| Items Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
| Enum Value | Description |
|---|---|
| AF | Afrikaans |
| SQ | Albanian |
| AR | Arabic |
| AZ | Azerbaijani |
| BN | Bengali |
| BG | Bulgarian |
| CA | Catalan |
| ZH | Chinese |
| ZH_CN | Chinese (CHN) |
| ZH_HK | Chinese (HKG) |
{ "channel_identities": [ { … } ], "channel_priority": [ "WHATSAPP" ], "display_name": "string", "email": "string", "external_id": "string", "id": "{CONTACT_ID}", "language": "AF", "metadata": "string" }
Returns a specific contact as specified by the contact ID. Note the following:
If a WhatsApp contact is returned, the display_name field of that contact may be populated with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).
If you receive an Inbound Message callback for an MO message on the Instagram channel, the corresponding payload will not include the Instagram username. You may use the contact_id and channel_identity values included in the callback to retreive the username (detailed in the display_name field) with this Conversation API operation.
The unique ID of the project. You can find this on the Sinch Dashboard.
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{contact_id}
curl -i -X GET \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{contact_id}'A successful response.
List of channels defining the channel priority.
| Items Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
| Enum Value | Description |
|---|---|
| AF | Afrikaans |
| SQ | Albanian |
| AR | Arabic |
| AZ | Azerbaijani |
| BN | Bengali |
| BG | Bulgarian |
| CA | Catalan |
| ZH | Chinese |
| ZH_CN | Chinese (CHN) |
| ZH_HK | Chinese (HKG) |
{ "channel_identities": [ { … } ], "channel_priority": [ "WHATSAPP" ], "display_name": "string", "email": "string", "external_id": "string", "id": "{CONTACT_ID}", "language": "AF", "metadata": "string" }
The unique ID of the project. You can find this on the Sinch Dashboard.
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{contact_id}
curl -i -X DELETE \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{contact_id}'The unique ID of the project. You can find this on the Sinch Dashboard.
The contact to be updated
List of channels defining the channel priority.
| Items Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
| Enum Value | Description |
|---|---|
| AF | Afrikaans |
| SQ | Albanian |
| AR | Arabic |
| AZ | Azerbaijani |
| BN | Bengali |
| BG | Bulgarian |
| CA | Catalan |
| ZH | Chinese |
| ZH_CN | Chinese (CHN) |
| ZH_HK | Chinese (HKG) |
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{contact_id}
curl -i -X PATCH \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{contact_id}?update_mask=string' \
-H 'Content-Type: application/json' \
-d '{
"channel_identities": [
{
"channel": "MESSENGER",
"identity": "{{FACEBOOK_USER_NAME}}",
"app_id": "{{APP_ID}}"
},
{
"channel": "VIBER",
"identity": "{{PHONE_NUMBER}}",
"app_id": "{{APP_ID}}"
}
],
"channel_priority": [
"MESSENGER",
"VIBER"
],
"email": "string",
"language": "FR",
"metadata": "string"
}'A successful response.
List of channels defining the channel priority.
| Items Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
| Enum Value | Description |
|---|---|
| AF | Afrikaans |
| SQ | Albanian |
| AR | Arabic |
| AZ | Azerbaijani |
| BN | Bengali |
| BG | Bulgarian |
| CA | Catalan |
| ZH | Chinese |
| ZH_CN | Chinese (CHN) |
| ZH_HK | Chinese (HKG) |
{ "channel_identities": [ { … }, { … } ], "channel_priority": [ "MESSENGER", "VIBER" ], "display_name": "string", "external_id": "string", "email": "string", "language": "EN_US", "metadata": "string" }
The remaining contact will contain all conversations that the removed contact did. If both contacts had conversations within the same App, messages from the removed contact will be merged into corresponding active conversations in the destination contact. Channel identities will be moved from the source contact to the destination contact only for channels that weren't present there before. Moved channel identities will be placed at the bottom of the channel priority list. Optional fields from the source contact will be copied only if corresponding fields in the destination contact are empty The contact being removed cannot be referenced after this call.
The unique ID of the project. You can find this on the Sinch Dashboard.
The contact to be removed.
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{destination_id}:merge
curl -i -X POST \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts/{destination_id}:merge' \
-H 'Content-Type: application/json' \
-d '{
"source_id": "string",
"strategy": "MERGE"
}'A successful response.
List of channels defining the channel priority.
| Items Enum Value | Description |
|---|---|
The WhatsApp channel. | |
| RCS | The RCS channel. |
| SMS | The SMS channel. |
| MESSENGER | The Facebook Messenger channel. |
| VIBERBM | The Viber Business Messages channel. |
| MMS | The MMS channel. |
The Instagram channel. | |
| TELEGRAM | The Telegram channel. |
| KAKAOTALK | The KakaoTalk channel. |
| KAKAOTALKCHAT | The KakaoTalk chat channel (used primarily in ConsultationTalk). |
| Enum Value | Description |
|---|---|
| AF | Afrikaans |
| SQ | Albanian |
| AR | Arabic |
| AZ | Azerbaijani |
| BN | Bengali |
| BG | Bulgarian |
| CA | Catalan |
| ZH | Chinese |
| ZH_CN | Chinese (CHN) |
| ZH_HK | Chinese (HKG) |
{ "id": "ID_of_target_contact", "channel_identities": [ { … }, { … } ], "channel_priority": [ "TELEGRAM", "WHATSAPP" ], "display_name": "{CONTACT_DISPLAY_NAME}", "email": "", "external_id": "", "metadata": "", "language": "ZU" }
Get user profile from a specific channel. Only supported on MESSENGER, INSTAGRAM, VIBER and LINE channels. Note that, in order to retrieve a WhatsApp display name, you can use the Get a Contact or List Contacts operations, which will populate the display_name field of each returned contact with the WhatsApp display name (if the name is already stored on the server and the display_name field has not been overwritten by the user).
The unique ID of the project. You can find this on the Sinch Dashboard.
Identifies the recipient.
https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts:getChannelProfile
curl -i -X POST \
-u <username>:<password> \
'https://us.conversation.api.sinch.com/v1/projects/{project_id}/contacts:getChannelProfile' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "{APP_ID}",
"recipient": {
"contact_id": "{CONTACT_ID}"
},
"channel": "MESSENGER"
}'{ "profile_name": "John Doe" }
A capability query checks the options available for reaching the contact on the channels on which it has a channel identity.
Capability queries can only be executed for contacts that already exist in a project and app. For executing the request, either the contact ID or the channel recipient identities of the contact are required.
The request is executed asynchronously, therefore the service responds immediately. The result of the capability query is sent to the registered webhook for the CAPABILITY trigger.
Consent queries provide a way to retreive any identities stored within a given consent list. You can also retrieve audit records that provide details for a given identity's journey through consent management. Note that this feature is currently available for beta testing. To gain access to this functionality, please contact your account manager.