Skip to content

Instagram Integration for Hosted Clients

This guide describes how to integrate Instagram as a communication channel in a hosted Rox.Chat Server installation using a custom Facebook App registered on the Facebook for Developers platform.

The integration works by connecting your Instagram Business account (linked to a Facebook Page) with your Rox.Chat Server through a properly configured Facebook App. This app acts as a bridge between Meta's APIs and Rox.Chat, enabling agents to receive and reply to messages from Instagram users.

Hosted customers are responsible for deploying and managing their own Rox.Chat Server instances. Integration with third-party services such as Instagram is performed independently or with assistance from Rox.Chat support, using the steps provided in this article.

The guide below includes step-by-step instructions on how to create the app, configure the required permissions, generate access tokens, and integrate the app into Rox.Chat Admin Panel.

Prepare Your Facebook Account and Project Assets

Before you start creating an app, ensure the following:

  • Ensure your personal Facebook profile is fully verified (phone, email, ID ready).
  • If the owner account is lost, the integration will stop working, so consider a dedicated admin profile.
  • Your Facebook account is an admin of the Facebook Page linked to the Instagram account.
  • Your project has:
    • A Privacy Policy and preferably Terms of Service (hosted online).
    • A logo image (1024×1024 pixels), with rights to use it.
    • An up-to-date contact email and real identity data in your Facebook profile (may be verified by Meta).
  • You've created a Facebook Page and converted your Instagram to a Business Account.

It's recommended to use a dedicated Facebook account for integration management to prevent access issues.

Register a Facebook Developer App

  1. Go to the Facebook for Developers website.
  2. Log in using your regular Facebook account.

  3. If this is your first time working with Facebook Developer tools:

    • Click Get Started in the top right corner.
    • A welcome screen will appear — select Continue.
    • If your Facebook profile does not include a verified phone number, you may be asked to provide and confirm one at this stage.
    • If no form appears, continue to the next step.

  4. Once completed, you'll land on the main dashboard. Click the Create App button.

  5. Type the name of your app and contact email.
  6. In the app type selection screen, scroll down and select Other.
  7. Then, in the next screen, select Business as the app type.

  8. Set the following fields:

    • Display Name — a public name for your app (e.g. “Rox.Chat Integration”)
    • App Contact Email — your business contact email

  9. Complete the CAPTCHA if prompted, and select Create App.

Configure the App for Instagram

  1. In the left sidebar select Add Products, find Messenger, and select Set Up.
  2. After this expand Messenger and select Instagram Settings in the left panel.
  3. Click Add or Remove Pages and select your Facebook Page linked to the Instagram Business account.
  4. Confirm and select Done.
  5. A new Access Token will appear — copy it and save it somewhere safe.
  6. Go to App Settings → Basic, copy the App Secret as well.

Add Instagram Channel in Rox.Chat

  1. Log into the Rox.Chat Admin Panel.
  2. Navigate to Settings → Channels → Instagram via Facebook App.
  3. Click Add Channel.

  4. Complete the required fields:

    • Page Name — an internal label for the channel
    • Access Token — from your Facebook App
    • App Secret — from Facebook Developer Console
    • Verify Token — a secure string you generate
    • Department (optional) — if you need to route messages to a specific department

Configure Facebook Webhooks

  1. In your Facebook App, go to Messenger → Instagram Settings → Webhooks.
  2. Click Add Callback URL.
  3. In the Callback URL, paste your Rox.Chat Server webhook address.
  4. In Verify Token, paste the same token you used in the Admin Panel. > The Rox.Chat tab must remain open — otherwise, Facebook will fail verification.
  5. Save changes.
  6. Then, select Add Subscriptions next to your Page.
  7. In the pop-up tick messages under the Instagram section and select Subscribe.
  8. Confirm and save.

App Review and Permission Requests

To use your app in production, Facebook requires you to request advanced access to the permissions.

  1. Navigate to App Review → Permissions and Features.

  2. Request Advanced Access for the following permissions:

    • pages_show_list — used to let users select a Page for connection.
    • pages_messaging — used to send and receive messages from Facebook and Instagram.
    • pages_read_engagement — used to fetch user profile pictures and names from messages.
    • pages_manage_metadata — used to generate and refresh the Long-Lived Access Token. Necessary for subscribing to Page messages.
    • instagram_basic — reads basic Instagram account info.
    • instagram_manage_messages — sends and receives Instagram messages.

  3. Click Edit App Review request next to each permission.

Fill Out Review Forms

  1. Go to Settings → Basic.
  2. Scroll down and click Add Platform, then select Website.
  3. Enter your website URL.

  4. Make sure the following are filled in:

    • Valid Contact Email
    • Privacy Policy URL (must be public and accurate)
    • App Icon (1024x1024)
    • App Category matching your use case

      Without these, Facebook will not let you submit the application.

  5. Include detailed testing instructions and credentials so that Meta reviewers can verify the integration. For example:

    1. Go to https://your_domain/agent/settings/channels/facebook_roxchat
2. Log in with test credentials
3. Click "Log in with Facebook" and authenticate
4. Click "Reconnect" → "Got it"
5. Select "Rox.Chat Testing" page → Save
6. Scroll to "Facebook using Rox.Chat application" → Edit → Save
7. Open https://your_domain/agent/chat
8. Send a message from the connected Facebook account
9. Rox.Chat receives it and displays a new session
10. Userpic is fetched, session is visible
11. Click the dialog and reply

  6. Include a screencast (video) showing this flow, and add it to each permission if required.

  7. After filling out the forms and uploading videos, select Submit for Review. You might be asked to enter your Facebook password.

Facebook usually responds in 5 business days. Status updates will be sent to the email address you provided. If your app involves external data, you may be asked to verify your identity or company registration.

Example Answers for App Review

When requesting permissions in App Review, you’ll be asked to explain how your app uses each permission. Below are example answers tailored for Rox.Chat's Instagram integration:

Permission Description
instagram_manage_messages This permission is required to facilitate two-way communication between Instagram users and our clients' business accounts.

It allows us to:
- Receive incoming messages sent by customers to the business account.
- Deliver outgoing messages from the business account to the customers.
- Synchronize messages in real-time, ensuring that messages sent via Instagram appear in our service and vice versa.
- Maintain conversation history and enable our clients to manage customer inquiries efficiently.

Without this permission, our service would not be able to send or receive messages on behalf of the business account, making the integration non-functional. This feature enhances customer support and engagement by allowing businesses to manage Instagram communications in a structured and professional manner.
instagram_basic This permission allows our system to retrieve basic profile data of users who initiate a conversation with our client's Instagram business account.

This is essential for identifying the customer within our service and displaying their details to the business client. Without this information, the client wouldn't be able to recognize or follow up with the customer effectively.

Additional Questions

Meta reviewers may also ask the following:

  • Does your app use a custom inbox?
    Yes.

  • Can users delete (unsend) messages?
    Our application can remove messages unsent in the mobile version of Instagram (the web version does not send us the webhook about unsending).

Publish the App

Once approved:

  • Switch your app from In Development to Live using the top toggle.
  • If rejected — fix only the denied permissions and resubmit.

Testing the Integration

  1. Use another Instagram account to send a message to your Business account.
  2. In Rox.Chat, a new conversation will appear in the Inbox, marked with Instagram as the entry point.
  3. Respond from Rox.Chat to confirm the two-way messaging works.

Troubleshooting

  • If no chat appears in Rox.Chat, double-check the token, webhook URL, and app permissions.
  • Make sure the Instagram account is Business type, and correctly linked to the Facebook Page.

Notes

  • Operators can only reply to messages within 24 hours of receiving them, per Instagram's policy.
  • In some cases, the app may be temporarily blocked immediately after being published. To lift the block submit an appeal via the Facebook Developer Console and complete any additional identity verification steps if requested (e.g., uploading an ID). Once these steps are completed, the block will be removed and the communication channel will become fully operational.

At this point, your Facebook App is live, the required permissions have been granted, and your Instagram Business account is successfully connected to Rox.Chat. You can now receive and respond to direct messages from Instagram users directly within your Rox.Chat operator interface.

Need Help?

If you experience any issues during the setup process or while requesting Facebook permissions, feel free to contact Rox.Chat Support for assistance.