Adapter request: Instagram Direct Messages (@chat-adapter/instagram)

[ivandujaut]

Platform name

Instagram (Direct Messages)

Adapter type

Platform adapter (chat platform integration)

Platform API documentation

https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/messaging-api/

Use case

Opening a dedicated issue as suggested in #122, linked from #157.

In Latin America, Instagram DM is not a social channel that businesses also happen to answer. For a large share of small and mid-sized businesses, it is the storefront.

Per the NubeCommerce Argentina 2026 report, Instagram is the top sales channel after a brand's own online store, accounting for 82.6% of SMB sales and 68.2% of large-brand sales. Instagram has 30.5M active users in Argentina, in a country of ~46M people. The pattern repeats across the region: the buying conversation starts on a post and moves to a DM.

Chat SDK already covers the channels where Western B2B software lives (Slack, Teams, Discord) and, with the WhatsApp adapter, the dominant support channel in much of the world. Instagram DM is the missing half of the LATAM commerce conversation. A team building an agent for an Argentine, Brazilian, Mexican or Colombian merchant today can serve WhatsApp with a first-party adapter, but has to add a paid aggregator to reach the channel where most of their sales conversations start.

Concretely this unlocks: order status and shipping questions answered in the DM where the customer asked, product availability off a story reply, and lead qualification before handing off to a human — with the same bot logic already written for the other adapters.

Why this is a low-risk adapter to add: Instagram Messaging runs on the same Meta Messaging Platform as Facebook Messenger — same Graph API host, same webhook envelope shape, same 24-hour messaging window, same quick-reply and attachment primitives. @chat-adapter/messenger is therefore a near-complete reference implementation, not just a stylistic guide.

Proposed API

Consistent with the existing Meta-family adapters:

import { Chat } from "chat";
import { createInstagramAdapter } from "@chat-adapter/instagram";

const bot = new Chat({
  userName: "mystore",
  adapters: {
    instagram: createInstagramAdapter(),
  },
  state: createRedisState(),
});

bot.onDirectMessage(async (thread, message) => {
  await thread.subscribe();
  await thread.post(`Thanks for reaching out! You said: ${message.text}`);
});

Environment variables

Variable	Required	Purpose
INSTAGRAM_ACCESS_TOKEN	yes	Instagram User access token for the professional account
INSTAGRAM_APP_SECRET	yes	Verifying X-Hub-Signature-256 on inbound webhooks
INSTAGRAM_VERIFY_TOKEN	yes	Webhook subscription handshake
INSTAGRAM_ACCOUNT_ID	yes	Instagram professional account ID (thread/channel scoping)
INSTAGRAM_API_VERSION	no	Graph API version override (pinned by default, as Messenger does with v21.0)

Webhook wiring follows the existing convention: bot.webhooks.instagram mounted on the app's HTTP route.

Capability matrix

Capability	Support	Notes
Receive DMs	✅	messages webhook field
Send text	✅	Send API
Attachments (image, video, audio)	✅	URL-based and media-ID based
Quick replies	✅	Maps to Actions / Button in the card layer
Typing indicator	✅	sender_action: typing_on, same as Messenger
Reactions	✅ (receive)	Instagram surfaces message reactions on webhooks — one place Instagram can do more than the Messenger adapter, which throws AdapterUnsupportedError here
Story replies / mentions	✅ (receive)	Distinct webhook payload; proposal is to normalize as a Message with raw preserved
Edit message	❌	Not supported by the platform, mirrors Messenger
Threads	⚠️	Instagram DMs are a flat per-user conversation, not threaded — same model the Messenger adapter already uses
Modals	❌	No platform equivalent

What is genuinely Instagram-specific (and why this warrants its own package rather than a flag on @chat-adapter/messenger):

1. Identity and scoping — Instagram-scoped IDs (IGSID) rather than Page-scoped IDs, and an Instagram professional account rather than a Facebook Page. ID encoding/decoding differs.
2. Permission scope — instagram_business_manage_messages, obtained through Instagram Login rather than the Facebook Login flow Messenger uses.
3. Narrower message-tag support — Messenger has CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE; on Instagram HUMAN_AGENT is the reliable one (extends the window to 7 days). The adapter should surface a typed error when a send falls outside the window rather than letting a raw Graph error bubble up.
4. Rate limits — 200 calls/hour per Instagram account, tighter than the Messenger surface. Warrants mapping to AdapterRateLimitError with a retry hint.
5. Story-reply and mention payloads, which have no Messenger equivalent.

Constraints worth stating up front, rather than having them surface in review:

• 24-hour messaging window. A business can only reply within 24 hours of the user's last inbound message; each inbound message resets it. HUMAN_AGENT extends to 7 days but is audited by Meta. This is a platform rule, not an adapter limitation, but the adapter should fail loudly and typed rather than silently.
• App Review required for production. Development mode works against accounts with a role on the app, which is enough to build and test.
• Business or Creator account required. Personal Instagram accounts have no DM API access.

Existing community work

zernio (in the adapter directory) reaches Instagram DMs, but through a third-party aggregator requiring its own account, API key and pricing. There is no native adapter talking to Meta's Graph API directly.

Related: #122 (closed, asked for a dedicated proposal), #157.

Contribution

• I am willing to help implement and maintain this adapter

Additional context

My plan, if this direction sounds right:

1. Land this proposal and get direction on whether this belongs as a first-party adapter in the repo or as a community package.
2. Build against a test Instagram professional account in development mode.
3. Follow docs/contributing/building.mdx, testing.mdx and documenting.mdx, mirroring the structure and test depth of @chat-adapter/messenger.

Happy to adjust the API shape before writing code if maintainers prefer a different surface.