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

The Conversation API provides support for the WhatsApp channel through the Sinch WhatsApp Business Messaging API. To use either the WhatsApp channel or the Sinch WhatsApp Business Messaging API, you'll need a Sinch WhatsApp Sender ID.

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.
If you are not an enterprise customer (for example, if you are an ASP), you'll be assigned Sender ID information by your account manager. This usually occurs during onboarding.

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 the API.

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.

Warning

Both the Conversation API and the Sinch WhatsApp API are regional. Your Conversation API App must be created in the same region that your WhatsApp Sender ID/bot is provisioned. If your Conversation API App is created in a different region than the WhatsApp Sender ID/bot, the WhatsApp channel will report errors.

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