In today's digital era, Omnichannel customer care is a vital factor for every business. WhatsApp, with over 2 billion users globally, is one of the most important communication channels that you cannot ignore. By combining the power of WhatsApp with Chatwoot – the leading open-source Omnichannel Customer Engagement platform – your business can manage thousands of messages from customers efficiently, centrally, and professionally.

This article will guide you through every step in detail to integrate WhatsApp Cloud API into Chatwoot using the manual method (Manual Flow). This is the approach that helps you take full control of your data and configuration without depending on expensive third-party Business Solution Providers (BSPs).

Why should you use WhatsApp Cloud API with Chatwoot?

Before diving into the technical details, let's go over some of the great benefits when you perform this integration:

• Cost savings: WhatsApp Cloud API is hosted directly on Meta's infrastructure, helping to eliminate intermediary costs that you previously had to pay to BSPs like Twilio or MessageBird.
• High speed and stability: Connecting directly with Meta ensures the lowest latency and highest stability for your messaging system.
• Centralized management: Chatwoot allows you to aggregate messages from WhatsApp, Facebook, Email, and Live Chat into a single interface, helping support staff avoid switching between multiple applications.
• Automation: Leverage Chatwoot features like Chatbots, Automation Rules, and Canned Responses to respond to customers quickly.

Prerequisites

For the installation process to go smoothly, you need to prepare the following resources:

1. Meta Developer Account: If you don't have one, register for free at developers.facebook.com. This is where you manage applications connecting to the Facebook/Instagram/WhatsApp ecosystem.
2. Valid phone number: You need a phone number capable of receiving SMS messages or voice calls for verification.
   • Important notes: This phone number must not be currently linked to any personal WhatsApp account or WhatsApp Business App on a phone. If it is, you must delete the WhatsApp account on the phone before using it for the API.
3. Facebook Business Account: Able to access business.facebook.com to manage business assets.

Step 1: Set up a Business Profile

The first step is to create an identity for your business on the Meta platform. This helps Meta verify the business and grant access to advanced WhatsApp API features.

1. Access business.facebook.com.
2. If you are a newcomer, create a Business Portfolio (formerly known as Business Manager Account).
3. Fill in all legal information for the business such as Business Name, Business Email, and Address. Accurate information will help the Business Verification process go faster later, although for basic usage you may not need verification immediately.

Step 2: Create a Facebook App

Similar to creating a technical “gateway”, the App on Facebook Developers is where API configurations are housed.

1. Visit the page My Apps and click the green button Create App.
2. At the “What do you want your app to do?” screen, select the option Other (Other). Press Next.
3. At the “Select an app type” screen, select Business. This is the type of app for managing Pages, Events, and the WhatsApp Business API. Press Next.
4. In the “Details” section:
   • App Name: Set an easy-to-remember name, for example “Chatwoot WhatsApp Connect”.
   • App Contact Email: Your email.
   • Business Portfolio: Select the Business account you created in Step 1. This is a required step to use the WhatsApp API in a Production environment.
5. Press Create app to complete. You may need to enter your Facebook password to confirm.

Step 3: Add the WhatsApp product to the app

After creating the App, you will be taken to the App Dashboard. At this point, your App doesn't have any functions yet; you need to add the WhatsApp “Product”.

1. Scroll down to find the item named WhatsApp in the product list. Press the button Set up.
2. Meta will ask you to select or create a new Meta Business Account. Select your Business account.
3. Press Continue. The system will take a few seconds to set up the WhatsApp Cloud API environment for you.

Step 4: Create a Permanent Access Token

This is the most important step and often the most confused. By default, Meta provides you with a “Temporary Access Token” that lasts only 24 hours. If you use this token to enter into Chatwoot, the connection will be disconnected after one day. You must create a “System User” to get a permanent Token.

1. Access Business Settings.
2. In the left menu, find the item Users > System Users.
3. Press the button Add. A popup will appear. Read carefully and click to accept the terms.
4. Name the System User, for example “Chatwoot Admin”. In the section System User Role, select Admin. Press Create System User.
5. After creation, you need to assign assets (App) to this user. Press the button Add Assets.
6. In the window that appears, select Apps, then select the name of the App you created in Step 2.
7. Turn on the option Full Control (Manage App) to grant full permissions. Press Save Changes.
8. Now, go back to the System Users list page, select the user you just created. Press the button Generate new token.
9. Select your App from the dropdown list.
10. Permissions: You need to find and check exactly 3 permissions (very important):
    • whatsapp_business_messaging: Allows sending and receiving messages.
    • whatsapp_business_management: Allows managing WhatsApp business information.
    • whatsapp_business_manage_events: Allows receiving webhook events (incoming messages, delivery status, etc.).
11. Press Generate Token. A long string of code will appear. Copy and store it in a safe place immediately, because Facebook will not display this code a second time. This is the “API Key” that you will enter into Chatwoot.

Step 5: Configure the WhatsApp phone number

You need to declare the actual phone number that will be used to chat with customers.

1. Return to the App Dashboard page on developers.facebook.com.
2. In the left menu, select WhatsApp > API Setup.
3. Scroll down to the section Step 5: Add a phone number, press the button Add phone number.
4. Fill in the WhatsApp profile information:
   • Display Name: Name displayed to customers (Example: ABC Customer Care).
   • Category: Select the appropriate business field.
5. Enter your phone number and select the verification method (SMS or Voice Call).
6. Enter the OTP code to complete verification.
7. After success, you will see your phone number appear in the list. Here, copy two important parameters: Phone Number ID and WhatsApp Business Account ID.

Step 6: Connect with Chatwoot

It is time to pair everything together on the Chatwoot interface.

1. Log in to your Chatwoot system with Administrator rights.
2. Go to Settings (Settings – gear icon) > Inboxes > Add Inbox.
3. Select the icon WhatsApp.
4. In the API Provider section, select WhatsApp Cloud (Note: do not mistakenly select Twilio or 360Dialog).
5. Fill in the configuration form:
   • Phone Number: Enter the verified phone number (Only enter numbers, including country code, no plus sign or spaces. Example: 84912345678).
   • Phone Number ID: Paste the ID you obtained in Step 5.
   • Business Account ID: Paste the ID you obtained in Step 5.
   • API Key: Paste the Permanent Access Token you created and saved in Step 4.
6. Press Create WhatsApp Channel.
7. In the next step, select the agents who will manage this inbox. Press Add agents.
8. The final screen will provide you with a Webhook URL and Webhook Verify Token. Keep this screen open or copy them.

Step 7: Configure Webhook

Entering the Token in Step 6 only helps Chatwoot send messages. For Chatwoot to receive messages sent by customers, you need to declare the Webhook address with Meta.

1. Return to the Facebook App Dashboard.
2. In the left menu, under WhatsApp > select Configuration.
3. Find the section titled Webhook, press the button Edit.
4. A popup window will appear:
   • Callback URL: Paste the Webhook URL provided by Chatwoot (usually in the form https://domain-cua-ban.com/webhooks/whatsapp/...).
   • Verify Token: Paste the Verify Token from Chatwoot.
5. Press Verify and Save. If the information is correct, the window will close and a green checkmark will appear. If an error is reported, check if the URL is publicly accessible (if you are installing Chatwoot on localhost, you need to use ngrok).
6. Not done yet! You need to register for the events you want to receive. In the section Webhook fields, click Manage.
7. In the Subscribe, column, find the row messages and check it. This is a mandatory event to receive message content. Additionally, you can select message_deliveries, message_reads to track sent/viewed status.
8. Press Done.

Complete and Test

Congratulations! You have completed the process of integrating WhatsApp Cloud API into Chatwoot. Now, the system is ready to operate.

How to test:

• Use another personal phone number to send a “Hello” message to the business phone number you just set up.
• Open the Chatwoot Dashboard, and you will see the new message appear in the WhatsApp Inbox.
• Try replying from Chatwoot; the personal phone will receive the response immediately.

A few operating notes (Troubleshooting)

• 24-hour rule: WhatsApp applies a 24-hour session policy. If a customer has not messaged you within the last 24 hours, you cannot send free-form messages to them. You must use Template Messages (Template messages) pre-approved by Meta to start a conversation.
• Update Token: If you accidentally used a temporary Token, the connection will be lost after 24 hours. Go to Chatwoot > Settings > Inboxes > WhatsApp > Configuration and update the new permanent Token.
• Error not receiving messages: Check the Webhook section again to see if you have Subscribed to the messages event. This is the most common error.

Hopefully, this guide helps you master the WhatsApp communication channel on Chatwoot. Wish your business strong growth with the new customer care system!