Instagram

The Instagram extension lets your AI agent receive and respond to messages on Instagram Direct. Users message your business account on Instagram and your agent replies automatically — with optional handoff to a human operator when needed.

Prerequisites

Before setting up the Instagram extension, make sure you have:

• A Facebook Business Page linked to your Instagram Professional account.
• A Meta Developer App with the Instagram Messaging API enabled.
• A Page Access Token with the instagram_manage_messages and pages_messaging permissions.

Tip

If you don’t have a Meta Developer App yet, go to developers.facebook.com and create one. Select “Business” as the app type.

Setup

1. Enable the extension

1. Navigate to your agent’s Extensions page.
2. In the Explore tab, find Instagram under the Chat category.
3. Click the card to open the configuration page.

2. Enter your credentials

Field	Description
Page Access Token	The long-lived token from your Meta Developer App. This token is encrypted and stored securely — it will appear masked after saving.
Instagram Account ID	Your Instagram Professional account ID (found in the Meta Business Suite or via the Instagram Graph API).

Click Save to store your credentials.

3. Configure the webhook

After saving, the extension page displays a Webhook URL unique to your agent:

https://api.synapsai.app/v1/{accountId}/instagram/{agentKey}

Copy this URL and configure it in your Meta Developer App:

1. In your Meta Developer App, go to Instagram > Settings.
2. Under Webhooks, click Add Callback URL.
3. Paste the webhook URL provided by SynapsAI.
4. Set the Verify Token to match your configuration.
5. Subscribe to the messages webhook field.

Caution

The webhook URL is specific to your agent. If you have multiple agents, each one has its own URL.

4. Test the connection

Send a Direct Message to your Instagram account from another account. You should see the conversation appear in the Conversations page within a few seconds.

How it works

Once configured, the flow is:

1. A user sends a DM to your Instagram business account.
2. Instagram delivers the message to SynapsAI via the webhook.
3. Your AI agent processes the message, consults the knowledge base, and generates a response.
4. The response is sent back to the user on Instagram.

The user stays in Instagram the entire time — no redirects, no external links.

Features

• Automatic replies — your agent responds to Instagram DMs using your knowledge base, FAQ, and system prompt.
• Rich conversation history — all Instagram conversations appear in the Conversations page with the INSTAGRAM origin badge.
• Contact tracking — Instagram users are automatically created as contacts with their Instagram identity linked.
• Operator handoff — when the agent can’t help, the conversation can be transferred to a human operator. The operator responds from the dashboard and the user sees the reply in Instagram.
• Cross-channel view — if a contact also interacts via WhatsApp or Live Chat, you can see all their conversations in one place using the contact filter.

Security

• Your Page Access Token is encrypted at rest and never exposed in the UI after saving. The console shows masked bullet points instead.
• If you need to rotate the token, enter the new token and save — the old one is replaced immediately.

Troubleshooting

Problem	Solution
Messages not arriving	Verify the webhook URL is correctly configured in your Meta Developer App. Check that the messages subscription is active.
Agent not responding	Confirm the extension is enabled (green status on the Extensions page). Check that your Page Access Token is valid and has not expired.
”Token expired” errors	Generate a new long-lived Page Access Token from Meta and update it in the extension settings.

Next steps

• Configure behavior — customize how your agent responds on Instagram.
• Operator Handoff — set up human takeover for complex conversations.
• Conversations — review Instagram conversation history.
• WhatsApp — add another messaging channel.