Instagram Direct Message (DM)

The Instagram Direct Message (DM) channel connects an Instagram Business or Creator account to an inbox. Each received message enters a SquadOS conversation and follows the selected destination: an agent or human support.

Before connecting

You need:

• an Instagram Business or Creator account; personal accounts are not accepted;
• access to sign in to that account and authorize the application;
• permission to create or change inboxes in SquadOS.

Authorization uses Instagram’s own login. A linked Facebook Page is not required. SquadOS requests access to the professional profile, messages, and comments because the same Meta connection serves Instagram Direct and Instagram Comments.

Connect the account

1. In the admin panel, open Inboxes.
2. Click Connect inbox.
3. Under Instagram, choose Instagram Direct.
4. Click Connect with Instagram. A separate window opens the Instagram login.
5. Sign in to the professional account and approve the requested permissions.
6. After the window closes, check Connected: @username. When Meta does not return the username, the card identifies the account as Instagram Business · ID ….
7. Click Continue, choose an active agent or Human support, set the Inbox name, and click Done.

If the browser does not open the authorization window, allow pop-ups for the admin panel domain and try again. Closing the window before completion cancels the connection and should not leave a new inbox in the list.

An account can be active in only one inbox for the same channel. Connecting the same account to another inbox deactivates the previous connection because of exclusivity; confirm the destination before completing the switch.

What happens to each message

Meta’s webhook identifies the recipient account and looks for an active Instagram Direct inbox with that identity. SquadOS then:

1. ignores copies of messages sent by the account itself;
2. identifies the contact by Instagram ID and creates or reuses the conversation;
3. records context when the message is a story reply or mention;
4. delivers the message to the configured agent or human queue;
5. sends the reply back through Instagram.

With an agent destination, the agent uses its prompt, linked knowledge bases, and enabled tools. With Human support, the message is stored without calling a model or consuming AI credits. Long agent or operator replies are automatically split into chunks of up to 1,000 characters for Instagram.

The channel is reactive: SquadOS replies to someone who initiated contact, but this inbox does not provide an action for starting a new DM.

Received attachments

In the currently audited code, the webhook recognizes that the DM contains an attachment but does not pass that attachment into the conversation. A photo, audio clip, or other file may arrive without usable content; a message made up only of the attachment may fail during processing. Ask the customer to send the information as text and report the case to support.

Human support and Meta’s window

In Conversations, use Claim to become responsible for the conversation and pause automatic replies. Messages typed by the operator are sent to Direct through the same channel.

The current delivery path uses Meta’s standard message, including for the operator. Therefore, treat 24 hours since the contact’s last message as the operational limit for both AI and human support. The runtime has technical support for the HUMAN_AGENT tag, but the product’s operator path does not apply it; do not promise the extended seven-day window. Outside the window, ask the contact to message the Instagram account again.

Check and renew the connection

Under Inboxes, open the row’s ⋮ menu and choose Settings. In the Connection block, a connected account may show:

• Instagram username or the ID used as its identity;
• Connected at;
• Token expires.

The token is stored with an expiry of up to 60 days. A daily routine attempts to renew connections that are close to expiry. Transient failures are recorded for another attempt; a failure classified as permanent deactivates the inbox with a token-expired reason.

When the list shows Disconnected and a Reconnect action, reauthorize the account through that action. Do not rely on the internal token-expired warning: in the audited code, the derived state prevents that specific warning from being displayed.

Disconnect or remove

Inside Settings → Connection, Disconnect attempts to cancel the Meta subscription and removes the inbox from the list:

• without conversations, the inbox is deleted;
• with conversations, the inbox is soft-deleted and its history preserves the source of those conversations;
• its credential is no longer available for new deliveries.

This is not a reversible pause. To use the account again after a voluntary disconnect, connect a new inbox. An inbox automatically deactivated because of a lost session, token, or exclusivity follows a different flow and may offer Reconnect while it remains in the list.

Quick diagnosis

• The pop-up does not open: allow pop-ups for the admin panel domain.
• The window was closed: click Connect with Instagram again and complete authorization.
• The inbox looks connected, but no DM arrives: send a DM from another account, confirm the identity shown under Settings, and contact support. The current flow can complete OAuth even when Meta does not return the routable ID or when the webhook subscription fails.
• The inbox looks disconnected: use Reconnect and authorize it again. If the row no longer exists, create a new inbox.
• The reply fails after hours without contact: the standard 24-hour window ended; ask the customer to send a new message.
• An image, audio clip, or file does not reach the agent: ask for the content as text; received attachments do not yet cross this channel’s pipeline.