CX Facebook Messenger¶

Connect a Facebook page to QVOICE Platform CX Channels so that Messenger conversations arrive in a CX inbox and agents can reply to them.

To integrate with Facebook Messenger, you need a Facebook (Meta) app.

Who does what

The Meta app belongs to the owner of the Facebook page, who creates it in their own Meta developer account. It carries their brand on the Facebook consent screen and stays under their control. Two steps need a platform administrator: entering the app credentials in CX Channels, and providing the CX Channels address to register with Meta. They are marked below.

Facebook is greyed out in CX Channels

Until a platform administrator enters the Meta app credentials, the Facebook card in Settings → Inboxes → Add Inbox is shown greyed out and cannot be selected. This is expected, not a fault. Complete this guide to enable it.

Throughout this guide, replace <cx> with the CX Channels address your administrator gives you, for example https://cx.example.com.

Facebook App¶

Go to Facebook Developer Portal: https://developers.facebook.com

Create App¶

Lets press Create App button

Select this one

Complete form - App name - Contact email - Not select a Business Manager account

Provide App ID and App Secret¶

Open App settings → Basic and send the App ID and App Secret to your platform administrator through a secure channel. Do not post the secret in a support ticket.

For administrators¶

Sign in to the CX Channels Super Admin console at <cx>/super_admin, open Settings, and click the configure icon on the Facebook card. Fill in:

Field	Value
Facebook App ID	The App ID
Facebook App Secret	The App Secret
Facebook Verify Token	A random string you generate. The page owner enters the same value when configuring the callback URL
Facebook API Version	Leave the default unless you need a specific version (prefixed with `v`, e.g. `v22.0`)
Enable human agent	Leave off unless the app is approved for the Human Agent feature

Then give the page owner:

the Verify Token you generated,
the callback URL: <cx>/bot,
the CX Channels domain, for Allowed Domains for the JavaScript SDK.

These settings take effect immediately; no restart is needed.

Use the Super Admin console, not environment variables

CX Channels reads FB_APP_ID, FB_APP_SECRET and FB_VERIFY_TOKEN from the Super Admin settings first. The environment variables of the same name are only read while the setting is still blank in the database, and once a blank setting has been saved, setting the environment variable has no effect. Always enter the values in the Super Admin console.

Configure App¶

Configure the product Facebook Login for Business:

Turn on Login with the JavaScript SDK.
In Allowed Domains for the JavaScript SDK, add the CX Channels address (<cx>).
In App settings → Basic → App domains, add the CX Channels domain as well.

CX Channels opens the Facebook login in a pop-up window from the CX Channels page. The login is rejected if that domain is not allowed.

Add Product: Messenger¶

Now its time to add the Facebook Page that we have

The nexts steps its to retrieve the Facebook Page from the Facebook account

Select Page

Result as follow

Configure Callback URL¶

Complete with: - Callback URL: <cx>/bot - Verify token: the Facebook Verify Token from your administrator

Result as follow

Configure Callback Subscriptions¶

Press Add Subscription

Select: - messages - messaging_postbacks - message_deliveries - message_reads - message_echoes

Result as follow:

Facebook Verification¶

Go to App Review -> Requests
Click on Request Permissions or Features

On App Review -> Permissions and Features click on Request advanced access on the permissions CX Channels requests when you connect a page:

pages_messaging
pages_show_list
pages_manage_metadata
pages_read_engagement
business_management
Business Asset User Profile Access

And then click on Continue requests

Select yes on the modal asking about enable multiple bussines clients

Go to Requests. In this step you submit the request for the advanced access permissions above

Its needed a business verification

Until the permissions are approved and the app is published, Meta only delivers messages from people who have a role on the app (App roles → Roles). Use those accounts to test.

Connect the page and assign a queue¶

In the Portal, go to Config → CX Channels → Settings → Inboxes and click Add Inbox.
Choose Facebook and click the Facebook login button.
A Facebook pop-up opens. Sign in with an account that manages the page and grant the requested permissions.
Back in CX Channels, choose the page, give the inbox a name and click Create Inbox.
Assign a queue. Open Settings → Inboxes → your Facebook inbox → Collaborators and select the queue whose agents will handle Messenger conversations.

An inbox without a queue hides every conversation

Messages sent to an inbox with no queue assigned are received and stored, but no agent is a member of the inbox, so nobody sees them. Always assign a queue.

Troubleshooting¶

Symptom	Cause	What to do
The Facebook card is greyed out in Add Inbox	No Meta app credentials are configured in CX Channels	Create the app and have your administrator enter the App ID and App Secret in the Super Admin console (For administrators)
The card is still greyed out after the administrator set the environment variables	The Super Admin setting already exists and is blank, so the environment variable is ignored	Enter the values in the Super Admin console
The Facebook pop-up shows an error about the domain or does not open	The CX Channels domain is not in Allowed Domains for the JavaScript SDK / App domains, or the browser blocked the pop-up	Add the domain (see Add Product: Facebook Login for Business) and allow pop-ups for the CX Channels site
Meta cannot verify the callback URL	The Verify Token in Meta does not match the one in the Super Admin console	Use exactly the same token in both places
The inbox exists but no conversations appear	No queue assigned to the inbox	Assign a queue
Only messages from app testers arrive	App not published, or permissions not yet approved	Publish the app and complete App Review