Contacts

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.

Operations

List Contacts

Request

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

Security

Basic or oAuth2

Path

project_idstringrequired

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

Query

page_sizeinteger, (int32)

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

page_tokenstring

Optional. Next page token previously returned if any.

external_idstring

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

channelstring(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 Value	Description
SMS	The SMS channel.
RCS	The RCS channel.
WHATSAPP	The WhatsApp channel.
MMS	The MMS channel.
KAKAOTALK	The KakaoTalk channel.
KAKAOTALKCHAT	The KakaoTalk chat channel (used primarily in ConsultationTalk).
VIBERBM	The Viber Business Messages channel.
LINE	The LINE channel.
INSTAGRAM	The Instagram channel.
MESSENGER	The Facebook Messenger channel.
WECHAT	The WeChat channel.
TELEGRAM	The Telegram channel.
APPLEBC	The Apple Messages for Business channel.

Example:channel=WHATSAPP

identitystring

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.

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'

Responses

A successful response.

Bodyapplication/json

contactsArray of objects(Contact)

List of contacts belonging to the specified project.

next_page_tokenstring

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

Response

{
  "contacts": [
    { … }
  ],
  "next_page_token": "string"
}

We'd love to hear from you!