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 images, Reels, posts, and Stories

Availability in Dev

The shared media flow was published in Dev on October 13, 2026. Video analysis and history recall were validated through the deployed API. Sharing from the Instagram app through to the agent’s reply still requires real validation; this delivery has not been published to production.

When Instagram provides an accessible URL, the channel identifies media from shared posts, Reels, and Stories and preserves the available caption or title. Images follow the agent’s configured visual processing. Audio follows the transcription flow. The agent also receives context for shares, Story replies, or mentions.

For videos, behavior depends on the model and the Multimodal configuration:

• if the conversation model accepts video and no preprocessing model is configured, it receives the video directly;
• otherwise, an active compatible auxiliary model analyzes the video and provides a description to the agent, keeping the conversation model;
• Don’t accept files also blocks videos and uses the configured rejection message.

Auxiliary analysis is saved with the message. In the conversation, you can play the video and open Description of … when analysis is available. Later questions can use this description from history without analyzing the same attachment again. Analysis cost is included in the reply charge; reusing a saved description does not make a new analysis call.

Received videos have a 25 MB limit. A missing, expired, or inaccessible URL prevents content recovery from the message type alone. In these cases, the channel records unavailability in the context; ask the person to send the image or video directly. Speech and sound coverage in the description depends on the auxiliary model.

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.
• A post, Reel, or Story appears unavailable: ask the person to send the image or video directly; Meta may not provide an accessible URL, or the content may have expired or been removed.
• The video is not analyzed: check that Files is enabled under Multimodal. When the conversation model does not accept video, analysis requires a compatible auxiliary model allowed by the organization. For files over 25 MB or slow processing, send a smaller video; for access failures, send the media again.
• The video does not play in the browser: check your connection and retry. If the format cannot be played, download the file to open it in another app.