Docs/Channels/Instagram DM

Instagram DM

Instagram integration uses Meta's official Graph API. The agent receives DMs and story replies on connected Business or Creator accounts and responds through the Send API. We do not use unofficial libraries.

Requirements

Instagram Business or Creator account (not personal).
The Instagram account must be connected to a Facebook Page. Meta requires this — the Send API uses page credentials.
You are an admin of the Facebook Page.

App Review status matters. Until Meta App Review is approved for the platform, only the platform's own Facebook Page can receive DMs through Neofir. Self-serve onboarding for other tenants is gated on Live Mode approval. See Status.

Connect

Go to /dashboard/settings → Integrări → Instagram.
Click Connect Instagram. You are redirected to Meta's OAuth.
Grant instagram_basic, instagram_manage_messages, pages_show_list, pages_messaging, and pages_read_engagement.
Choose which Facebook Page (and connected IG account) to enable. Neofir subscribes the page to the messaging webhook.
Done. Your next DM is processed by the agent.

Webhook

Meta sends DM events to POST /v1/webhooks/instagram. The route verifies the request signature against your App Secret (X-Hub-Signature-256), looks up the org by recipient page id, and dispatches the message into the channel-agnostic pipeline.

Verification challenge: GET /v1/webhooks/instagram?hub.mode=subscribe&hub.verify_token=...&hub.challenge=... returns the challenge string when the token matches IG_VERIFY_TOKEN.

Deduplication

Meta retries webhooks aggressively (sometimes 5+ times for one event). Each incoming message carries a Meta-side mid; the platform stores it and drops duplicates within a 24-hour window. Duplicate dispatch would double-count quota and could double-reply.

Story replies

When a user replies to your story, Meta delivers the reply as a normal DM with the story metadata attached. The agent handles it as a regular message — the personality decides whether to acknowledge the story context.

Phone collection

On IG the visitor's identifier is their IG handle. The booking flow sets phone_optional: true in the visitor state — the agent does not insist on a phone number because the DM channel itself supports reminders.

Required env vars

Variable	Purpose
`META_APP_ID`	OAuth client id.
`META_APP_SECRET`	OAuth client secret + webhook signature verification.
`IG_VERIFY_TOKEN`	Meta webhook verification token (you set this, it must match in Meta dashboard).
`META_OAUTH_REDIRECT_URI`	OAuth callback (must match the Meta dashboard).
`ENCRYPTION_KEY`	32-byte key for at-rest encryption of page access tokens.

Limits

Reply window: Meta's policy gives you 24 hours after the user's last message to send a non-template reply. After that you need a Message Template (not yet supported in Neofir).
Rate limits: Meta's Calls Per Page headroom; for typical small-business volume you are nowhere near the cap.

Testing in Dev Mode

Before Live Mode, only users you add as testers (under App Roles → Roles in the Meta dashboard) can interact with your app. Add your own IG account as a tester and DM your connected page to exercise the full path.