CX Instagram

Connect an Instagram professional account to QVOICE Platform CX Channels so that Instagram Direct messages arrive in a CX inbox and agents can reply to them.

This guide uses Instagram API with Instagram login, the integration Meta recommends for new apps. It does not need a Facebook page. If your deployment still uses the older flow through a Facebook page, see CX Instagram via Facebook Login.

Who does what

Most steps happen in the Meta developer console and are done by the owner of the Instagram account. Two steps need a platform administrator: entering the app credentials in CX Channels, and providing the two addresses you will register with Meta. They are marked below.

Overview

1. Create a Meta app with the Instagram use case.
2. Give the Instagram app ID and Instagram app secret to your administrator.
3. Add the messaging permissions.
4. Configure webhooks.
5. Register the redirect URI in Business login settings.
6. Connect the Instagram account from the Portal and assign a queue.
7. Publish the app and test with accounts that have a role on it.
8. Submit the app for App Review to receive messages from everyone.

Before you start

You need:

• An Instagram professional account (Business or Creator). A personal account can be switched to professional from the Instagram app: Settings and activity → Account type and tools → Switch to professional account.
• A Meta developer account at https://developers.facebook.com.
• From your administrator, two addresses for your QVOICE Platform deployment:
  • the Portal address, for example https://portal.example.com
  • the CX Channels address, for example https://cx.example.com

Throughout this guide, replace <portal> and <cx> with those two addresses.

1. Create the Meta app

1. Go to https://developers.facebook.com and click Create App.
2. When asked for a use case, choose the one to manage messaging and content on Instagram.
3. Complete the form and create the app.
4. Open Use cases → Instagram API → Customize → API setup with Instagram login. The rest of this guide happens on this page.

Reusing an app

If you already have a Meta app for CX Facebook Messenger or WhatsApp, you can add the Instagram use case to it instead of creating a new app.

2. Instagram app ID and app secret

At the top of API setup with Instagram login you will find the Instagram app name, Instagram app ID and Instagram app secret (click Show to reveal the secret).

Use the Instagram credentials, not the app's

A Meta app has two sets of credentials: the app's own App ID and App Secret (under App settings → Basic), and the Instagram app ID and Instagram app secret shown on this page. CX Channels needs the Instagram pair.

Using the App Secret by mistake is easy to do and hard to spot: the Instagram consent page still opens, but connecting the account fails afterwards with "Error validating verification code. Please make sure your redirect_uri is identical to the one you used in the OAuth dialog request". Despite the wording, the redirect URI is not the problem.

Send the Instagram app ID and Instagram app secret to your 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 Instagram card. Fill in:

Field	Value
Instagram App ID	The Instagram app ID
Instagram App Secret	The Instagram app secret
Instagram Verify Token	A random string you generate. The account owner enters the same value when configuring webhooks (step 4)
Enable human agent for instagram channel	Leave off unless the app is approved for the Human Agent feature

Then give the account owner:

• the Verify Token you generated,
• the webhook callback URL: <cx>/webhooks/instagram,
• the redirect URI: <portal>/portal/callcenter/config/cx_channels/instagram.

These settings take effect immediately; no restart is needed.

Also check that the Instagram Channel feature is enabled on the customer's CX account (Super Admin → Accounts → the account → Edit, then tick Instagram Channel in the features list). Accounts created on older versions can have it off, and the Instagram card then stays greyed out even with the credentials in place.

Use the Super Admin console, not environment variables

CX Channels reads INSTAGRAM_APP_ID and INSTAGRAM_APP_SECRET from the Super Admin settings first. An environment variable of the same name is only read while the setting is still blank in the database, and once a blank setting has been saved, the environment variable has no effect.

3. Add the messaging permissions

In section 1. Add required messaging permissions, make sure these are added:

• instagram_business_basic
• instagram_business_manage_messages

instagram_business_manage_comments and the Human Agent feature are optional. Human Agent lets agents reply up to 7 days after the customer's last message instead of 24 hours, and needs its own approval in App Review.

4. Configure webhooks

In section 3. Configure webhooks:

1. Callback URL: <cx>/webhooks/instagram
2. Verify token: the Verify Token from your administrator.
3. Click Verify and save.
4. In Webhook fields, set these to Subscribed:
   • messages
   • message_reactions
   • messaging_seen

The Test button creates a sample conversation

Each Test click next to a webhook field sends a sample notification. CX Channels stores the messages sample as a conversation from sender_username with the text random_text in the most recently connected Instagram inbox. It confirms that Meta can reach CX Channels, but it does not prove that real messages will be delivered (see step 7). Delete the sample conversation afterwards.

5. Register the redirect URI

In section 4. Set up Instagram business login, click Business login settings and add this address to OAuth redirect URIs:

<portal>/portal/callcenter/config/cx_channels/instagram

Enter it exactly as given, with no trailing slash, and click Save.

Why the Portal address

Instagram does not allow its authorization page to be shown inside another page, and CX Channels runs inside the Portal. The authorization therefore opens as a full page and Instagram sends you back to the Portal, which completes the connection. That is why the redirect URI points at the Portal, not at CX Channels.

6. Connect the account and assign a queue

1. In the Portal, go to Config → CX Channels → Settings → Inboxes and click Add Inbox.
2. Choose Instagram and click Continue with Instagram.
3. The Instagram page opens in the whole browser tab. Sign in with the Instagram professional account and approve access.
4. You are returned to the Portal and the inbox is created, named after the Instagram username.
5. Assign a queue. Open Settings → Inboxes → your Instagram inbox → Collaborators and select the queue whose agents will handle Instagram conversations.

An inbox without a queue hides every conversation

Messages sent to an Instagram inbox with no queue assigned are received and stored, but no agent is a member of the inbox, so nobody sees them. It looks exactly as if messages were not arriving. Always assign a queue, and assign it again if you delete and reconnect the inbox.

7. Publish the app and test

Meta does not send message notifications for an app that is not published — the console says so above the webhook settings: "To receive webhooks, your app must be in published state." An unpublished app still passes the webhook Test and still lets you connect the account, so this is easy to miss.

1. Publish the app. You can publish before App Review is approved.
2. Until App Review is approved, only accounts with a role on the app can be expected to work. Open App roles → Roles → Add people and add the Instagram accounts you will test with as Instagram Tester.
3. Each tester accepts the invitation in Instagram: Settings → Apps and websites → Tester invites.
4. From a tester account, send a message to the connected Instagram account and check that it appears in CX Channels.

Messages from accounts that the business account does not follow appear in Instagram under Message requests rather than the main inbox.

8. App Review

To receive messages from any Instagram user, Meta must approve the app's permissions.

1. Open App Review and request Advanced Access for:
   • instagram_business_basic
   • instagram_business_manage_messages
   • Human Agent, if you enabled it in step 2
2. Complete business verification if Meta asks for it.
3. Keep the app published.

Publishing is not the same as approval

In Use cases → Instagram API → Permissions and features, a permission that still shows Ready for testing has not been approved. Until it shows as approved, messages from Instagram users without a role on the app are not expected to reach CX Channels, even though the app is published.

After approval, send a message from an account without a role on the app to confirm that real customers get through.

Keeping the connection working

CX Channels renews the Instagram access token automatically while the inbox is in use. The token lasts about 60 days, so an inbox that sees no activity for that long, or whose access was removed from the Instagram account, becomes disconnected. Its settings then show "Your inbox is disconnected. You won't receive new messages until you reauthorize it." Click Click here to reconnect. — the Instagram page opens as a full page, just as when you first connected. Assign the queue again if it was lost.

Removing the app from the Instagram account, or deleting the Meta app, disconnects the inbox.

Troubleshooting

Symptom	Cause	What to do
The Instagram card is greyed out in Add Inbox	No Instagram app credentials in CX Channels, or the Instagram Channel feature is off for the account	Your administrator enters the Instagram app ID and secret and enables the feature on the account (For administrators)
Clicking Continue with Instagram leaves a blank area in the Portal	The deployment runs an older CX Channels version that opens Instagram inside the Portal	Ask your administrator to upgrade CX Channels and the Portal
Instagram rejects the request before showing the consent page	The redirect URI is not registered	Add <portal>/portal/callcenter/config/cx_channels/instagram in Business login settings (step 5)
After approving, "Error validating verification code. Please make sure your redirect_uri is identical…"	The administrator entered the app's App Secret instead of the Instagram app secret	Replace it in the Super Admin console (step 2) and connect again
The inbox exists but no conversations appear	No queue assigned to the inbox	Assign a queue (step 6)
Test reaches CX Channels, real messages do not	App not published; or App Review not approved and the sender has no role on the app	Publish the app and test with an Instagram Tester (step 7); complete App Review (step 8)
A conversation from sender_username saying random_text	Created by a webhook Test click	Delete it