This guide helps you move an existing WhatsApp Cloud inbox to manual setup in Chatwoot. The migration keeps your existing inbox intact. Conversations, contacts, collaborators, routing rules, business hours, CSAT settings, bot settings, and other inbox settings are preserved.

> **WhatsApp numbers with Coexistence support are currently under review. If your WhatsApp number is also used in the WhatsApp Business App, contact Chatwoot Support before starting this migration.**

Before starting the migration, collect the required WhatsApp Cloud API details from Meta: WABA ID, Phone Number ID, and a permanent system user access token. Use the steps below to create or select a Meta app, add or select the WhatsApp phone number, and generate the token.

## Get your WhatsApp Cloud API details from Meta

To complete the migration, 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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCUFZCNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--1f606325708a807b616377c294d8f6ab773405c4/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRFJDNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--a289d00dec522df84ce9008ea0fdb583f32bdd77/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRkZDNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--a530ad1de8ee93a4cb598179012b8bd3e7fecfca/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSUJDNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--84077f3925813b62827752465f321f3f7850b7cc/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCS0pDNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8a8ee0aa597971b88d6b962b88b3590f73f8aae8/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTnRONHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cb19f0f9ed989a0fa8a59f8aeed546ba7daa5b05/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCUFpENHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--6d166ce9f67c24dd28dc4584f38ad4cd42eba7d2/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCR1JPNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--ea20129b52437bce02873cb8b19e369f3dc1f8d9/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTDVENHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--52d9b1ad6ec3ab149aea026c3422be5b5ec92963/old-ui-api.png)

### Add or select your WhatsApp phone number

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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSXhGNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--06635673d9dca75d676567697983cc9c3b1dd7bc/create-business-portfolio.png)

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRXhGNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2d87c35170f160b0d364c77df3e0813651d013fb/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 Chatwoot migration flow.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTlZHNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--99eb8165e60d568bb5987af12c8c1f0fa4bb3a99/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRlJINHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2d69164afa5b86f0c022c56a8e44f40fdf8281ba/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCT1JJNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--1c0d8becbf722cab74bf2309dfe1f9943c097f4e/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSkpMNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--52471a7d920c432a30fe0da42721f9af4e8491c6/CleanShot%202026-07-16%20at%2012.45.15@2x.png)

### Generate a token

1. Select the system user.

2. Click **Generate token**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRTlNNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--3fc13f84c0551ec2ebb5d567885d6827c8c1c9df/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSGRNNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--d7d7bf129b54cfb283abaeb0b456a8b2f82b6323/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCS3RNNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--4882df87fe944d64630f8cefcf2bcc3093b660b9/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/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVpNNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--6a69a730f132fcc05663f8bef110e817b6f54d35/CleanShot%202026-07-16%20at%2012.46.27@2x.png)

### Copy the token

After Meta creates the token, click **Copy** and store it securely. You will paste this token into the **Access token** step in the Chatwoot migration flow.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCT2hNNHdVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--3dadfaa25557bb093bb7af3713c2f5264befda82/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.

## Start the migration

1. Go to **Settings → Inboxes**.

2. Open the WhatsApp inbox connected via embedded signup.

3. Click **Start manual migration**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRllnMndVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0fed8e7f92b6a0dacb1a1ca68422eeec6a431a47/CleanShot%202026-07-13%20at%2014.28.42@2x.png)

Chatwoot will open a guided migration flow.

## Step 1: Review what will change

The first step explains what will be preserved and what will be updated.

Preserved:

* Conversations

* Contacts

* Collaborators

* Routing

* Business hours

* Inbox settings

Updated:

* WABA ID

* Phone Number ID

* Access token

* Webhook configuration

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCT01nMndVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--9e1d089787f62140ca6ee62fb27f44417f083d5c/CleanShot%202026-07-13%20at%2014.30.08@2x.png)

Click **Continue**.

## Step 2: Enter business details

Enter the WhatsApp asset details from Meta.

Fields:

* **WABA ID**: The WhatsApp Business Account that owns this phone number.

* **Phone Number ID**: Meta’s unique ID for the WhatsApp number connected to this inbox.

* **Display phone number**: The customer-facing WhatsApp number. This cannot be changed during migration.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRkFrMndVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--3554a80c878cdecba4de08b8c42ed6cb1a5a98fd/CleanShot%202026-07-13%20at%2014.35.38@2x.png)

Click **Continue**.

## Step 3: Add the access token

Paste a permanent access token or system user token with WhatsApp permissions. The token must include **whatsapp_business_messaging, whatsapp_business_management, and whatsapp_business_manage_events**.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSTBrMndVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--365e188d56d91c2b5adf3f3030e484f0e71d9614/CleanShot%202026-07-13%20at%2014.36.18@2x.png)

## Step 4: Review and reconnect

Review the inbox, phone number, WABA ID, and Phone Number ID before applying changes.

Chatwoot will verify the credentials with Meta before applying changes. If verification fails, the current configuration is left untouched.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRThsMndVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--57a16743b6aad7c8870c8e50e96c37ef93e271a7/CleanShot%202026-07-13%20at%2014.37.18@2x.png)

Click **Reconnect WhatsApp inbox** to complete the migration.

## After migration

After the migration succeeds, the inbox remains the same in Chatwoot, but the WhatsApp connection uses the manual WhatsApp Cloud API setup.

You should verify:

* Incoming messages

* Outgoing replies

* Template message sending

* Template sync

* Webhook delivery

## Need help?

If you are unsure about any step, contact Chatwoot Support. We can help you verify the required Meta details and assist with the migration.