All channels

Instagram Messaging

Connect an Instagram professional (business or creator) account so DMs are answered by your governed flow. Instagram messaging is part of Meta's Messenger Platform and requires the account to be linked to a Facebook Page. Channel key: instagram.

What you need

  • An Instagram professional account linked to a Facebook Page you manage.
  • A Meta app with the Messenger product and Instagram messaging enabled.
  • The Instagram account ID (IGID), a Page access token for the linked Page (with instagram_basic, instagram_manage_messages, pages_manage_metadata), and the App secret.
  • In Instagram: Settings → Privacy → Messages → Allow access to messages (connected tools) must be on.
  • App Review (instagram_manage_messages) and a published app before people without a role on the app can reach the bot.

Official documentation

Set up on Meta

  1. Link the Instagram account to your Facebook Page (Page → Settings → Linked accounts → Instagram) and switch it to a professional account.
  2. Create the app (type Business) and add the Messenger product; open Messenger → Instagram settings.
  3. Access token: under Access tokens add the Page linked to the Instagram account and Generate token; grant instagram_basic, instagram_manage_messages, pages_manage_metadata.
  4. Instagram account ID: Business Suite → Settings → Accounts → Instagram accounts, or call GET /me/accounts?fields=instagram_business_account with the token.
  5. App secret: App settings → Basic.
  6. Webhook: Webhooks → choose the Instagram object → Subscribe to this object: paste the Callback URL and Verify token from Tools Anatomy, then subscribe to messages (and messaging_postbacks if you use buttons). Also add the Instagram account under Instagram settings → Webhooks.
  7. Enable Allow access to messages in the Instagram app, publish the app and pass App Review to go public.

Connect in Tools Anatomy

  1. /channels → Messaging channels → Instagram Messaging → Connect.
  2. Fill in Instagram account ID, Page access token, App secret.
  3. Connect validates the token can read the account (GET /{ig_account_id}?fields=id,username) and shows the Callback URL
    • Verify token for the Meta webhook configuration. POSTs must carry a valid X-Hub-Signature-256 or are rejected with 401.

Identity we derive

Canonical key Source Notes
external_user_id <instagram_account_id>:<IGSID> IGSIDs are scoped to your account
channel instagram
display_name / phone_number / email — (only via profile API or user quick replies)

conversation_context.channel_account_id = your Instagram account ID. Thread = the sender's IGSID.

Limits

  • Replies are allowed within the 24-hour window after the person's last message (human-agent tags beyond that are not used).
  • Message text must be ≤ 1,000 bytes; replies are split accordingly.
  • Story replies/mentions, reactions, shares and media arrive as attachments or are ignored; the flow answers text-only.
  • Echoes of your own messages and read receipts are ignored; deliveries are deduplicated on message.mid.

Test it

In development mode, DM the account from an Instagram account whose Facebook user has a role on the app (add testers under App roles).

Troubleshooting

  • No webhooks arrive — the app must be published (even before App Review), the Instagram object must be subscribed, and Allow access to messages must be on in the Instagram app.
  • "platform rejected the credentials" — the token lacks instagram_manage_messages or is for a Page not linked to the account.
  • Replies fail after a day — the 24-hour window closed.