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).
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
A successful response.
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "contacts": [
- {
- "channel_identities": [
- {
- "app_id": "string",
- "channel": "WHATSAPP",
- "identity": "string"
}
], - "channel_priority": [
- "WHATSAPP"
], - "display_name": "string",
- "email": "string",
- "external_id": "string",
- "id": "{CONTACT_ID}",
- "language": "AF",
- "metadata": "string"
}
], - "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.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
The contact to create.
A successful response.
Array of objects (Channel Identity) List of channel identities. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| channel_priority | Array of strings (Channel Identifier) List of channels defining the channel priority. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display_name | string The display name. A default 'Unknown' will be assigned if left empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string Email of the contact. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| external_id | string Contact identifier in an external system. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The ID of the contact. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| language | string (ContactLanguage)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadata | string Metadata associated with the contact. Up to 1024 characters long. |
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "channel_identities": [
- {
- "channel": "WHATSAPP",
- "identity": "{{WHATSAPP_PHONE_NUMBER}}"
}
], - "language": "EN_US",
- "display_name": "New Contact",
- "email": "new.contact@email.com"
}{- "channel_identities": [
- {
- "app_id": "string",
- "channel": "WHATSAPP",
- "identity": "string"
}
], - "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.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
| contact_id required | string The unique ID of the contact. |
A successful response.
Array of objects (Channel Identity) List of channel identities. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| channel_priority | Array of strings (Channel Identifier) List of channels defining the channel priority. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display_name | string The display name. A default 'Unknown' will be assigned if left empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string Email of the contact. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| external_id | string Contact identifier in an external system. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The ID of the contact. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| language | string (ContactLanguage)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadata | string Metadata associated with the contact. Up to 1024 characters long. |
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "channel_identities": [
- {
- "app_id": "string",
- "channel": "WHATSAPP",
- "identity": "string"
}
], - "channel_priority": [
- "WHATSAPP"
], - "display_name": "string",
- "email": "string",
- "external_id": "string",
- "id": "{CONTACT_ID}",
- "language": "AF",
- "metadata": "string"
}Delete a contact as specified by the contact ID.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
| contact_id required | string The unique ID of the contact. |
A successful response.
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "code": 400,
- "message": "Malformed request",
- "status": "INVALID_REQUEST",
- "details": [ ]
}Updates a contact as specified by the contact ID.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
| contact_id required | string The unique ID of the contact. |
The contact to be updated
Array of objects (Channel Identity) List of channel identities. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| channel_priority | Array of strings (Channel Identifier) List of channels defining the channel priority. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display_name | string The display name. A default 'Unknown' will be assigned if left empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string Email of the contact. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| external_id | string Contact identifier in an external system. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The ID of the contact. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| language | string (ContactLanguage)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadata | string Metadata associated with the contact. Up to 1024 characters long. |
A successful response.
Array of objects (Channel Identity) List of channel identities. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| channel_priority | Array of strings (Channel Identifier) List of channels defining the channel priority. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display_name | string The display name. A default 'Unknown' will be assigned if left empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string Email of the contact. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| external_id | string Contact identifier in an external system. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The ID of the contact. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| language | string (ContactLanguage)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadata | string Metadata associated with the contact. Up to 1024 characters long. |
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "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"
}{- "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"
], - "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.
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
| destination_id required | string The unique ID of the contact that should be kept when merging two contacts. |
The contact to be removed.
A successful response.
Array of objects (Channel Identity) List of channel identities. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| channel_priority | Array of strings (Channel Identifier) List of channels defining the channel priority. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display_name | string The display name. A default 'Unknown' will be assigned if left empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string Email of the contact. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| external_id | string Contact identifier in an external system. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The ID of the contact. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| language | string (ContactLanguage)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadata | string Metadata associated with the contact. Up to 1024 characters long. |
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "source_id": "string"
}{- "id": "ID_of_target_contact",
- "channel_identities": [
- {
- "channel": "TELEGRAM",
- "identity": "{TELEGRAM_ID}",
- "app_id": ""
}, - {
- "channel": "WHATSAPP",
- "identity": "{WHATSAPP_ID}",
- "app_id": ""
}
], - "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).
| project_id required | string The unique ID of the project. You can find this on the Sinch Dashboard. |
Malformed request. See common error responses for more information.
Incorrect credentials. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Correct credentials but you don't have access to the requested resource. See common error responses for more information.
Something went wrong on our end, try again with exponential back-off. See common error responses for more information.
{- "app_id": "{APP_ID}",
- "recipient": { },
- "channel": "MESSENGER"
}{- "profile_name": "John Doe"
}