> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Manual Setup

> Set up WhatsApp Cloud API manually in ChatbotX using Meta Developer, a permanent token, WhatsApp Business Account ID, and webhooks.

**WhatsApp Manual Setup** lets you connect a Meta WhatsApp Cloud API number to ChatbotX without using Embedded Signup. Use this flow when you already manage your WhatsApp assets in Meta Business Manager and want to enter the business account ID, permanent token, and webhook settings yourself.

## Prerequisites

Before you begin, make sure you have:

* A Meta Developer account
* A Meta Business Portfolio
* A valid phone number that can receive SMS or voice verification
* Admin access to the Meta Business Portfolio that owns the WhatsApp Business Account
* Admin access to your ChatbotX installation
* A publicly accessible ChatbotX URL for webhook delivery

<Info>
  If you are developing locally, use a tunneling tool such as [ngrok](/channels/local-development-with-tunnels) so Meta can reach your ChatbotX webhook URL.
</Info>

## Step 1: Set up your Business Profile

Create or choose the Meta Business Portfolio that will own your WhatsApp Business Account. This portfolio stores your business details, WhatsApp assets, phone numbers, and system users.

<Steps>
  <Step title="Create or select a Business Portfolio">
    Go to [Meta Business](https://business.facebook.com/) and log in with the Facebook account that will manage the WhatsApp setup. If you do not have a portfolio yet, click **Create a business portfolio** and enter your business name, your name, and your business email. If you already have one, select it from the account dropdown.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-331.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=40de70dc854beec44b61f1835acb58fc" alt="whatsapp_manual_setup_create_business_portfolio_form" width="2974" height="1814" data-path="images/image-331.png" />
    </Frame>
  </Step>

  <Step title="Complete the business details">
    Fill in the required business information. Meta uses these details for account ownership, billing, and business verification.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-332.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=1c1f959a97c0438942565496dbf2abf7" alt="whatsapp_manual_setup_fill_in_the_required_business_information" width="2973" height="1805" data-path="images/image-332.png" />
    </Frame>
  </Step>
</Steps>

<Note>
  For production use, verify your business in Meta Business Manager before sending live WhatsApp messages at scale.
</Note>

## Step 2: Setup your Facebook App

If you already have a Facebook App (for example, from your [Messenger channel setup](/channels/facebook-messenger)), you can reuse it and skip directly to [Step 3](#step-3-add-whatsapp-to-your-app).

<Steps>
  <Step title="Create a new app">
    Go to the [Facebook Developer Portal](https://developers.facebook.com/apps/) and click **Create App**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-1.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=a4312497d6e27a9d63e2c2adc4fd6d12" alt="whatsapp_manual_setup_create_app" width="2409" height="757" data-path="images/image-1.png" />
    </Frame>
  </Step>

  <Step title="Enter app details">
    Enter your **App name** and **contact email**, then click **Next**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-340.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=fe94778ad2dd6d2b356444676ea6a8e3" alt="whatsapp_manual_setup_enter_app_name_and_contact_email_fields" width="2152" height="882" data-path="images/image-340.png" />
    </Frame>
  </Step>

  <Step title="Select a use case">
    When asked for a use case, select **Other**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-341.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=fc96efca42436d4bb2c1145045c95ac1" alt="whatsapp_manual_setup_use_case_selection_other_option_highlighted" width="2133" height="1677" data-path="images/image-341.png" />
    </Frame>
  </Step>

  <Step title="Choose app type">
    For the app type, choose **Business**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-4.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=a7bc6f433111bee494f0220d8505799c" alt="whatsapp_manual_setup_app_type_selection_business" width="2173" height="844" data-path="images/image-4.png" />
    </Frame>
  </Step>

  <Step title="Finish creation">
    Enter your contact email address and choose your business portfolio from the dropdown menu and click **Create App** to finish.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-342.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=41b4ef3002e14a7919c33fdbea33abb5" alt="whatsapp_manual_setup_choose_your_business_portfolio" width="2180" height="1091" data-path="images/image-342.png" />
    </Frame>
  </Step>
</Steps>

## Step 3: Add WhatsApp to your app

Add the WhatsApp product to your Facebook App so Meta can create or connect a WhatsApp Business Account and phone number.

<Steps>
  <Step title="Open the app dashboard">
    In the [Meta Developer Portal](https://developers.facebook.com/apps/), open the Facebook App you created or reused in the previous step.
  </Step>

  <Step title="Add the WhatsApp product">
    Click **Add Product** in the left sidebar, find **WhatsApp**, and click **Set Up**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-343.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=8638bc34165f32c61fce4e0ddc2209e4" alt="whatsapp_manual_setup_add_whatsapp_product_to_facebook_app" width="2788" height="1370" data-path="images/image-343.png" />
    </Frame>
  </Step>

  <Step title="Confirm the WhatsApp dashboard">
    After setup, Meta redirects you to the WhatsApp product dashboard. Keep this page open because you will return to it for the WhatsApp Business Account ID and webhook configuration.
  </Step>
</Steps>

<Warning>
  Do not use temporary test values for production. Before going live, add a verified payment method and complete Meta business verification if Meta requests it.
</Warning>

## Step 4: Set up a permanent WhatsApp Cloud API access token

ChatbotX needs a permanent token so it can send and receive WhatsApp messages without reconnecting every few hours. Create the token from a Meta System User with access to your app and WhatsApp assets.

<Steps>
  <Step title="Open System Users">
    Go to [Meta Business Settings](https://business.facebook.com/settings/system-users), then open **Users -> System Users**.
  </Step>

  <Step title="Create an Admin system user">
    If you do not already have a system user, click **Add**, enter a name, and choose **Admin** as the role.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-345.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=f557f85b71e3fb053d9b97bce172623c" alt="whatsapp_manual_setup_meta_business_system_users_page" width="2977" height="1810" data-path="images/image-345.png" />
    </Frame>
  </Step>

  <Step title="Assign assets">
    Select the system user, click **Add Assets**, choose your Facebook App and WhatsApp Business Account, grant **Full Control**, and click **Assign assets**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-346.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=a33d0bcc9527a55bfea9f70591e0be19" alt="whatsapp_manual_setup_assign_app_and_whatsapp_assets" width="2977" height="1812" data-path="images/image-346.png" />
    </Frame>
  </Step>

  <Step title="Generate a new token">
    Return to the system user details and click **Generate new token**. Select your Facebook App from the dropdown.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-349.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=9578886fefc0565ec004a246f687bfc4" alt="whatsapp_manual_setup_generate_new_system_user_token" width="2985" height="1814" data-path="images/image-349.png" />
    </Frame>
  </Step>

  <Step title="Select token permissions">
    Select these permissions at minimum:

    | Permission                        | Purpose                                  |
    | --------------------------------- | ---------------------------------------- |
    | `whatsapp_business_manage_events` | Receive WhatsApp event updates           |
    | `whatsapp_business_management`    | Read and manage WhatsApp Business assets |
    | `whatsapp_business_messaging`     | Send and receive WhatsApp messages       |

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-337.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=44fda2de028174af5ca34781d95753aa" alt="whatsapp_manual_setup_select_permissions" width="2971" height="1812" data-path="images/image-337.png" />
    </Frame>
  </Step>

  <Step title="Copy the token">
    Click **Generate Token** and copy the token immediately. You will paste this token into ChatbotX when creating the WhatsApp channel.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rTjZ_kv4tWWb4f4V/images/image-350.png?fit=max&auto=format&n=rTjZ_kv4tWWb4f4V&q=85&s=b670fae18f21441b574eb98bf2c844da" alt="whatsapp_manual_setup_copy_permanent_access_token" width="2982" height="1811" data-path="images/image-350.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Save the token in a secure password manager. Meta shows it only once. If you lose it, generate a new token and update ChatbotX.
</Warning>

## Step 5: Set up WhatsApp Cloud API

Set up the WhatsApp Business Account and production phone number in Meta. You will need the **WhatsApp Business Account ID** for ChatbotX.

<Steps>
  <Step title="Open API setup and Add your production phone number">
    In your Facebook App, open **WhatsApp -> API Setup**. Add the phone number you want customers to message. Complete verification with SMS or voice call.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/oRdBp7ZDTUXtf6fh/images/image-364.png?fit=max&auto=format&n=oRdBp7ZDTUXtf6fh&q=85&s=51afa038e21a97d434cfef3a1cf0028a" alt="whatsapp_manual_setup_add_and_verify_production_phone_number" width="2807" height="1688" data-path="images/image-364.png" />
    </Frame>
  </Step>

  <Step title="Copy your WhatsApp IDs">
    Copy the **WhatsApp Business Account ID** from the API setup page. Keep this value with your permanent token.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/9HqeqHeS6I71qQsZ/images/image-362.png?fit=max&auto=format&n=9HqeqHeS6I71qQsZ&q=85&s=c3f1bfccd823dee4d9f57d5cecb57ae1" alt="whatsapp_manual_setup_copy_business_account_id" width="2036" height="743" data-path="images/image-362.png" />
    </Frame>
  </Step>
</Steps>

## Step 6: Connect your ChatbotX account

Create the WhatsApp channel in ChatbotX and enter the values you collected from Meta.

<Steps>
  <Step title="Open channel settings">
    In ChatbotX, go to **Settings -> Channels** and click **Add WhatsApp**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/voS3Qh6j-s9Wg2oh/images/image-223.png?fit=max&auto=format&n=voS3Qh6j-s9Wg2oh&q=85&s=44b713c4420ac6e880c213e1bbdcfeee" alt="whatsapp_manual_setup_chatbotx_channels_add_whatsapp" width="3019" height="1263" data-path="images/image-223.png" />
    </Frame>
  </Step>

  <Step title="Choose manual setup">
    Select the manual WhatsApp Cloud API setup option. To proceed, you need to enable the connection settings as follows:

    * **Switch on "Connect an existing WhatsApp Business Account"**: Once this is enabled, the option for manual connection will appear below it.
    * Then, the **"Manual connect using System User Access token"** option will become visible.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/XJK78BpgkVn_wOZs/images/image-357.png?fit=max&auto=format&n=XJK78BpgkVn_wOZs&q=85&s=703c564465594bf655d57b472277f6f5" alt="whatsapp_manual_setup_toggle_options" width="992" height="468" data-path="images/image-357.png" />
    </Frame>
  </Step>

  <Step title="Enter your WhatsApp credentials">
    In this step, you will provide the necessary technical details from Meta:

    * **Enable "Manual connect using System User Access token"**: Switching this on will reveal the input fields for your specific account data.
    * **WABA ID**: Paste your WhatsApp Business Account ID into this field.
    * **Access Token**: Paste your permanent System User Access Token here.

    Ensure all values are copied correctly from your Meta Developer portal to establish the connection.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/XJK78BpgkVn_wOZs/images/image-356.png?fit=max&auto=format&n=XJK78BpgkVn_wOZs&q=85&s=05506241332220bb48b3ff281ce92a41" alt="whatsapp_manual_setup_waba_id_access_token_input" width="1037" height="724" data-path="images/image-356.png" />
    </Frame>

    <Frame>
      <img src="https://mintcdn.com/chatbotx/oRdBp7ZDTUXtf6fh/images/image-365.png?fit=max&auto=format&n=oRdBp7ZDTUXtf6fh&q=85&s=bd6c593a1ddf37aeedaff9741541e53d" alt="whatsapp_manual_setup_waba_id_access_token_input_2" width="2011" height="1061" data-path="images/image-365.png" />
    </Frame>
  </Step>

  <Step title="Copy webhook details">
    After **Continue manual connect**, copy the **Webhook URL** and **Webhook Verify Token** shown by ChatbotX. You will paste both values into Meta in the next step.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/9HqeqHeS6I71qQsZ/images/image-360.png?fit=max&auto=format&n=9HqeqHeS6I71qQsZ&q=85&s=65c23948d9c7fd70fcd7598402b87374" alt="whatsapp_manual_setup_chatbotx_copy_webhook_url_and_verify_token" width="1252" height="1829" data-path="images/image-360.png" />
    </Frame>
  </Step>
</Steps>

## Step 7: Set up your webhook

The webhook lets Meta send inbound WhatsApp messages and delivery events to ChatbotX.

<Steps>
  <Step title="Open WhatsApp configuration">
    In your Facebook App, go to **WhatsApp -> Configuration**.
  </Step>

  <Step title="Paste the callback URL and verify token">
    In the **Webhooks** section, paste the **Webhook URL** and **Webhook Verify Token** from ChatbotX, then click **Verify and Save**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/9HqeqHeS6I71qQsZ/images/image-363.png?fit=max&auto=format&n=9HqeqHeS6I71qQsZ&q=85&s=cd9860feae057144c06f867a72df125e" alt="whatsapp_manual_setup_meta_webhook_callback_url_and_verify_token" width="2781" height="1527" data-path="images/image-363.png" />
    </Frame>
  </Step>

  <Step title="Subscribe to messages">
    Under webhook fields, subscribe to "**flows"** and "\*\*messages" \*\*for your WhatsApp Business Account.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/9HqeqHeS6I71qQsZ/images/image-361.png?fit=max&auto=format&n=9HqeqHeS6I71qQsZ&q=85&s=b4dc710c42e3265a6ed9f7b1cd045d0a" alt="whatsapp_manual_setup_meta_subscribe_to_messages_and_flows_webhook" width="2811" height="1719" data-path="images/image-361.png" />
    </Frame>
  </Step>

  <Step title="Test the channel">
    Send a WhatsApp message to the connected phone number. The conversation should appear in the ChatbotX Inbox.
  </Step>
</Steps>

<Note>
  If the verification fails, confirm that your ChatbotX URL is public, the webhook token matches exactly, and your server can receive HTTPS requests from Meta.
</Note>

## FAQ and troubleshooting

<AccordionGroup>
  <Accordion title="Can I configure multiple WhatsApp numbers under one Facebook App?">
    Meta allows a Facebook App to use one webhook callback configuration for the WhatsApp product. In ChatbotX, create the WhatsApp channels you need, then configure the Meta webhook with the callback URL from the channel that should receive webhook verification. Messages for subscribed phone numbers can still be routed through the connected WhatsApp Business Account when the IDs and tokens are correct.
  </Accordion>

  <Accordion title="Messages do not appear in ChatbotX">
    Check that the **messages** webhook field is subscribed in Meta, the ChatbotX webhook URL is reachable over HTTPS, and the WhatsApp Business Account ID in ChatbotX matches the account that owns the tested phone number.
  </Accordion>

  <Accordion title="Outbound messages fail">
    Confirm the permanent token includes `whatsapp_business_messaging`, the system user has access to the WhatsApp Business Account, and the phone number has completed Meta verification.
  </Accordion>

  <Accordion title="Webhook verification fails">
    Copy the **Webhook Verify Token** from ChatbotX again and paste it into Meta without extra spaces. Also confirm your ChatbotX app URL is publicly accessible.
  </Accordion>

  <Accordion title="The token stopped working">
    Generate a new System User token with the same permissions, then update the WhatsApp channel credentials in ChatbotX.
  </Accordion>
</AccordionGroup>

## Reference Documentation

For more technical details, see the official Meta documentation: [WhatsApp Cloud API - Meta for Developers](https://developers.facebook.com/docs/whatsapp/cloud-api/).