Skip to main content
Integrating Meta’s WhatsApp Embedded Signup solution on your portal allows your customers to connect their WhatsApp Business accounts through an intuitive step-by-step wizard directly in their browser.

​
Prerequisites

Before you begin, make sure you have:
  • A valid Facebook account
  • A WhatsApp Business account (or the ability to create one during setup)
  • A portal configured with a custom domain, running HTTPS protocol, and publicly accessible.
  • Super Admin access to your portal to set up Credentials.
If you are developing locally, you will need a tunneling tool such as ngrok to expose your local server to the internet to receive Facebook webhooks.

​
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 enter 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 the Admin Portal

You must enter the WhatsApp credentials in the Admin Portal under Super Admin access before the integration can work.
1

Open Integrations

Log in to your Admin Portal, navigate to:
https://app.chatconnectx.com/manage/integrations
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 fields:
FieldDescriptionWhere to findExample
Client IDFacebook App IDMeta Developer Portal → App → Settings → Basic1974877133429651
Client SecretFacebook App SecretSame page → click Show●●●●●●●●●●
API VersionGraph API versionApp → Settings → Advanced → API Versionv20.0
Webhook Verify TokenRandom string for webhook verificationSelf-generatedi7CTHYSF66uEHS3B
App Config IDConfiguration ID from the Embedded Signup wizardFacebook Login for Business → Configurations. See Step 4783655134328535
System User IDSystem User’s ID, obtained via Graph API ExplorerGraph API Explorer. See Step 5110835055179851
System User TokenAccess token generated for your System UserMeta Business Settings. See Step 5EAACanps...
Business ID*(optional)*Meta Business Portfolio IDMeta Business Settings → Business Info627055339164xxx
Business NameYour business display name in the systemYour own brand namechatconnectx
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.
4

Save

Click Save to apply the settings. The WhatsApp card will now display your Client ID and Business Name. WhatsApp Embedded Signup is now active.

​
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. ChatconnectX 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 ChatconnectX. 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, ChatconnectX), 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, as 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:
PermissionPurpose
whatsapp_business_managementRead and manage WhatsApp Business assets (phone numbers, profiles)
whatsapp_business_messagingSend and receive WhatsApp messages and make calls
whatsapp_business_manage_eventsLog events such as purchases, add-to-cart, and leads
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:
PermissionPurpose
business_managementManage business assets and settings
whatsapp_business_managementRead and manage WhatsApp Business assets
whatsapp_business_messagingSend and receive WhatsApp messages
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.
{
  "name": "Your System User Name",
  "id": "110835055179851"
}

​
User Connection Guide

After completing the app configuration on the Meta Developer Portal and entering the Credentials in the Admin Portal, your customers can connect their WhatsApp Business accounts through the Embedded Signup flow. For step-by-step instructions, see the WhatsApp Connection Guide.

​
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 /manage/integrations
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 server 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 Community Discord with specific error messages and screenshots

​
Reference Documentation

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