Docs/Configuring Your Agent/Connect to Instagram

Connect to Instagram

This tutorial walks you through connecting your qlar agent to an Instagram Business account using Meta Cloud (Meta's Instagram Messaging API). After completing setup, users can send direct messages to your Instagram Business account and receive AI-powered responses from your agent.

Prerequisites

Before you start, make sure you have:

  • An Instagram Business account (personal accounts cannot receive DM webhooks from Meta).
  • A Meta Business Suite account linked to your Instagram Business account.
  • A Meta Developer account at developers.facebook.com.
  • A Meta App created with the Instagram use case enabled.
  • The following values ready from your Meta App dashboard:
    • Account ID (the App ID)
    • App Secret
    • Access Token (a long-lived token generated for your Instagram Business account)

Tip: You can download the full Meta Developer setup guide from the qlar documentation resources. The guide contains annotated screenshots for each configuration screen in Meta's dashboard.

Step 1 — Open Channel Settings

  1. Open the CMS dashboard and select the agent you want to connect.
  2. In the left sidebar, click Channel.
  3. Click the Instagram tab.

Note: Unlike WhatsApp, Instagram supports only one configuration. There are no separate Published and Draft tabs — all users interact with the same Instagram Business account.

Step 2 — Enter Your Instagram Username

A setup wizard appears when no Instagram account is connected yet.

  1. In the Instagram Account Username field, enter your Instagram Business account username without the @ symbol. For example: mybrand_official.
  2. Click Next.

Note: The username you enter here is used as an identifier inside qlar. Make sure it matches the actual Instagram Business account you will link in the Meta Developer dashboard.

Step 3 — Confirm Meta Developer Setup

The next screen shows a checklist of Meta Developer prerequisites you must complete before qlar can receive Instagram messages. Work through each item in order:

  1. Create a Meta Developer account and set up a new app using the Instagram use case, then connect your Instagram Business account.
  2. Go to Roles, add an Instagram Tester and your business account, then accept the tester invitation from your Instagram account.
  3. Return to the app use case settings, configure the required permissions, and obtain the necessary credentials — Account ID, App Secret, and Access Token.
  4. Register your Webhook Callback URL in the Meta App and configure it using your Verify Token.
  5. Ensure your app is in Published mode to receive messages — this requires completing the App Review process in the Meta Developer dashboard.
  6. Once published, test the integration by sending a direct message to your Instagram account.

After completing all six steps, check the box "Yes, I have completed the Meta Developer setup" and click Next.

Warning: If your Meta App is not in Published mode, Meta will not forward any DMs to qlar. App Review is mandatory. Complete it before expecting live messages to arrive.

Step 4 — Enter Your Credentials

The wizard closes and the full configuration form loads. Fill in the following fields:

  1. Account ID — Enter the App ID from your Meta App.

    Tip: Click the info icon (ⓘ) next to the Account ID field for a guide image. The Account ID is found in the Generate Access Token section of the Instagram use case inside your Meta App.

  2. App Secret — Enter the App Secret for your Meta App. The field is masked by default; click the eye icon to reveal it.

    Tip: Click the info icon next to the App Secret field for a guide image. The App Secret is found in the first section of the Instagram Business Use Case settings in your Meta App.

  3. Access Token — Enter the long-lived access token you generated for your Instagram Business account.

    Tip: Click the info icon next to the Access Token field for a guide image showing where to copy the generated token in Meta's UI.

Step 5 — Configure Webhook in Meta App Dashboard

qlar needs Meta to forward incoming Instagram DMs to qlar's servers. This is done through a webhook.

  1. In the qlar form, locate the Webhook Secret field. Click Regenerate to create a new secret, then copy it.
  2. Below the secret, qlar displays your Webhook URL in a code block. Copy that URL.
    • The URL follows the format: https://<your-qlar-domain>/Instagram/Webhook/<your-instagram-username>
  3. Go back to your Meta App dashboard → Instagram → Configuration → Webhooks.
  4. Click Edit and fill in:
    • Callback URL — Paste the Webhook URL from qlar.
    • Verify Token — Paste the Webhook Secret from qlar.
  5. Click Verify and Save. Meta sends a verification request to qlar. The form confirms success if the token matches.
  6. Under Webhook Fields, enable at least messages so qlar receives incoming DMs.

Warning: Do not share the Webhook Secret publicly. If it is compromised, click Regenerate in qlar and update the Verify Token in Meta App immediately.

Step 6 — Save and Verify

Click the Save button at the bottom of the form.

To verify the connection is working:

  1. Send a test direct message to your Instagram Business account from a separate Instagram account.
  2. The message should appear in your agent's conversation history in the CMS dashboard.
  3. Your agent should respond automatically based on its configuration.

Tip: If messages are not arriving, check that: (1) the Webhook URL and Verify Token match exactly between qlar and Meta App, (2) the messages webhook field is subscribed, and (3) your Meta App is in Published mode.

What's Next

PreviousQontak
NextAutomate with Escalation