# 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](/docs/conversation/getting-started) steps, you can skip this section. 1. Sign up for the Sinch Build 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](/docs/conversation/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 you're a [direct enterprise customer](#creating-sender-ids-as-a-direct-enterprise-customer) or an [ASP](#creating-sender-ids-as-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 Build Dashboard using the embedded signup process. See [How do I use the WhatsApp embedded signup process on the Sinch Build Dashboard?](https://community.sinch.com/t5/WhatsApp/How-do-I-onboard-to-Sinch-s-WhatsApp-service-using-the-Sinch/ta-p/17787) for more information. #### Creating Sender IDs as an ASP If you are an [ASP](https://community.sinch.com/t5/Glossary/ASP/ta-p/7467), you may also create Sender IDs using the embedded signup process on the Sinch Build 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](/docs/conversation/channel-support/whatsapp/asp-tutorial/) 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. #### Create channel-specific templates Follow the [WhatsApp template documentation](/docs/conversation/channel-support/whatsapp/template-support) to create your first template. Make note of the `templateName`, as you'll need it in the send request. ## 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 Build Dashboard](https://dashboard.sinch.com/convapi/overview), or using a combination of Sinch Provisioning API calls and Sinch Conversation API calls. ### Set up the WhatsApp integration using the Sinch Build Dashboard When setting up the WhatsApp channel through the [Sinch Build Dashboard](https://dashboard.sinch.com/convapi/overview), 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](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100) for more information. The events your app should listen for are: - MESSAGE_DELIVERY — confirms message delivery statuses - MESSAGE_INBOUND — triggered when a user replies ### Set up WhatsApp integration using the API To set up the WhatsApp integration programmatically, use the following snippet to configure the channel credentials for the **app** with the WhatsApp channel: ```json { "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](/docs/conversation/callbacks#creating-webhooks-using-the-api) for more information. The events your app should listen for are: - MESSAGE_DELIVERY — confirms message delivery statuses - MESSAGE_INBOUND — triggered when a user replies ### Establishing channel priority If your application supports multiple channels, you can configure how messages should be routed by defining [channel priority](/docs/conversation/channel-support/prioritize-channels/). If your app only uses WhatsApp, you may skip this step. ## Sending your first message 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: ### Understanding WhatsApp messaging windows WhatsApp requires an open [customer service window](https://community.sinch.com/t5/WhatsApp/What-is-a-Customer-Care-Session/ta-p/6858) to send [generic](/docs/conversation/channel-support/whatsapp/message-support) 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](/docs/conversation/channel-support/whatsapp/direct-api) (currently in Beta and only available to selected businesses). For this guide, we'll continue using [template messages](#create-a-channel-specific-template). ### Understanding recipient identity To send a message, you must already know either: - A `channel` + `identity` pair, or - A `contact_id` Recommended approach 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](/docs/conversation/api-reference/conversation/contact/contact_listcontacts). ### Sending the message Note 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](/docs/conversation/api-reference/conversation#section/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](/docs/conversation/api-reference/conversation/messages/) with the following payload: ```json { "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}}", } } } } } } ``` Note 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: ```json { "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](/docs/conversation/channel-support/whatsapp/message-support). You can also use our [getting started guide](/docs/conversation/getting-started/) to perform these steps programmatically.