Getting started with a WhatsApp channel

This article details the steps required to set up a WhatsApp channel for use with the Sinch Conversation API.

Prerequisites

Before you can set up a WhatsApp channel on the Conversation API, you need to do the following:

Account Upgrade

You must ensure that you have a postpay Sinch account. If your account is not a postpay account, you will be unable to use the WhatsApp channel.

To upgrade your account to a postpay account, reach out to your account manager.

General requirements

Note

If you have already completed the Conversation API Getting started steps, you can skip this section.

Sign up for the Sinch Customer Dashboard.
Get access to the Conversation API.
Create your app.
Create your access key. Any API calls you make will require authentication information provided by your access key.

Refer to the Conversation API Getting started section for more information on any of these steps.

WhatsApp Requirements

To use the WhatsApp channel, you'll need a Sinch WhatsApp Sender ID. The method by which you create Sender IDs depends on whether your a direct enterprise customer or an ASP.

Creating Sender IDs as a direct enterprise customer

If you are a direct enterprise customer (that is, a customer using the API for your own brand), you can create a Sender ID from the Sinch Customer Dashboard using the embedded signup process. See How do I use the WhatsApp embedded signup process on the Sinch Customer Dashboard? for more information.

Creating Sender IDs as an ASP

If you are an ASP, you may also create Sender IDs using the embedded signup process on the Sinch Customer Dashboard (this requires your client's Meta credentials).

Note:

You can also incorporate the Embedded Signup functionality into your own system. See our WhatsApp ASP onboarding guide for more information.

Alternatively, you can use the On-behalf-of (OBO) process, in which you will set up a new account on behalf of your client(s), eliminating the need to share exisitng Meta credentials.

Configuring the Conversation API and WhatsApp integration

After ensuring that you meet the above prerequisites, you must enable the WhatsApp integration for your Conversation API app. You can do so using the Sinch Customer Dashboard, or using a combination of Sinch Provisioning API calls and Sinch Conversation API calls.

Enabling the WhatsApp integration using the Sinch Customer Dashboard

When enabling the WhatsApp channel through the Sinch Customer Dashboard, select your app and click SET UP CHANNEL next to the relevant WhatsApp channel. Then, select the appropriate Sender Identity (also known as a WhatsApp bot) and click SAVE.

Note:

The Conversation API has regional servers. If your business is located in Brazil or Mexico, you can assign the corresponding WhatsApp Sender Identities to Conversation API apps configured for the US or BR servers. If your business is located elsewhere, you can assign the corresponding WhatsApp Sender Identities to Conversation API apps configured for the US or EU servers.

You must also configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. See How to add a webhook to a Conversation API app for more information.

Setup WhatsApp integration using the API

To setup the WhatsApp integration programmatically, use the following snippet to configure the channel credentials for the app with the WhatsApp channel:

Copy

Copied

{
  "channel_credentials": [
    {
      "channel": "WHATSAPP",
      "static_bearer": {
        "claimed_identity": "{{WHATSAPP_BOT_ID}}",
        "token": "{{WHATSAPP_BEARER_TOKEN}}"
      }
    }
  ]
}

You need to replace {{WHATSAPP_BOT_ID}} with your Sinch WhatsApp Sender ID and {{WHATSAPP_BEARER_TOKEN}} with the Sender ID's access token.

Note

Any API calls you make will require authentication information provided by your access key. For more information, see this Overview.

You must also configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. For more information on how to do this programmatically, click here. The most important triggers for your conversation applications are:

MESSAGE_DELIVERY - Delivery receipts for business messages.
MESSAGE_INBOUND - Inbound messages, contact replies.

Next steps

After creating a channel, you need to set the channel priority in your app. Then, it's time to send your first message.

You must know your contact's channel/idenity pair or contact_id prior to sending a message. For WhatsApp, the channel is WHATSAPP and the identity is simply the phone number associated with the contact's WhatsApp account. To get a list of any existing contact_id values, you can make a GET request to the contact endpoint. For more information, see the API reference. Also note the following:

All marketing, utility or authentication conversations on the WhatsApp channel must start with an “Opt-In” by the user. This can be collected through any third party channel. For example in an SMS message, a web form, or email. Businesses must also provide a method by which customers may opt-out of receiving future messages from your organization.
Remember that you can only send a generic message on the WhatsApp channel of the Conversation API during a 24-hour customer care session. If you have not yet initiated a conversation with your chosen contact, or the last 24 hour customer care session expired, you can can send the contact a template message.

Once you have set your channel priority and have your contact's ID, you can begin sending and receiving messages in your preferred language:

If you are an existing customer looking for information on the standalone WhatsApp API, see our archived reference documentation.