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.

You don't need a Meta developer account or any technical setup. You sign in with the Facebook account that manages your Instagram, grant access, and the portal collects the credentials and connects the webhook for you.

Want to enter credentials yourself?

This guide uses Login with Meta, the simplest path. If you'd rather bring your own Meta app and paste credentials by hand — or the Login with Meta button is disabled with the message "Meta App ID and App Secret are not configured on the server" — turn on Advanced mode and follow Instagram (advanced setup) instead.

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​

Instagram messaging through the API needs your account set up in a specific way. If you've never done this, it takes a few minutes in the Instagram and Facebook apps:

  • An Instagram professional account (Business or Creator). Personal accounts are not supported by Meta's API. In the Instagram app, you can switch under Settings > Account type and tools.
  • A Facebook Page linked to the Instagram account. The sign-in needs this link to find your account. Link them in the Instagram app (Settings > under your account, connect a Facebook Page) or in the Facebook Page settings.
  • Message access turned on for the API: in the Instagram app, Settings > Privacy > Messages > Allow Access to Messages. Without this, no messages reach the channel.
  • The Facebook account that manages the Page, to sign in with.
  • An account in the portal with permission to edit settings.

You do not need to create a Meta developer app, generate tokens, or configure webhooks — the portal handles all of that.

Connect Instagram​

Open the connector and start sign-in​

  1. Go to Settings > Channels, select Instagram in the list, and click Add +. The New connector panel opens on the right.
  2. Leave the Advanced mode switch (top-right of the panel) off. Optionally type a Name and Description — if you leave Name empty, the portal fills in a suggested name (like Instagram: acme.support) after sign-in.
  3. Click Login with Meta. A window titled Facebook Login for Business opens.

Complete the Meta sign-up​

Sign in with the Facebook account that manages your Page, then follow the screens. Meta walks you through it step by step:

  1. Continue as yourself. Confirm the Facebook account you're signed in with and click Continue. (To use a different account, click Log in to another account.)
  2. Start the Instagram setup. On Connect to Instagram, read the three steps — log in to Instagram, connect it to a Facebook Page, and allow messaging permissions — and click Get started.
  3. Log in to Instagram. Sign in with your Instagram username and password (or pick your account if you're already signed in). If your account is still personal, Meta switches it to a professional account in this step.
  4. Choose the business. On Choose the Businesses you want … to access, leave Opt in to current Businesses only selected, tick the business that owns your Page, and click Continue.
  5. Choose the Page. On Choose the Pages you want … to access, tick the Facebook Page linked to your Instagram account, and click Continue.
  6. Choose the Instagram account. On Choose the Instagram accounts you want … to access, tick the Instagram account you want the agent to answer for, and click Continue.
  7. Review and save. On Review … access request, check the access being granted — messages, profile, Page, and webhooks — and click Save.
  8. Finish. Meta confirms the connection. Click Got it to close the window.

Meta may show the asset screens (business, Page, Instagram account) in a slightly different order.

Finish in the portal​

  1. The window closes and the portal reads the Instagram business account linked to your Page, connects the webhook, fills in the credentials, and saves the connection — under the Name you entered, or a suggested name like Instagram: acme.support if you left it empty. You can rename it later by editing the connection.
  2. Select the new connection in the list and click Start in the panel header. The status dot turns purple (STARTING), then green (RUNNING).

For the general mechanics of the screen — status dots, Logs, editing credentials, stopping and restarting — see the Channels overview.

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​

  • Sign-in fails with "No Instagram Business Account is linked to this Facebook page". The Page you selected has no Instagram account linked. Link your Instagram business account to that Page, then sign in again — or sign in again and select the correct Page.
  • The channel is RUNNING but the agent never receives messages. Check the Instagram side: Allow Access to Messages is enabled in the Instagram app settings, the account is a professional account, and the Facebook Page is still linked to it.
  • 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.
  • The channel goes to ERROR on Start. The access token saved during sign-in has expired or been revoked. Open the connection and reconnect with Login with Meta, then Start.
  • The Login with Meta button is disabled. The deployment has no shared Meta app. Use Instagram (advanced setup) with your own Meta app.
  • Instagram (advanced setup) — connect with your own Meta app by entering credentials manually
  • 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?