If you are having trouble with Embedded Signup or connecting an existing WhatsApp Business app number, see [Troubleshoot WhatsApp onboarding issues](https://www.chatwoot.com/hc/user-guide/articles/1789116643-troubleshoot-whats_app-onboarding-issues).

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**](https://developers.facebook.com/docs/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](https://developers.facebook.com/apps/) and either select an existing app or click **Create App**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTC82QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--6a6fe8ce45d12415ebb566feea542d9fb9a12dab/choose-or-create-app.png)

\
If you are creating a new app, enter an app name and contact email, then click **Next**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVA2QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--33e2461575baafbeb61276d9d04038cd74b21d77/create-app.png)

### Choose the WhatsApp use case

On the use case selection screen, choose **Connect with customers through WhatsApp**, then click **Next**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVg2QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--a848601497d112b8b083ae215371fd899a1d44ca/choose-whatsapp-use-case.png)

### 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.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTUw2QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--de094508d48317f09e729bf42b79bd56b45bfccd/choose-portfolio.png)

### Review publishing requirements

Meta may show publishing requirements for the selected app and use case. Review the requirements and click **Next**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTUQ2QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--68fa524755a64868fbf4319c556b94333743b176/publishing-requirments.png)

### Review and create the app

Review the app details, selected WhatsApp use case, and connected business portfolio. Click **Create app** to finish.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTUg2QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--bfa973f995b90571b4cf270c73539d4486da0946/review.png)

### Open WhatsApp API setup

After the app is created or selected:

1. Click **Use cases** in the sidebar.

2. Find **Connect with customers through WhatsApp**.

3. Click **Customize**.

4. Click API Setup.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ0Q4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--831f01b017a734b2c860493106bd0bd99c590aec/use-case.png)

In the new Meta app interface, go to **Basic setup → Step 2. Production setup** and open **Register your WhatsApp phone number**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQno4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--508f796638b1758872170a557647e9ad03d58b0e/new-ui-add-or-use-number.png)

In older Meta apps, open **WhatsApp → API setup** from the left sidebar.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQmo4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--f085505319b75ba0e84a65dcf7bc41f1d0c0f108/old-ui-api.png)

### 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:

1. Enter your WhatsApp Business display name and business details.

2. Enter the phone number.

3. Choose verification by SMS or phone call.

4. Enter the OTP code from Meta to verify the number.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQlQ4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--62360fefd025ebf3f6659f0907ae79b5d2fb6e89/create-business-portfolio.png)

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQmI4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8ef4db512a3ca74849c135b0bdae7224470a9596/add-number.png)

### 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.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQm44QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--7ca99f4d81babde83c16aa4e6aea5490491241d9/CleanShot-202026-07-16-20at-2012.38.30@2x.png)

In the older Meta UI, these values are shown directly under the **From** selector in **WhatsApp → API setup**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQnY4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--155d64142bf2e480fe36d763593d0dc924bd8e80/CleanShot-202026-07-16-20at-2012.39.36@2x.png)

> 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

1. Open [Meta Business Settings](https://business.facebook.com/settings).

2. Select the business portfolio that owns your WhatsApp Business Account.

3. Go to **Users → System users**.

4. If you already have a system user for Chatwoot, select it.

5. If you do not have one, click **Add**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQjM4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0b52dcd9332f77b1cddb1d0aad043652df164843/CleanShot-202026-07-16-20at-2012.43.38@2x.png)

### Create a system user

1. Enter a name for the system user, such as `Chatwoot WhatsApp`.

2. Select **Admin** as the system user role.

3. Click **Create system user**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQi84QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0866a00e31eb542833b7c442080321ff676e0734/CleanShot-202026-07-16-20at-2012.45.15@2x.png)

### Generate a token

1. Select the system user.

2. Click **Assign assets**.

3. Assign the Meta app and WhatsApp Business Account.

4. Grant the required control.

5. Click **Generate token**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQnI4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--85394befae278c1e0bc39e92b7442a3c13e6d85a/CleanShot-202026-07-16-20at-2012.43.38@2x-20copy.png)

### Select the Meta app

Choose the Meta app that you created or selected earlier for WhatsApp Cloud API setup, then click **Next**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQlg4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--4be301cf2a8435dc58ca05c3782da413f985932c/CleanShot-202026-07-16-20at-2012.45.37@2x.png)

### Set token expiry

Select **Never** as the token expiry, then click **Next**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQmY4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--b873faaae720eed362c3c61a39797d5710cd63a6/CleanShot-202026-07-16-20at-2012.45.48@2x.png)

### Assign permissions

Select the required WhatsApp permissions:

* `whatsapp_business_messaging`

* `whatsapp_business_management`

Then continue to generate the token.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQlA4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--06a023e8e986799b686c5722e941905452ea16a1/CleanShot-202026-07-16-20at-2012.46.27@2x.png)

### Copy the token

After Meta creates the token, click **Copy** and store it securely.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQjc4QVFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--bd725841111effe0e6b2ab966b900a5bc86d3dbb/CleanShot-202026-07-16-20at-2012.47.35@2x.png)

> 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.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRmdBQWdZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--37586dbbe2bca57b3971b173a22c8caf75d1eb12/CleanShot%202026-07-28%20at%2012.11.10@2x.png)

Enter your phone number, phone number ID, and business ID, Access token whoch you got from previous step

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCT1V3TlFFPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--36b14c0dff0a29cb3de0a07be4a8fa42f649decb/cw-2.png)

Add team members to your WhatsApp inbox

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCUFl3TlFFPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--aff01faf7c0ba58daf722b218a378ebdae62617d/cw-3.png)

Copy the webhook URL and webhook verification token provided here

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQVl4TlFFPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--ebc9f3052573b38afdd96995bfd97af6e9ed75cc/cw-4.png)

## **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}**](https://app.chatwoot.com/webhooks/whatsapp/%7Bphone_number%7D).

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"

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQmN4TlFFPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--3802889ac4ce26cd2264b6dab4267fd1cb6afe53/hk-1.png)

Set up webhook permissions by subscribing to messages

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ1V4TlFFPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--a8d5c4c957aa29875247a3b135eb2acf945fddcc/hk-2.png)

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**](https://www.chatwoot.com/hc/user-guide/articles/1754940076-whatsapp-templates) for more details about templates.

**What are the supported media types?**

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRHZuSWdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--469bfec94ea6ac0381da7d5223e83312dbaf5ca9/image.png)