Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • A valid Facebook account
  • A WhatsApp Business account (or the ability to create one)
  • A ChatbotX installation with a publicly accessible URL
  • Admin access to your ChatbotX installation
If you are developing locally, you will need a tunneling tool such as ngrok to expose your local server to the internet.

​
Step 1: Create a 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 2.
1

Create a new app

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

Enter app details

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

Select a use case

When asked for a use case, select Other.
Use case selection — Other option highlighted
4

Choose app type

For the app type, choose Business.
App type selection — Business option highlighted
5

Finish creation

Review your details and click Create App to finish.
Confirmation screen before creating the app
6

Get your App ID and App Secret

After creating your app, go to Settings → Basic to find your App ID and App Secret. Click Show and authenticate with your Facebook password to reveal the App Secret. You will need both values in the next step.
App ID and App Secret in Basic Settings

​
Step 2: Configure Credentials in ChatbotX

A Super Admin must enter the WhatsApp credentials in ChatbotX before the integration can work. Complete this step immediately after obtaining your App ID and App Secret.
1

Open Integrations

In your ChatbotX installation, navigate to:
Then select WhatsApp.
chatbotx_super_admin_integrations_whatsapp
2

Open the WhatsApp configuration

Find the WhatsApp card and click the Edit button to open the configuration modal.
chatbotx_super_admin_whatsapp_edit_modal
3

Fill in the WhatsApp credentials

In the Edit WhatsApp modal, fill in the following fields:
Client ID and Client Secret must exactly match the values in your Facebook App’s Settings → Basic. If any value is incorrect, the WhatsApp Embedded Signup flow will fail silently.
4

Save

Click Save to apply the settings. The WhatsApp card will now display your Client ID and Business Name. WhatsApp Embedded Signup will now be available as a channel when creating chatbots.

​
Step 3: Configure the WhatsApp Product

1

Add WhatsApp product to your app

In your Facebook app dashboard, click Add Product in the left sidebar. Find WhatsApp in the product list and click Set Up.
Adding WhatsApp product
2

Confirm the WhatsApp Quickstart dashboard

After clicking Set Up, you will be redirected to the WhatsApp Quickstart dashboard. This confirms the WhatsApp product has been added successfully.
whatsapp_quickstart_dashboard
If you see a “Missing valid payment method” warning, click Add payment method to configure billing. Without a valid payment method, you will not be able to send messages beyond the free test tier.
Do NOT click “Start using the API!”. This button is for direct Cloud API setup, which requires manual webhook and phone number configuration. ChatbotX uses the Embedded Signup flow instead, which automates the entire process. Skip this section entirely.
3

Add Facebook Login for Business product

The Embedded Signup flow requires the Facebook Login for Business product. Go back to the app dashboard, click Add Product, find Facebook Login for Business, and click Settings.
facebook_app_login
If you already have Facebook Login for Business added (for example, from a previous Messenger or Instagram setup), skip this step and proceed to Step 4.

​
Step 4: Obtain Configuration ID

The Configuration ID is the critical value that enables the WhatsApp Embedded Signup flow in ChatbotX. You obtain it from the Facebook Login for Business product settings through a 6-step configuration wizard.
1

Navigate to Facebook Login for Business configurations

In your Facebook app left sidebar, expand Facebook Login for Business and click Configurations. Click the Create configuration button to start the wizard.
Facebook Login For Business Configuration Menu
2

Name

Enter a descriptive name for this configuration (for example, BotX), then click Next.
Facebook Create Configuration Step Name
3

Login variation

Select WhatsApp Embedded Signup as the login variation, then click Next.
Facebook Create Configuration Step Login Variation
This setting cannot be changed later. Make sure to select WhatsApp Embedded Signup before clicking Next.
4

Products

Check the WhatsApp Cloud API checkbox at minimum, then click Next.
Facebook Create Configuration Step Products
This setting cannot be changed later. Make sure to select at least WhatsApp Cloud API before clicking Next.
5

Access token

Set Token expiration to Never for uninterrupted service, then click Next.
Facebook Create Configuration Step Access Token
6

Assets

Leave the default selections as-is — the wizard pre-selects the necessary assets based on your chosen products. Click Next.
Facebook Create Configuration Step Assets
7

Permissions

Review the permissions. Ensure at least these 3 WhatsApp permissions are included:
Facebook Create Configuration Step Permissions
Click Create to finalize the configuration.
8

Copy the Configuration ID

A success dialog will appear. Copy the Configuration ID displayed, you will need it when filling in the credentials in Step 2.
Facebook Configuration Id Generated Copy
Before overriding the current callback URI, your app must be subscribed to receive messages for the WhatsApp Business Account. This prevents error (#100) during webhook configuration. Ensure the messages webhook field is subscribed in your app’s Webhooks settings under the WhatsApp product section.

​
Step 5: Obtain System User ID and Token

1

Navigate to System Users

Go to Meta Business Settings and navigate to Users → System Users in the left sidebar. If you don’t have a System User yet, click Add, choose a name, and set the role to Admin.
meta_business_system_users
2

Generate Access Token

Select your System User and click Generate New Token. Configure the following:
  1. Select App: choose your Facebook App
  2. Token Expiration: select Never to avoid disruptions
  3. Select Permissions: check these 3 permissions:
meta_system_user_generate_token
meta_system_user_assign_permissions
Click Generate Token. Copy the generated token, this is your System User Token.
Save the token immediately. You will not be able to view it again after closing the dialog.
3

Get System User ID via Graph API Explorer

Go to the Meta Graph API Explorer, paste your System User Token into the Access Token field, set the request to GET /me, and click Submit. Copy the id value from the response, this is your System User ID.

​
Step 6: Create a WhatsApp Channel

Once the Super Admin has configured the integration credentials, users can connect their WhatsApp Business accounts through the Embedded Signup flow.
1

Navigate to Channel Selection

Go to Settings → Channel and click Add WhatsApp.
whatsapp_channel_selection
2

Choose your WhatsApp connection

Select the option that best fits your needs and click Continue:
  • Connect an existing WhatsApp Business Account: use if you already have a Meta Business account set up
  • Transfer phone from another WhatsApp provider: migrate your current number from a different BSP
  • Marketing Message Lite: for a marketing messaging setup
whatsapp_provider_selection
3

Connect your account

Follow the Meta embedded signup flow to link your WhatsApp Business account. Review the permissions, accept the Meta Hosting Terms for Cloud API and the Meta Terms for WhatsApp Business, then click Continue.
whatsapp_facebook_authentication
4

Select Business Assets

Choose your Business portfolio and WhatsApp Business account (or create new ones), then click Next.
whatsapp_select_business_assets
5

Fill Business Information

Enter your business Name, Category, Website, and Time zone, then click Next.
whatsapp_business_profile_details_setup
6

Add your WhatsApp phone number

Enter your WhatsApp Business display name and add a phone number. Complete verification via SMS or voice call, then click Next.
whatsapp_add_phone_number
7

Review and Confirm Permissions

Review the selected assets and access levels, then click Confirm to complete the integration.
meta_whatsapp_permission_review_confirmation
8

Complete Setup

Your WhatsApp account is now connected. Click Finish on the Meta popup to be redirected to ChatbotX. Your new WhatsApp channel will appear in the inbox section.
meta_whatsapp_connection_success_confirmation_details
chatbotx_dashboard_whatsapp_channel_management_interface

​
Commerce Policy Compliance

Meta will review your business to ensure it complies with WhatsApp’s Commerce Policy and will reach out within 24 hours if there’s an issue.

​
Troubleshooting

This usually means the Super Admin configuration is incomplete.Checklist:
  • Confirm the Super Admin has entered all required credentials (App ID, App Secret, Configuration ID) at /admin/platform-credentials
Your app must be subscribed to receive messages before overriding the callback URI.Fix:
  1. Go to your Facebook app in the Meta Developer Portal
  2. In the left sidebar, navigate to WhatsApp → Configuration
  3. Under Webhooks, subscribe to the messages field for WhatsApp Business Account
  4. Retry the Embedded Signup flow
Checklist:
  • Ensure you are logged into a Facebook account with admin access to the Meta Business Portfolio
  • Verify your app has the required permissions: whatsapp_business_management, whatsapp_business_messaging, whatsapp_business_manage_events
  • Confirm the App ID and App Secret in the Super Admin panel match the values in Settings → Basic of the Meta Developer Portal
What to do:
  • Ensure your business information is accurate and complete (legal name, website, address)
  • Check that your business complies with WhatsApp’s Commerce Policy
  • New accounts have a temporary message limit until verification is completed
  • Verification typically takes up to 1 business day
Steps to resolve:
  1. Open the rejected submission in the Meta Developer Dashboard
  2. Review the rejection reason and feedback provided by the review team
  3. Use the Messenger support icon (bottom right corner) to contact the review team for clarification
  4. Provide clear documentation of your use case, test credentials, and step-by-step instructions for the reviewer
  5. Resubmit after addressing all feedback
  1. Check ChatbotX logs: Look for error messages in both rails and sidekiq service logs
  2. Verify Facebook/WhatsApp accounts: Confirm all prerequisites (business verification, permissions, billing) are met
  3. Contact Community Support: Visit the ChatbotX Community with specific error messages and screenshots

​
Reference Documentation

For more technical details, refer to the official Meta documentation: WhatsApp Embedded Signup - Meta for Developers.