Connect to Instagram
Open in CMSThis tutorial walks you through connecting your qlar agent to an Instagram Business account using Meta Cloud (Meta's Instagram Messaging API). After completing setup, people can send direct messages to your Instagram Business account and receive AI-powered responses from your agent.
The example connects Atlas, Kirana Group's operations assistant, to Kirana's Instagram Business account kirana.group.example, so staff and site partners who message that account get answers from Atlas.
Personal agents too. A personal agent can be connected to Instagram. Anyone who messages the account gets answers given on your behalf.
Before you start
- Your agent answers well in Preview and has been published at least once. See Preview and Publish Changes. The Published Configuration tab needs a published agent.
- If you already connected WhatsApp, the Published and Draft idea works the same way here. See Connect to WhatsApp.
From Meta, 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.
- Access to these values in the Meta Developer Console:
- Account ID
- App Secret
- Access Token (a long-lived token generated for your Instagram Business account)
Tip: The configuration screen has a link to the Instagram channel setup guide (a PDF with annotated screenshots of Meta's dashboard). See Step 4.
Step 1: Open Channel Settings
- Open the CMS dashboard and select the agent you want to connect.
- In the left sidebar, open Channels β Instagram.
- Choose which configuration to set up: Published Configuration (for live users) or Draft Configuration (optional, for testing with a separate account). Click the corresponding tab.
Note: Like WhatsApp, each tab is configured independently. The Draft Configuration is optional; you can leave it empty if you do not need a separate test account.
Step 2: Enter your Instagram username
The Connect Instagram wizard appears when no Instagram account is connected yet.
- In the Instagram Account Username field, enter your Instagram Business account username without the
@symbol. For Kirana that iskirana.group.example. - Click Next.

Note: The username identifies the account inside qlar and becomes part of the webhook URL. Make sure it matches the Instagram Business account you link in the Meta Developer dashboard. It cannot be changed later.
Step 3: Confirm the Meta Developer setup
The Meta Developer Setup screen lists the steps you must complete in the Meta Developer Console before qlar can receive Instagram messages:
- Create a Meta Developer account and set up a new app using the Instagram use case, then connect your Instagram Business account.
- Go to Roles, add an Instagram Tester and your business account, then accept the tester invitation from your Instagram account.
- Return to the app use case settings, configure the required permissions, and obtain the necessary credentials (Account ID, App Secret, and Access Token).
- Register your Webhook Callback URL in the Meta App and configure it using your Verify Token. You get both values from qlar in Step 5.
- Ensure your app is in Published mode to receive messages; this requires completing the App Review process in the Meta Developer dashboard.
- Once published, test the integration by sending a direct message to your Instagram account.

You can work through the Meta steps now or come back to them after the configuration exists, because steps 4 to 6 need values that qlar shows only on the configuration screen.
- Tick Yes, I have completed the Meta Developer setup. Next stays disabled until you do. Back returns to the username.
- Click Next. The CMS asks Are you sure you want to add this messenger?
- Click Yes. The configuration is created and the configuration screen opens.
Warning: If your Meta App is not in Published mode, Meta does not forward any DMs to qlar. App Review is mandatory. Complete it before expecting live messages to arrive.
Step 4: Enter your credentials
The configuration screen shows the Meta Cloud badge, a Channel on switch and a Delete button at the top. The integration stays inactive until all inputs are complete.

In the API Credentials card, fill in the values from your Meta App. Each field has an info icon (β) that shows where to find the value, with a guide image:
- Account ID: in the Generate Access Token section of your Instagram account, under your app's Instagram use case settings.
- App Secret: in the first section of the Instagram Business Use Case settings. The field is masked; click the eye icon to reveal it.
- Access Token: the long-lived token you generate in the Generate Access Token section.
In the Additional Context card, describe which physical branch or region this Instagram account represents, so the agent can disambiguate location-specific questions for this account only. For Kirana, for example: This is Kirana Group's head-office account in Jakarta. It covers all offices and project sites.
Under Session Management, keep the defaults unless you have a reason to change them: Ask user to end session on, Delay Before Ask More 300 seconds, Delay Before End Session 600 seconds.
Need more help with Meta's screens? The banner Need further guidance? Refer to the documentation available here opens the Instagram channel setup guide.
Step 5: Configure the webhook in the Meta App dashboard
qlar needs Meta to forward incoming Instagram DMs to qlar's servers. This is done through a webhook.
- In the Connection card, the Webhook Secret is already filled in. Click the eye icon to show it and the copy button to copy it. The refresh icon next to the label generates a new secret; click Update afterwards to save it.
- Below the fields, qlar shows a text block with your Account Username and the Webhook Configuration URL, in the format
https://api.qlar.ai/messenger/api/Instagram/Webhook/<username>. For Kirana that ishttps://api.qlar.ai/messenger/api/Instagram/Webhook/kirana.group.example. Use the copy button in the corner of the block to copy it. - Go to your Meta App dashboard β Instagram β Configuration β Webhooks.
- Click Edit and fill in:
- Callback URL: paste the Webhook Configuration URL from qlar.
- Verify Token: paste the Webhook Secret from qlar.
- Click Verify and Save. Meta sends a verification request to qlar.
- Under Webhook Fields, subscribe to at least messages so qlar receives incoming DMs.
Warning: Do not share the Webhook Secret publicly. If it is compromised, regenerate it in qlar, click Update, and update the Verify Token in your Meta App immediately.
Step 6: Update and publish
- Click Update at the bottom of the form. The CMS asks Are you sure you want to update this Instagram account? Click Yes.
- A message confirms Instagram account updated successfully.
- Saving marks your agent as having unpublished changes, so the Publish button appears at the top of the CMS. Click Publish so the connection is synced to the live version of your agent.
Cancel discards your unsaved changes on this screen and restores the saved values.
Add more Instagram accounts
If your organization has several Instagram accounts, for example one per region, they can share the webhook you configured above. Under Other Instagram Accounts, click Add Instagram account (or the add-account button next to Account Username). The Add Another Instagram Account dialog asks for:
- Instagram Username: the handle exactly as it appears on the Instagram profile, without
@. - Account ID and Access Token for that account.
- Additional Context (optional): the branch or region this account represents.
Click Add Account. Each added account is listed under Other Instagram Accounts, where you manage its credentials.
Check the result
To verify the connection is working:
- From a separate Instagram account, send a test direct message to your Instagram Business account, for example
Who signs the permit for work above two metres? - The message should appear in your agent's conversation history in the CMS dashboard.
- Your agent should respond automatically, with the same kind of answer it gives in Preview.
Tip: If messages are not arriving, check that: (1) the switch shows Channel on, (2) every field in API Credentials is filled in and saved, (3) the Callback URL and Verify Token match exactly between qlar and your Meta App, (4) the messages webhook field is subscribed, and (5) your Meta App is in Published mode.
Next steps
- Next in the journey: Manage Who Can Use and Build, to decide who may chat with your agent and who may help configure it.
- Connect other channels: see Connect to WhatsApp or Embed Chat on Your Website.
- Hand difficult conversations to a person: see Hand Off to a Human.