Chatwoot
en
Language
en English pt_BR Portuguese (Brazil) es Spanish

Migrate a WhatsApp Embedded Signup inbox to manual setup

Open in
View as Markdown Open in ChatGPT Open in Claude
Muhsin

Muhsin

Last updated on Jul 16, 2026

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

  1. Click Use cases in the sidebar.

  2. Find Connect with customers through WhatsApp.

  3. Click Customize.

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

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.

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.

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

  1. Open Meta Business 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.

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.

Generate a token

  1. Select the system user.

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

  • whatsapp_business_manage_events

Then continue to generate the token.

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.

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.

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

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.

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.

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.

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.