Skip to content
Conversation API/
/Contacts

Conversation API - Batch API | Sinch (1.0)

Perform batch operations on select Conversation API resources.

Download OpenAPI description
batch.json
batch.yaml
Overview
support at sinch
support@sinch.com
License
MIT
Languages
Servers
The {region} variable must be set to either us, eu, or br
https://{region}.conversationbatch.api.sinch.com

Messages

Send a message to one or many recipients. This API supports the same channels as Conversation API.

Operations

Contacts

Create or delete contacts in batches.

Operations

Create contacts

Request

Creates a batch of up to 1000 contacts as specified by the list of contacts.

The contacts are created asynchronously. A CONTACT_CREATE event will be generated for every successfully created contact.

Security
BearerAuth
Path
project_idstringrequired

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

Bodyapplication/jsonrequired
contactsArray of objects(Contact creation request)[ 1 .. 1000 ] itemsrequired

List of contacts to be created in Conversation API.

contacts[].​channel_identitiesArray of objects(Channel Identity)required

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

contacts[].​channel_identities[].​identitystringrequired

The channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business.

contacts[].​channel_identities[].​channelstring(ConversationChannel)required

The identifier of the channel you want to include. Must be one of the enum values.

Enum ValueDescription
WHATSAPP

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.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

KAKAOTALKCHAT

The KakaoTalk chat channel (used primarily in ConsultationTalk).

contacts[].​channel_identities[].​app_idstring

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.

contacts[].​languagestring(ContactLanguage)required
Enum ValueDescription
AF

Afrikaans

SQ

Albanian

AR

Arabic

AZ

Azerbaijani

BN

Bengali

BG

Bulgarian

CA

Catalan

ZH

Chinese

ZH_CN

Chinese (CHN)

ZH_HK

Chinese (HKG)

contacts[].​channel_priorityArray of strings(Channel Identifier)

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

Items Enum ValueDescription
WHATSAPP

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.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

KAKAOTALKCHAT

The KakaoTalk chat channel (used primarily in ConsultationTalk).

Example: ["WHATSAPP"]
contacts[].​display_namestring

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

contacts[].​emailstring

Email of the contact.

contacts[].​external_idstring

Contact identifier in an external system.

contacts[].​metadatastring

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

curl -i -X POST \
  'https://us.conversationbatch.api.sinch.com/v1/projects/{project_id}/contacts' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      {
        "channel_identities": [
          {
            "channel": "WHATSAPP",
            "identity": "{{PHONE_NUMBER_1}}"
          }
        ],
        "language": "EN_US"
      },
      {
        "channel_identities": [
          {
            "channel": "RCS",
            "identity": "{{PHONE_NUMBER_2}}"
          }
        ],
        "language": "EN_US"
      },
      {
        "channel_identities": [
          {
            "channel": "RCS",
            "identity": "{{PHONE_NUMBER_3}}"
          }
        ],
        "language": "EN_US"
      }
    ]
  }'

Responses

OK

Response
No content

Delete contacts

Request

Deletes a batch of up to 1000 contacts as specified by the list of contact IDs.

The contacts are deleted asynchronously. A CONTACT_DELETE event will be generated for every successfully deleted contact.

Security
BearerAuth
Path
project_idstringrequired

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

Bodyapplication/jsonrequired
contact_idsArray of strings[ 1 .. 1000 ] itemsrequired

List of IDs for contacts to be deleted in Conversation API.

curl -i -X DELETE \
  'https://us.conversationbatch.api.sinch.com/v1/projects/{project_id}/contacts' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact_ids": [
      "{{CONTACT_1}}",
      "{{CONTACT_2}}",
      "{{CONTACT_3}}",
      "{{CONTACT_4}}",
      "{{CONTACT_5}}"
    ]
  }'

Responses

OK

Response
No content

Consents

Manage Conversation API consents in batches.

Operations