Contact

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
Email Optional Email of the contact
External id Optional identifier of the contact in external systems
Metadata Optional metadata associated with the contact.

List Contacts

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

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
page_size
integer <int32>

Optional. The maximum number of contacts to fetch. The default is 10 and the maximum is 20.

page_token
string

Optional. Next page token previously returned if any.

external_id
string

Optional. Contact identifier in an external system. If used, channel and identity query parameters can't be used.

channel
string (Channel Identifier)

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: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT" "APPLEBC"
Example: channel=WHATSAPP
identity
string

Optional. If set, the channel parameter must be set and external_id can't be used. Used in conjunction with channel to uniquely identify the specified channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business.

Responses
200

A successful response.

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

List of contacts belonging to the specified project.

next_page_token
string

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

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

Create a Contact

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.

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 contact to create.

required
Array of objects (Channel Identity)

List of channel identities. Array must contain at least one item.

language
required
string (ContactLanguage)
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)

ZH_TW

Chinese (TAI)

HR

Croatian

CS

Czech

DA

Danish

NL

Dutch

EN

English

EN_GB

English (UK)

EN_US

English (US)

ET

Estonian

FIL

Filipino

FI

Finnish

FR

French

DE

German

EL

Greek

GU

Gujarati

HA

Hausa

HE

Hebrew

HI

Hindi

HU

Hungarian

ID

Indonesian

GA

Irish

IT

Italian

JA

Japanese

KN

Kannada

KK

Kazakh

KO

Korean

LO

Lao

LV

Latvian

LT

Lithuanian

MK

Macedonian

MS

Malay

ML

Malayalam

MR

Marathi

NB

Norwegian

FA

Persian

PL

Polish

PT

Portuguese

PT_BR

Portuguese (BR)

PT_PT

Portuguese (PT)

PA

Punjabi

RO

Romanian

RU

Russian

SR

Serbian

SK

Slovak

SL

Slovenian

ES

Spanish

ES_AR

Spanish (ARG)

ES_ES

Spanish (SPA)

ES_MX

Spanish (MEX)

SW

Swahili

SV

Swedish

TA

Tamil

TE

Telugu

TH

Thai

TR

Turkish

UK

Ukrainian

UR

Urdu

UZ

Uzbek

VI

Vietnamese

ZU

Zulu

channel_priority
Array of strings (Channel Identifier)

List of channels defining the channel priority. The channel at the top of the list is tried first.

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

The display name. A default 'Unknown' will be assigned if left empty.

email
string

Email of the contact.

external_id
string

Contact identifier in an external system.

metadata
string

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

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Identity)

List of channel identities.

channel_priority
Array of strings (Channel Identifier)

List of channels defining the channel priority.

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

The display name. A default 'Unknown' will be assigned if left empty.

email
string

Email of the contact.

external_id
string

Contact identifier in an external system.

id
string

The ID of the contact.

language
string (ContactLanguage)
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)

ZH_TW

Chinese (TAI)

HR

Croatian

CS

Czech

DA

Danish

NL

Dutch

EN

English

EN_GB

English (UK)

EN_US

English (US)

ET

Estonian

FIL

Filipino

FI

Finnish

FR

French

DE

German

EL

Greek

GU

Gujarati

HA

Hausa

HE

Hebrew

HI

Hindi

HU

Hungarian

ID

Indonesian

GA

Irish

IT

Italian

JA

Japanese

KN

Kannada

KK

Kazakh

KO

Korean

LO

Lao

LV

Latvian

LT

Lithuanian

MK

Macedonian

MS

Malay

ML

Malayalam

MR

Marathi

NB

Norwegian

FA

Persian

PL

Polish

PT

Portuguese

PT_BR

Portuguese (BR)

PT_PT

Portuguese (PT)

PA

Punjabi

RO

Romanian

RU

Russian

SR

Serbian

SK

Slovak

SL

Slovenian

ES

Spanish

ES_AR

Spanish (ARG)

ES_ES

Spanish (SPA)

ES_MX

Spanish (MEX)

SW

Swahili

SV

Swedish

TA

Tamil

TE

Telugu

TH

Thai

TR

Turkish

UK

Ukrainian

UR

Urdu

UZ

Uzbek

VI

Vietnamese

ZU

Zulu

metadata
string

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

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}/contacts
Request samples
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "language": "EN_US",
  • "display_name": "New Contact",
  • "email": "new.contact@email.com"
}
Response samples
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "channel_priority": [
    • "WHATSAPP"
    ],
  • "display_name": "string",
  • "email": "string",
  • "external_id": "string",
  • "id": "{CONTACT_ID}",
  • "language": "AF",
  • "metadata": "string"
}

Get a Contact

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.

SecurityBasic or oAuth2
Request
path Parameters
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.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Identity)

List of channel identities.

channel_priority
Array of strings (Channel Identifier)

List of channels defining the channel priority.

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

The display name. A default 'Unknown' will be assigned if left empty.

email
string

Email of the contact.

external_id
string

Contact identifier in an external system.

id
string

The ID of the contact.

language
string (ContactLanguage)
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)

ZH_TW

Chinese (TAI)

HR

Croatian

CS

Czech

DA

Danish

NL

Dutch

EN

English

EN_GB

English (UK)

EN_US

English (US)

ET

Estonian

FIL

Filipino

FI

Finnish

FR

French

DE

German

EL

Greek

GU

Gujarati

HA

Hausa

HE

Hebrew

HI

Hindi

HU

Hungarian

ID

Indonesian

GA

Irish

IT

Italian

JA

Japanese

KN

Kannada

KK

Kazakh

KO

Korean

LO

Lao

LV

Latvian

LT

Lithuanian

MK

Macedonian

MS

Malay

ML

Malayalam

MR

Marathi

NB

Norwegian

FA

Persian

PL

Polish

PT

Portuguese

PT_BR

Portuguese (BR)

PT_PT

Portuguese (PT)

PA

Punjabi

RO

Romanian

RU

Russian

SR

Serbian

SK

Slovak

SL

Slovenian

ES

Spanish

ES_AR

Spanish (ARG)

ES_ES

Spanish (SPA)

ES_MX

Spanish (MEX)

SW

Swahili

SV

Swedish

TA

Tamil

TE

Telugu

TH

Thai

TR

Turkish

UK

Ukrainian

UR

Urdu

UZ

Uzbek

VI

Vietnamese

ZU

Zulu

metadata
string

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

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}/contacts/{contact_id}
Request samples
Response samples
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "channel_priority": [
    • "WHATSAPP"
    ],
  • "display_name": "string",
  • "email": "string",
  • "external_id": "string",
  • "id": "{CONTACT_ID}",
  • "language": "AF",
  • "metadata": "string"
}

Delete a Contact

Delete a contact as specified by the contact ID.

SecurityBasic or oAuth2
Request
path Parameters
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.

Responses
200

A successful response.

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

Update a Contact

Updates a contact as specified by the contact ID.

SecurityBasic or oAuth2
Request
path Parameters
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.

query Parameters
update_mask
Array of strings

The set of field mask paths.

Request Body schema: application/json
required

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.

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

The display name. A default 'Unknown' will be assigned if left empty.

email
string

Email of the contact.

external_id
string

Contact identifier in an external system.

id
string

The ID of the contact.

language
string (ContactLanguage)
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)

ZH_TW

Chinese (TAI)

HR

Croatian

CS

Czech

DA

Danish

NL

Dutch

EN

English

EN_GB

English (UK)

EN_US

English (US)

ET

Estonian

FIL

Filipino

FI

Finnish

FR

French

DE

German

EL

Greek

GU

Gujarati

HA

Hausa

HE

Hebrew

HI

Hindi

HU

Hungarian

ID

Indonesian

GA

Irish

IT

Italian

JA

Japanese

KN

Kannada

KK

Kazakh

KO

Korean

LO

Lao

LV

Latvian

LT

Lithuanian

MK

Macedonian

MS

Malay

ML

Malayalam

MR

Marathi

NB

Norwegian

FA

Persian

PL

Polish

PT

Portuguese

PT_BR

Portuguese (BR)

PT_PT

Portuguese (PT)

PA

Punjabi

RO

Romanian

RU

Russian

SR

Serbian

SK

Slovak

SL

Slovenian

ES

Spanish

ES_AR

Spanish (ARG)

ES_ES

Spanish (SPA)

ES_MX

Spanish (MEX)

SW

Swahili

SV

Swedish

TA

Tamil

TE

Telugu

TH

Thai

TR

Turkish

UK

Ukrainian

UR

Urdu

UZ

Uzbek

VI

Vietnamese

ZU

Zulu

metadata
string

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

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Identity)

List of channel identities.

channel_priority
Array of strings (Channel Identifier)

List of channels defining the channel priority.

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

The display name. A default 'Unknown' will be assigned if left empty.

email
string

Email of the contact.

external_id
string

Contact identifier in an external system.

id
string

The ID of the contact.

language
string (ContactLanguage)
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)

ZH_TW

Chinese (TAI)

HR

Croatian

CS

Czech

DA

Danish

NL

Dutch

EN

English

EN_GB

English (UK)

EN_US

English (US)

ET

Estonian

FIL

Filipino

FI

Finnish

FR

French

DE

German

EL

Greek

GU

Gujarati

HA

Hausa

HE

Hebrew

HI

Hindi

HU

Hungarian

ID

Indonesian

GA

Irish

IT

Italian

JA

Japanese

KN

Kannada

KK

Kazakh

KO

Korean

LO

Lao

LV

Latvian

LT

Lithuanian

MK

Macedonian

MS

Malay

ML

Malayalam

MR

Marathi

NB

Norwegian

FA

Persian

PL

Polish

PT

Portuguese

PT_BR

Portuguese (BR)

PT_PT

Portuguese (PT)

PA

Punjabi

RO

Romanian

RU

Russian

SR

Serbian

SK

Slovak

SL

Slovenian

ES

Spanish

ES_AR

Spanish (ARG)

ES_ES

Spanish (SPA)

ES_MX

Spanish (MEX)

SW

Swahili

SV

Swedish

TA

Tamil

TE

Telugu

TH

Thai

TR

Turkish

UK

Ukrainian

UR

Urdu

UZ

Uzbek

VI

Vietnamese

ZU

Zulu

metadata
string

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

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}/contacts/{contact_id}
Request samples
application/json
{
  • "channel_identities": [
    • {
      },
    • {
      }
    ],
  • "channel_priority": [
    • "MESSENGER",
    • "VIBER"
    ],
  • "email": "string",
  • "language": "FR",
  • "metadata": "string"
}
Response samples
application/json
{
  • "channel_identities": [
    • {
      },
    • {
      }
    ],
  • "channel_priority": [
    • "MESSENGER",
    • "VIBER"
    ],
  • "display_name": "string",
  • "external_id": "string",
  • "email": "string",
  • "language": "EN_US",
  • "metadata": "string"
}

Merge two Contacts

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.

SecurityBasic or oAuth2
Request
path Parameters
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.

Request Body schema: application/json
required

The contact to be removed.

source_id
required
string

Required. The ID of the contact that should be removed.

strategy
string (ConversationMergeStrategy)
Default: "MERGE"
Value: "MERGE"
Responses
200

A successful response.

Response Schema: application/json
Array of objects (Channel Identity)

List of channel identities.

channel_priority
Array of strings (Channel Identifier)

List of channels defining the channel priority.

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

The display name. A default 'Unknown' will be assigned if left empty.

email
string

Email of the contact.

external_id
string

Contact identifier in an external system.

id
string

The ID of the contact.

language
string (ContactLanguage)
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)

ZH_TW

Chinese (TAI)

HR

Croatian

CS

Czech

DA

Danish

NL

Dutch

EN

English

EN_GB

English (UK)

EN_US

English (US)

ET

Estonian

FIL

Filipino

FI

Finnish

FR

French

DE

German

EL

Greek

GU

Gujarati

HA

Hausa

HE

Hebrew

HI

Hindi

HU

Hungarian

ID

Indonesian

GA

Irish

IT

Italian

JA

Japanese

KN

Kannada

KK

Kazakh

KO

Korean

LO

Lao

LV

Latvian

LT

Lithuanian

MK

Macedonian

MS

Malay

ML

Malayalam

MR

Marathi

NB

Norwegian

FA

Persian

PL

Polish

PT

Portuguese

PT_BR

Portuguese (BR)

PT_PT

Portuguese (PT)

PA

Punjabi

RO

Romanian

RU

Russian

SR

Serbian

SK

Slovak

SL

Slovenian

ES

Spanish

ES_AR

Spanish (ARG)

ES_ES

Spanish (SPA)

ES_MX

Spanish (MEX)

SW

Swahili

SV

Swedish

TA

Tamil

TE

Telugu

TH

Thai

TR

Turkish

UK

Ukrainian

UR

Urdu

UZ

Uzbek

VI

Vietnamese

ZU

Zulu

metadata
string

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

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}/contacts/{destination_id}:merge
Request samples
application/json
{
  • "source_id": "string"
}
Response samples
application/json
{
  • "id": "ID_of_target_contact",
  • "channel_identities": [
    • {
      },
    • {
      }
    ],
  • "channel_priority": [
    • "TELEGRAM",
    • "WHATSAPP"
    ],
  • "display_name": "{CONTACT_DISPLAY_NAME}",
  • "email": "",
  • "external_id": "",
  • "metadata": "",
  • "language": "ZU"
}

Get Channel Profile

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

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

The ID of the app.

required
Contact ID (object) or Channel Identities (object) (Recipient)

Identifies the recipient.

channel
required
string (Channel Identifier)

The channel. Must be one of the supported channels for this operation.

Enum: "MESSENGER" "INSTAGRAM" "VIBER" "LINE"
Responses
200

A successful response.

Response Schema: application/json
profile_name
string

The profile name.

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}/contacts:getChannelProfile
Request samples
application/json
{
  • "app_id": "{APP_ID}",
  • "recipient": { },
  • "channel": "MESSENGER"
}
Response samples
application/json
{
  • "profile_name": "John Doe"
}