Connect an Instagram professional account to your agent. People send your account a DM, and your agent answers with the same knowledge, guardrails, history, and message limits as every other channel.
For example, a clothing shop connects its Instagram account. A follower sees a new jacket in a post and sends a DM: "Is this available in size M?". The agent answers in Instagram with what the shop's knowledge says.
Instagram is available for public agents only. An Instagram sender is not signed in to Chatvia, so a protected agent cannot answer there. To make an agent public, open Security → Identity and turn on Make agent public. See Messaging channels for what all channels have in common.
Setup has two parts:
- Once per install: the person who runs your Chatvia server sets up one Meta app in the admin panel. Every workspace on the install connects through it.
- Per agent: someone in the workspace clicks Connect with Facebook and picks an Instagram account. Nobody pastes tokens or secrets.
Until the first part is done, the Instagram card on the agent's Channels page is greyed out and says "Not set up on this server".
Before you start
The workspace needs:
- An Instagram professional account (business or creator). You can switch a personal account in the Instagram app under Settings → Account type and tools.
- A Facebook Page linked to that Instagram account. Chatvia finds the account through the Page.
For the server admin: set up the Meta app
You do this once. You need a Meta developer account (developers.facebook.com) and access to the Chatvia admin panel.
Step 1: Create a Meta app
Go to developers.facebook.com/apps and click Create App. Pick a use case that lets you manage messages for Instagram accounts linked to Facebook Pages, and finish the wizard.
Step 2: Enter the app in Chatvia
Open the admin panel and go to Settings → Channels → Instagram (see Channels settings). Fill in:
- App ID and App secret: from App settings → Basic in your Meta app.
- Webhook verify token: any random string. You paste the same value in Meta in Step 4.
Under the advanced fields you can also set a Login configuration ID (a Facebook Login for Business configuration). Without it, Chatvia asks for the permissions the classic way.
Save. The card shows two addresses:
- OAuth redirect:
{APP_URL}/my/channels/instagram/oauth/callback. - Webhook callback URL:
{APP_URL}/instagram/webhook.
Step 3: Allow the OAuth redirect
In your Meta app's Facebook Login settings, add the OAuth redirect to the valid OAuth redirect URIs.
Step 4: Point the webhook at Chatvia
In your Meta app's Instagram webhook settings, paste the Webhook callback URL and the Webhook verify token, and save. Then subscribe the webhook to the messages field.
Meta verifies the URL instantly. If it shows an error, check that you pasted the full callback URL with no extra spaces, and the same verify token as in Chatvia.
App mode and testers
While the Meta app is in Development mode, only accounts with a role on the app (or added as testers) can use it. Switch the app to Live mode (this needs Meta's app review for instagram_manage_messages) to answer everyone.
For the workspace: connect an account
Step 1: Connect with Facebook
In Chatvia, open your agent, click Channels in the left menu, and click Setup on the Instagram card. Click Connect with Facebook.
Your browser goes to Facebook. Sign in and allow access, keeping every permission ticked. You then come back to the Channels page with the Instagram panel open. It lists the Instagram accounts linked to your Pages. Pick one under Choose an Instagram account and click Connect this account. The card then shows the account's @username.
Step 2: Allow message access in the Instagram app
On the phone, in the Instagram app for your professional account, go to Settings → Messages and story replies → Message controls → Connected tools and turn on Allow access to messages. Without this switch, Meta does not deliver DMs to any tool.
Step 3: Test it
Send a DM to your account from another Instagram account. Your agent shows a typing indicator while it thinks and replies. The conversation appears in your agent's Chatlog with an Instagram badge.
To stop, click Disconnect on the card.
Troubleshooting
| Problem | Likely cause |
|---|---|
| The Instagram card is greyed out | The admin has not set up the Instagram Meta app in Settings → Channels. |
| "No Instagram professional accounts came back." | The Instagram account is not a professional account, it is not linked to a Facebook Page you manage, or a permission was unticked on the Facebook screen. |
| "Facebook sign-in was cancelled. Please try again." | You closed or declined the Facebook screen. Connect again. |
| "That account selection expired. Please reconnect." | Chatvia no longer has the list Facebook sent back, for example because you signed out in between. Connect again. |
| "That Instagram account is already connected to another agent." | Disconnect it from the other agent first. |
| Webhook verification fails | Wrong verify token, or the callback URL was not copied fully. |
| No reply to DMs | The webhook is not subscribed to the messages field, or message access is off in the Instagram app (Step 2). |
| Strangers get no reply | The Meta app is still in Development mode. Only people with a role on the app get replies. |
| "This assistant isn't available on Instagram right now." | The agent was made protected after connecting. Make it public again on Security → Identity. |
How replies behave
- Replies are sent as one message (or several, if longer than Instagram's 1,000-character limit).
- Instagram shows no text formatting, so the agent's Markdown is stripped to readable plain text: lists keep their bullets and numbers, and links are sent as their text with the URL after it, which Instagram makes tappable.
- Chatvia only replies to incoming messages, so replies always fall inside Instagram's 24-hour response window.
- Each person has one ongoing conversation with the agent, so it remembers earlier messages.
- Only text DMs are answered. Photos, voice messages, story replies without text, reactions and stickers are ignored.
- One Instagram account can power one agent at a time. Disconnect stops the agent from answering. Past conversations stay in your Chatlog.