This article details the steps required to set up a WhatsApp channel for use with the Sinch Conversation API.
Before you can set up a WhatsApp channel on the Conversation API, you need to do the following:
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.
If you have already completed the Conversation API Getting started steps, you can skip this section.
- Sign up for the Sinch Build 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.
To use the WhatsApp channel, you'll need a Sinch WhatsApp Sender ID. The method by which you create Sender IDs depends on whether you're a direct enterprise customer or an ASP.
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 Build Dashboard using the embedded signup process. See How do I use the WhatsApp embedded signup process on the Sinch Build Dashboard? for more information.
If you are an ASP, you may also create Sender IDs using the embedded signup process on the Sinch Build Dashboard (this requires your client's Meta credentials).
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 Partner-initiated WABA Creation process, to set up new account and phone number on behalf of your client.
Follow the WhatsApp template documentation to create your first template. Make note of the templateName, as you'll need it in the send request.
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 Build Dashboard, or using a combination of Sinch Provisioning API calls and Sinch Conversation API calls.
When setting up the WhatsApp channel through the Sinch Build 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.
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.
The events your app should listen for are:
MESSAGE_DELIVERY— confirms message delivery statusesMESSAGE_INBOUND— triggered when a user replies
To set up 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 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 programmatically for more information.
The events your app should listen for are:
MESSAGE_DELIVERY— confirms message delivery statusesMESSAGE_INBOUND— triggered when a user replies
If your application supports multiple channels, you can configure how messages should be routed by defining channel priority. If your app only uses WhatsApp, you may skip this step.
Once you have completed the prerequisite steps defined in the previous sections, you may send your first message. The subsections below detail the information you'll need to send the message and provide a code sample you may use for testing purposes:
WhatsApp requires an open customer service window to send generic messages. The service window lasts 24 hours, is opened by the user sending a message to your business, and resets every time the user sends a new message.
When the window is not open, you can send messages using either approved template messages or the WhatsApp Direct Send API (currently in Beta and only available to selected businesses).
For this guide, we'll continue using template messages.
To send a message, you must already know either:
- A
channel+identitypair, or - A
contact_id
Using a channel + identity pair is the recommended way to send messages, as it not only allows you to send messages without creating contacts beforehand, but is also expected to work faster under general conditions.
For WhatsApp, the channel is always WHATSAPP and the identity is the user's phone number associated with the contact's WhatsApp account. To retrieve a user's contact_id, you can make a GET request to the contact endpoint. For more information, see the API reference.
Since this guide is intended to testing purposes, you can use your access key and access key secret to authenticate using basic authentication (we recommend using your access key and secret to create a short-lived OAuth2.0 token when working in production environments). For more information, see this the Authentication section of the API Reference Overview.
Once you have completed all prerequisites, you can send your first message. In this example, we will send a text template with a single variable by making a POST request to the /messages:send Conversation API endpoint with the following payload:
{
"app_id": "{{APP}}",
"recipient": {
"identified_by": {
"channel_identities": [
{
"channel": "WHATSAPP",
"identity": "{{PHONE_NUMBER}}"
}
]
}
},
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "template_name",
"language_code": "en",
"parameters": {
"body[1]text": "{{YOUR_VARIABLE}}",
}
}
}
}
}
}The template_id variable in the WHATSAPP node corresponds to the name of the template, not the identifier.
Your message should be delivered to the recipient you designate in the API call. If you configured a webhook, you should see a payload similar to the following sent by Sinch:
{
"app_id": "01HP7JGFTPQSE6W90GFPVXPVNQ",
"accepted_time": "2025-11-26T14:18:58.095Z",
"event_time": "2025-11-26T14:19:11Z",
"project_id": "5db402eb-b8ef-475c-a082-65e47befc330",
"message_delivery_report": {
"message_id": "01KB08G85FZ0WC0PHM4CA3FJR7",
"conversation_id": "01KB01T6WEHKZGQ7T1TMFY4ZSE",
"status": "DELIVERED",
"channel_identity": {
"channel": "WHATSAPP",
"identity": "{{CUSTOMER_NUMBER}}",
"app_id": ""
},
"contact_id": "01KB01T6SZW5A03FR5W3X8GVJ9",
"metadata": "",
"processing_mode": "DISPATCH"
},
"message_metadata": "{\"pricing_category\":\"service\",\"whatsapp_conversation_id\":\"95571f1b86e059c934c85901def19de8\",\"pricing_type\":\"free_customer_service\"}",
"correlation_id": "",
"channel_metadata": {
"whatsapp": {
"conversation": {
"type": "service"
}
}
}
}Once the user replies, the customer service window will open and you'll be able to send other supported message types.
You can also use one of our getting started guides to perform these steps programmatically in your preferred language:
