Skip to main content

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 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
If you are developing locally, use a tunneling tool such as ngrok so Meta can reach your ChatbotX webhook URL.

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

Create or select a Business Portfolio

Go to Meta Business 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.
whatsapp_manual_setup_create_business_portfolio_form
2

Complete the business details

Fill in the required business information. Meta uses these details for account ownership, billing, and business verification.
whatsapp_manual_setup_fill_in_the_required_business_information
For production use, verify your business in Meta Business Manager before sending live WhatsApp messages at scale.

​
Step 2: Setup your Facebook App

If you already have a Facebook App (for example, from your Messenger channel setup), you can reuse it and skip directly to Step 3.
1

Create a new app

Go to the Facebook Developer Portal and click Create App.
whatsapp_manual_setup_create_app
2

Enter app details

Enter your App name and contact email, then click Next.
whatsapp_manual_setup_enter_app_name_and_contact_email_fields
3

Select a use case

When asked for a use case, select Other.
whatsapp_manual_setup_use_case_selection_other_option_highlighted
4

Choose app type

For the app type, choose Business.
whatsapp_manual_setup_app_type_selection_business
5

Finish creation

Enter your contact email address and choose your business portfolio from the dropdown menu and click Create App to finish.
whatsapp_manual_setup_choose_your_business_portfolio

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

Open the app dashboard

In the Meta Developer Portal, open the Facebook App you created or reused in the previous step.
2

Add the WhatsApp product

Click Add Product in the left sidebar, find WhatsApp, and click Set Up.
whatsapp_manual_setup_add_whatsapp_product_to_facebook_app
3

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

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

Open System Users

Go to Meta Business Settings, then open Users -> System Users.
2

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

Assign assets

Select the system user, click Add Assets, choose your Facebook App and WhatsApp Business Account, grant Full Control, and click Assign assets.
whatsapp_manual_setup_assign_app_and_whatsapp_assets
4

Generate a new token

Return to the system user details and click Generate new token. Select your Facebook App from the dropdown.
whatsapp_manual_setup_generate_new_system_user_token
5

Select token permissions

Select these permissions at minimum:
PermissionPurpose
whatsapp_business_manage_eventsReceive WhatsApp event updates
whatsapp_business_managementRead and manage WhatsApp Business assets
whatsapp_business_messagingSend and receive WhatsApp messages
whatsapp_manual_setup_select_permissions
6

Copy the token

Click Generate Token and copy the token immediately. You will paste this token into ChatbotX when creating the WhatsApp channel.
whatsapp_manual_setup_copy_permanent_access_token
Save the token in a secure password manager. Meta shows it only once. If you lose it, generate a new token and update ChatbotX.

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

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

Copy your WhatsApp IDs

Copy the WhatsApp Business Account ID from the API setup page. Keep this value with your permanent token.
whatsapp_manual_setup_copy_business_account_id

​
Step 6: Connect your ChatbotX account

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

Open channel settings

In ChatbotX, go to Settings -> Channels and click Add WhatsApp.
whatsapp_manual_setup_chatbotx_channels_add_whatsapp
2

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

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

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

​
Step 7: Set up your webhook

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

Open WhatsApp configuration

In your Facebook App, go to WhatsApp -> Configuration.
2

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

Subscribe to messages

Under webhook fields, subscribe to “flows” and “**messages” **for your WhatsApp Business Account.
whatsapp_manual_setup_meta_subscribe_to_messages_and_flows_webhook
4

Test the channel

Send a WhatsApp message to the connected phone number. The conversation should appear in the ChatbotX Inbox.
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.

​
FAQ and troubleshooting

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.
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.
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.
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.
Generate a new System User token with the same permissions, then update the WhatsApp channel credentials in ChatbotX.

​
Reference Documentation

For more technical details, see the official Meta documentation: WhatsApp Cloud API - Meta for Developers.