Skip to main content

Instagram

The Instagram channel connects a Flametree agent to the direct messages of an Instagram business account, using Meta's Instagram API. Customers write to your account in Instagram, the agent answers, and every conversation appears in Sessions like any other channel.

Use this channel to:

  • Answer direct messages to your Instagram business account around the clock.
  • Handle inbound text, images, and voice messages — voice is transcribed when speech-to-text is configured for the agent. The agent replies with text.

Reactions, story mentions, story replies, and video attachments are not processed, and the channel is not available for outbound campaigns — conversations start when a customer messages your account.

Before you start​

  • An Instagram business account. Personal accounts are not supported by Meta's API.
  • A Facebook Page linked to the Instagram account. The Meta sign-in flow needs the link to find your account; link them in the Facebook Page settings if you have not done so.
  • In the Instagram app, allow message access for the API: Settings > Privacy > Messages > Allow Access to Messages.
  • An account in the portal with permission to edit settings.

There are two ways to create the connection, controlled by the Advanced mode switch on the connection form:

  • Sign in with Meta (switch off, the default) — sign in to your Meta account and let the portal collect the credentials. Fastest when your portal installation has a Meta app configured.
  • Advanced mode (switch on) — paste credentials from your own Meta app by hand and subscribe the webhook yourself.

If the switch is disabled with the message "Meta App ID and App Secret are not configured on the server", use Advanced mode. See the Channels overview for how the switch works on Meta channels.

Connect Instagram​

Sign in with Meta​

  1. Go to Settings > Channels, select Instagram in the list, and click Add. The New connector form opens on the right.
  2. Leave the Advanced mode switch off and click Login with Meta.
  3. Sign in to the Meta account that manages your Facebook Page and grant access. The portal finds the Facebook Page, reads the Instagram business account linked to it, fills in the credentials, and saves the connection under a suggested name.
  4. Select the new connection in the list and click Start. The status dot turns purple (STARTING), then green (RUNNING).

If the sign-in ends with No Instagram Business Account is linked to this Facebook page, link the Instagram account to the Page in the Facebook Page settings and try again.

Enter credentials manually (Advanced mode)​

Set up the Meta side​

Create the credentials in the Meta developer console — keep Meta's Instagram Platform documentation at hand for the console details:

  1. Go to developers.facebook.com and create a Meta app of the Business type (or open an existing one).
  2. Add the Instagram product to the app and generate an access token for your Instagram business account.
  3. From App Settings > Basic, note the App ID and App secret.
  4. Note the ID of your Instagram business account.

Create the connection​

  1. Go to Settings > Channels, select Instagram in the list, and click Add.

  2. Turn the Advanced mode switch on. The credential fields appear.

  3. Fill in the form:

    FieldRequiredDescription
    NameYesAn internal name shown across the portal.
    DescriptionNoInternal reference.
    Instagram IDYesThe ID of the Instagram business account.
    Access tokenYesThe access token generated in the Meta developer console. Stored as a secret and displayed masked.
    App IDNoThe ID of your Meta app. Leave it empty to use the Meta app configured on the server.
    App secretNoThe app secret from App Settings > Basic. The channel uses it to check the signature of incoming events. Leave it empty to use the Meta app configured on the server.
    Verify tokenYesAny value you make up yourself (for example, my_ig_webhook_2026). Works like a shared password — you enter the same value in the Meta app webhook settings.
    Registration delay, Registration countNoWebhook registration retry settings. Leave them empty — you subscribe the webhook in the Meta app dashboard instead (see below).

  4. Click Save.

  5. Click Start in the panel header. On startup the channel checks the account against the Instagram API — if the Instagram ID or Access token is wrong, the status turns red (ERROR); hover over the dot for the message and click Logs for details.

Subscribe the webhook in the Meta app​

The channel does not register its webhook with Meta automatically. Subscribe it in the Meta app dashboard so that messages reach the channel:

  1. Find the callback URL. In Settings > Channels, select the connection and expand Access Information — it shows an API Documentation link of the form https://<portal host>/channel/<connection ID>/docs. The callback URL is the same address with /docs replaced by /webhook.
  2. Make sure the channel is RUNNING — Meta calls the URL to verify it the moment you save the subscription.
  3. In the Meta app dashboard, open Webhooks, select Instagram, and edit the subscription. Enter the callback URL and, as the verify token, the exact value of the connection's Verify token field.
  4. Subscribe to the messages field.

Attach to an agent​

A running channel does nothing on its own — attach the connection to the agent that should answer the messages.

  1. Open AI Agents and select the agent.
  2. Find the Communication channels card and click Add.
  3. Pick Instagram from the dropdown and tick the checkbox next to your connection.
  4. Enable the Inbound switch so the agent answers incoming messages.
  5. Save the agent, then restart it (Stop agent, then Start agent).

After the restart, new direct messages to the account open sessions for this agent.

One account, one inbound agent

Only one agent should handle inbound traffic from an Instagram account — otherwise several agents would answer the same customer message. To put several inbound agents on Instagram, create a separate connection for each account.

Test the channel​

  1. From a different Instagram account (not the business account itself), send a direct message to your business profile.
  2. Check that the agent replies according to its instructions.
  3. Send a voice message — if speech-to-text is configured for the agent, a transcription appears in the conversation and the agent answers it.
  4. Open Sessions in the portal and confirm the conversation appears there with the Instagram channel icon.

Common issues​

  • The channel goes to ERROR on Start. The startup check against the Instagram API failed — the Instagram ID is wrong or the Access token is invalid or expired. Click Logs for the error message, fix the values (paste the new token over the masked value), click Save, then Start.
  • Meta cannot verify the callback URL. The verify token entered in the Meta app does not match the connection's Verify token field, the callback URL is wrong, or the channel was not RUNNING when Meta sent the verification request. Fix the mismatch and verify again.
  • The channel is RUNNING but the agent never receives messages. The webhook subscription is missing or incomplete — confirm the Meta app subscribes to the Instagram messages field with the correct callback URL. Also check the Meta side: Allow Access to Messages is enabled in the Instagram app settings, the Facebook Page is linked to the Instagram account, and the Meta app is in Live mode rather than Development mode.
  • Logs show signature verification failures. Events arrive from a Meta app whose secret does not match the connection's App secret. Make sure the App secret belongs to the same Meta app that delivers the webhooks.
  • Messages arrive but the agent stays silent. The connection is not attached to the agent, Inbound is off, or the agent was not restarted after attaching.
  • Reactions, story mentions, and story replies get no answer. Expected — the channel ignores these event types and only processes direct messages.
  • Voice messages get no reply. Configure a speech-to-text model for the agent so it can process audio.
  • Sign-in with Meta fails with "No Instagram Business Account is linked to this Facebook page". Link the Instagram business account to the Facebook Page in the Page settings, then sign in again.
  • Channels overview — create, start, stop, and monitor channel connections, including the Advanced mode switch for Meta channels
  • Facebook — connect Facebook Messenger for the same Meta business account
  • WhatsApp — connect the Meta WhatsApp Business API
  • Supported channels — capability comparison across channels
  • Sessions — monitor Instagram conversations

Was this article helpful?