Skip to content
SquadOS SquadOS Docs

Instagram Direct (DM)

The Instagram Direct trigger connects an Instagram business account to your agent. From then on, DMs, story replies, and mentions that land in the account are answered automatically, using the prompt and tools you configured.

Requirements

Section titled “Requirements”
  • Instagram Business or Creator account. Personal accounts don’t work — convert it in the Instagram app under Settings -> Account -> Switch to professional account.
  • A Facebook Page linked to the Instagram account. Meta’s API requires this link even for business accounts managed straight from Instagram.
  • Permission to authorize: you must be an admin of the linked Facebook Page at the time of authorization.

Connecting

Section titled “Connecting”
  1. Open the agent in the admin panel.
  2. Go to Triggers.
  3. In the Instagram Direct card, click Connect Instagram.
  4. A popup opens with the Instagram/Meta login. Log in with the account that manages the business profile.
  5. Approve the requested permissions (send/read DMs, manage the business account).
  6. When the popup closes, the card shows Connected: @your_handle.

If the browser blocks the popup, allow popups for app.squados.io and try again.

How it works

Section titled “How it works”
  • Instagram fires a webhook into SquadOS every time a DM arrives.
  • SquadOS creates (or continues) a conversation per Instagram contact.
  • The agent processes the message using your prompt + tools + knowledge base and replies through the Graph API.
  • The reply lands in the user’s Direct inbox as if you had typed it.

The same Instagram account can be used at the same time by the Instagram Comments trigger — you authorize once, but the two triggers are independent.

Disconnecting

Section titled “Disconnecting”

In the same card, click Disconnect. SquadOS stops receiving webhooks for the account right away, and the integration is unsubscribed on Meta’s side too.

Token and renewal

Section titled “Token and renewal”

The Meta token is valid for 60 days and SquadOS renews it automatically before it expires. If renewal fails (for example, you revoked permissions on Facebook), the card shows a warning and you need to reconnect by clicking Connect Instagram again.

Limits and notes

Section titled “Limits and notes”
  • Meta enforces rate limits per business account. At very high volumes, messages may be delayed.
  • Instagram only delivers DMs via webhook for business accounts — personal accounts converted to business start receiving webhooks a few minutes after the conversion.
  • The agent cannot initiate a DM conversation — only reply to people who messaged first (Meta’s rule for Instagram Direct).
  • Instagram’s default reply window is 24h after the user’s last message. After that, replies require approved templates (not supported by SquadOS yet).

Common issues

Section titled “Common issues”
  • “Popup blocked”: allow popups for app.squados.io in your browser.
  • “Token expired”: automatic renewal failed. Click Connect Instagram again to re-authorize.
  • DMs don’t arrive: confirm the account is in Business or Creator mode with a linked Facebook Page. Allow a few minutes after connecting for the webhook to stabilize.
  • “Could not connect”: you don’t have admin permission on the linked Facebook Page. Ask the admin to connect, or get permission in Business Manager.