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

1. Sign up for the Sinch Customer Dashboard.
2. Get access to the Conversation API.
3. Create your app.
4. 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 (recommended), 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.

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:

{
  "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.

You must also configure the callback URL of your WhatsApp Sender ID to point to your Conversation API app.

The callback URL is below:

https://whatsapp-adapter.{{REGION}}.conversation-api.int.prod.sinch.com/adapter/v1/{{CONVERSATION_APP_ID}}/callback

Replace {{REGION}} with either eu1 or us1, depending on the region of your app. Replace {{CONVERSATION_APP_ID}} with the ID of your Conversation API app.

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 ID prior to sending a message. For WhatsApp, that is simply the phone number associated with the contact's WhatsApp account. To get a list of your contact IDs, make a GET request to the contact webhook. For more information, see the API reference. Also note the following:

• All business initiated 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: