Connect your WhatsApp Business number to Chatwoot using Meta’s WhatsApp Cloud API. This guide walks you through preparing your Meta account, generating the required access token, and creating your WhatsApp inbox in Chatwoot.
Get your WhatsApp Cloud API details from Meta
WhatsApp Cloud API is hosted by Meta and available to businesses and individual developers. It lets you connect directly to the WhatsApp Business Platform without relying on a third-party provider to host the API.
To create a WhatsApp inbox, you need three details from Meta:
-
WhatsApp Business Account ID
-
Phone Number ID
-
Permanent access token or system user token
You can get the WhatsApp Business Account ID and Phone Number ID from your Meta app.
Create or select a Meta app
Go to Meta for Developers and either select an existing app or click Create App.
If you are creating a new app, enter an app name and contact email, then click Next.
Choose the WhatsApp use case
On the use case selection screen, choose Connect with customers through WhatsApp, then click Next.
Choose a business portfolio
Select the business portfolio that owns or will own your WhatsApp Business Account.
If you do not already have a business portfolio, you can create one during this step or continue and create it later if Meta allows it.
Review publishing requirements
Meta may show publishing requirements for the selected app and use case. Review the requirements and click Next.
Review and create the app
Review the app details, selected WhatsApp use case, and connected business portfolio. Click Create app to finish.
Open WhatsApp API setup
After the app is created or selected:
-
Click Use cases in the sidebar.
-
Find Connect with customers through WhatsApp.
-
Click Customize.
-
Click API Setup.
In the new Meta app interface, go to Basic setup → Step 2. Production setup and open Register your WhatsApp phone number.
In older Meta apps, open WhatsApp → API setup from the left sidebar.
Add or select your WhatsApp phone number
If this number is currently active in the WhatsApp Business app, do not delete or manually register it through this flow. Use Chatwoot’s Embedded Signup/Coexistence flow, or contact Chatwoot Support.
In the Send and receive messages or Register your WhatsApp phone number section, choose an existing number from the From selector, or click Add phone number.
If you are adding a new number:
-
Enter your WhatsApp Business display name and business details.
-
Enter the phone number.
-
Choose verification by SMS or phone call.
-
Enter the OTP code from Meta to verify the number.
Copy the required IDs
After the number is added or selected, copy these values from the API setup page:
-
Phone Number ID
-
WhatsApp Business Account ID
You will need to paste these values into the manual setup flow.
In the older Meta UI, these values are shown directly under the From selector in WhatsApp → API setup.
Meta changes this interface frequently. If your screen looks different, look for the WhatsApp API setup page and the selected sender number. The Phone Number ID and WhatsApp Business Account ID are usually shown near the selected From phone number.
Set up a permanent WhatsApp Cloud API access token
You also need a permanent system user access token with WhatsApp permissions. This token allows Chatwoot to connect to your WhatsApp Cloud API number, send and receive messages, and sync message templates.
Open System users in Meta Business Settings
-
Open Meta Business Settings.
-
Select the business portfolio that owns your WhatsApp Business Account.
-
Go to Users → System users.
-
If you already have a system user for Chatwoot, select it.
-
If you do not have one, click Add.
Create a system user
-
Enter a name for the system user, such as
Chatwoot WhatsApp. -
Select Admin as the system user role.
-
Click Create system user.
Generate a token
-
Select the system user.
-
Click Assign assets.
-
Assign the Meta app and WhatsApp Business Account.
-
Grant the required control.
-
Click Generate token.
Select the Meta app
Choose the Meta app that you created or selected earlier for WhatsApp Cloud API setup, then click Next.
Set token expiry
Select Never as the token expiry, then click Next.
Assign permissions
Select the required WhatsApp permissions:
-
whatsapp_business_messaging -
whatsapp_business_management
Then continue to generate the token.
Copy the token
After Meta creates the token, click Copy and store it securely.
Keep this token private. Anyone with access to it may be able to use your WhatsApp Cloud API connection.
Connecting Your Chatwoot Account
Let's connect your Chatwoot account with your WhatsApp Cloud API. Log into your Chatwoot account, go to Settings > Inbox > Select Manual flow.
Enter your phone number, phone number ID, and business ID, Access token whoch you got from previous step
Add team members to your WhatsApp inbox
Copy the webhook URL and webhook verification token provided here
Set Up Your Webhook
We need to set up the WhatsApp webhook to receive incoming customer messages sent to your business number.
Your callback URL should be in the format of https://app.chatwoot.com/webhooks/whatsapp/{phone_number}.
Log into your Facebook developer account and navigate to WhatsApp > Configuration
Paste your Chatwoot webhook URL and verification token here, then click "Verify and Save"
Set up webhook permissions by subscribing to messages
That's it—you're all done! You can now start sending WhatsApp messages through Chatwoot.
FAQs
How to configure multiple numbers under a single Meta app?
Meta 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 Meta app for all the other inboxes to work.
What type of WhatsApp templates are supported by Chatwoot ?
Please check the doc for more details about templates.
What are the supported media types?
