Skip to content
SynapsAI Docs

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

Section titled “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.

Setup

Section titled “Setup”

1. Enable the extension

Section titled “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

Section titled “2. Enter your credentials”
FieldDescription
Page Access TokenThe long-lived token from your Meta Developer App. This token is encrypted and stored securely — it will appear masked after saving.
Instagram Account IDYour 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

Section titled “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.

4. Test the connection

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Troubleshooting”
ProblemSolution
Messages not arrivingVerify the webhook URL is correctly configured in your Meta Developer App. Check that the messages subscription is active.
Agent not respondingConfirm the extension is enabled (green status on the Extensions page). Check that your Page Access Token is valid and has not expired.
”Token expired” errorsGenerate a new long-lived Page Access Token from Meta and update it in the extension settings.

Next steps

Section titled “Next steps”