How to setup a WhatsApp channel?

You can manage your WhatsApp business account conversations from Chatwoot. To set it up, you have two options to choose your provider:

1. WhatsApp Cloud API

2. Twilio

We'll explain all the procedures in this guide.

Prerequisites

Before bringing your WhatsApp inbox to Chatwoot, you need to set some things up in the API provider you want to use. These prerequisites are explained below.

Using WhatsApp Cloud API

If you are planning to use the WhatsApp Cloud API, the following two prerequisites are needed.

I. Configure your Facebook Developer App​

First, you need to create your Facebook Developer app with WhatsApp Product enabled. Go to the WhatsApp Cloud API Guide and navigate to the section called Set up Developer Assets and Platform Access and follow the steps.

Once you finish this step, you can now configure your required phone numbers in the WhatsApp section of your Facebook developer app. If you complete the steps successfully, you should be able to obtain the Phone Number Id and Whatsapp Bussiness Account ID, as shown in the below screenshot. Chatwoot will require these values for creating the WhatsApp Inbox.

II. Configure a system user for your Facebook Business Manager​

Create a system user in your Business Manager with access to the WhatsApp App. Generate an access token for the user, which will be required as the API key for setting up an inbox in Chatwoot.

When generating the access token, make sure the whatsapp_business_management and whatsapp_business_messaging permissions are selected.

Step 1. Create a system user in the System Users tab of Business Manager.

Step 2. Add the system user. Under the WhatsApp Accounts tab, select “Add People” and select the system user to grant access to the WhatsApp Business account.

Step 3. Generate the access token and request permissions.

Refer to this video for detailed steps.

Using Twilio

If you are planning to use the Twilio API, the following prerequisites are needed.

To connect to a WhatsApp inbox, you'll need to configure a callback URL in the Twilio inbox. Follow the steps below.

1. Login to your Twilio Console.

2. Go to Programmable SMS -> Whatsapp -> Senders.

3. You will be able to see your phone number. Click on it. It will display a field like the one shown below.

   

4. Provide https://app.chatwoot.com/twilio/callback as the value for WHEN A MESSAGE COMES IN input.

Twilio Studio

If you use Twilio Studio for a custom conversation flow, updating the webhook URL directly will break your existing integration.

For such cases, you can follow the steps given below.

1. Identify the step in your flow where you want the agent handoff to happen.

2. Add a make http request widget as shown below with the given values.

   

   REQUEST METHOD : POST

   REQUEST URL: https://app.chatwoot.com/twilio/callback

   CONTENT TYPE: Application/JSON

   REQUEST BODY: {{trigger.message | to_json }} ( make changes as required based on your flow variables).

   HTTP request widget will forward the message body to Chatwoot. This will create a conversation in Chatwoot from where the agent can reply.

3. Make sure that your flow can handle the user responses to Agent Replies.

Setting up WhatsApp Inbox in Chatwoot

If your prerequisites are met, you can create your WhatsApp inbox in Chatwoot. Follow the steps outlines below.

Step 1. Open your Chatwoot dashboard. Go to Settings → Inboxes → Add Inbox.

Step 2. Click on the "WhatsApp" icon.

Step 3. Choose an API provider. Based on your selection, you will see a different set of fields to be filled. Let us learn about each of them.

Selecting WhatsApp Cloud API

Choose "WhatsApp Cloud" as the API provider.

The fields, as seen in this selection, are explained below.

Finish the steps to obtain your Whatsapp Webhook Callback URL.

Enable the webhook​

Configure the webhook in Facebook Developer App.

Head back to the WhatsApp section in the Facebook Developer App. Navigate to the Configuration subsection and set up the Callback URL.

• The value for the URL should be the same URL you obtained at the end of your Chatwoot inbox creation and will look like https://app.chatwoot.com/webhooks/whatsapp/+{phone_number}.

• The value for the verify token should be the same value you configured for the Webhook Verify Token during inbox creation.

You should also subscribe to message field events on your Facebook Developer app under Webhooks Fields.

Once you finish all the steps, the section should look like the screenshot.

Selecting Twilio

Choose "Twilio" as the API provider.

The fields, as seen in this selection, are explained below.

Click "Create Twilio Channel" after filling in the information.

Step 4. "Add agents" to your inbox.

You have successfully created a whatsApp inbox.

Additional Inbox settings​

Your freshly configured WhatsApp inbox should now appear in your list of inboxes. To see this and to make additional settings in your WhatsApp inbox, go to Settings → Inboxes → click the gear icon on the associated WhatsApp inbox.

All the Additional Settings available are the same as those in your Twitter inbox. We recommend going through this link to understand the same.

Supported media types

Your WhatsApp inbox supports various media types, as summarized below.

Audio

Supported extensions:

• aac

• mp4

• mpeg

• amr

• ogg

Supported for: Both end-user and the agent in Chatwoot

Document

Supported extensions:

• text/plain

• application/pdf

• application/vnd.ms-powerpoint

• application/msword

• application/vnd.ms-excel

• application/vnd.openxmlformats-officedocument.wordprocessingml.document

• application/vnd.openxmlformats-officedocument.presentationml.presentation

• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Supported for: Both end-user and the agent in Chatwoot

Image

Supported extensions:

• jpeg

• png

Supported for: Both end-user and the agent in Chatwoot

Video

Supported extensions:

• mp4

• 3gp

Supported for: mp4 for both the end-user and the agent in Chatwoot, and 3gp for only the end-user.

Sticker

Supported extensions: image/webp

Supported for: Only end-user

FAQ​

How to configure multiple numbers under a single Facebook app?​

Facebook App allows configuring only a single Webhook endpoint. So create Inboxes in Chatwoot for all the numbers as required. You will need to configure the Webhook URL provided for only one of these inboxes in the Facebook app for all the other inboxes to work.

What type of Whatsapp templates are supported by Chatwoot ?

At the moment, Chatwoot only supports text-based templates. If your template has media headers or custom components like buttons, forms, etc, they won't be shown on the Chatwoot template selector.