Instagram Direct Messages (Addon)

Prerequisites

• Instagram Business or Creator account. Personal Instagram accounts cannot use the Messaging API — this is a Meta restriction.
• Facebook Page linked to the Instagram account. DMs are sent via the Page's access token. The Page-to-IG link is set up in Instagram's mobile app under Settings → Account → Linked Accounts.
• Meta App on developers.facebook.com. One-time admin setup (5 minutes), explained below.
• Addon installed. Upload the instagram-addon-v1.0.0.zip via Admin → Addons → Upload & Install → Activate.

Step 1 — Install the addon

1. Admin → Addons → Choose File → pick instagram-addon-v1.0.0.zip → Upload & Install.
2. Click Activate on the Instagram Direct Messages card. Migrations run (creates instagram_accounts table, adjusts the conversations channel column).
3. A new Settings button appears on the addon card. Click it to open the admin overview at /admin/addons/instagram/settings.

Step 2 — Create a Meta App (one-time, admin)

1. Go to developers.facebook.com and create a Business-type App.
2. Add the Instagram product. Request these permissions:
   • instagram_basic
   • instagram_manage_messages
   • pages_messaging
3. Open your MailTrixy admin overview at /admin/addons/instagram/settings. Copy the Webhook URL shown there (e.g. https://yourdomain.com/addons/instagram/webhook).
4. In Meta App Dashboard → Webhooks → Instagram → paste the Webhook URL as the Callback URL. Subscribe to the messages and messaging_postbacks fields.
5. Submit the app for Meta App Review. This typically takes 1–5 business days. Apps in “Development Mode” can only message accounts that have a role on the Meta App, so production use needs approval.

Step 3 — Workspace owner connects (per workspace)

Same WhatsApp-style flow:

1. User goes to Settings → Channels.
2. An Instagram card appears (only shown when the addon is active). Click Configure.
3. Paste the following values from Meta's Graph Explorer / App Dashboard:
   • Page ID — the Facebook Page linked to the IG account.
   • Page Name (optional) — for display.
   • IG User ID — Instagram Business Account ID (run GET /me/accounts then read instagram_business_account.id).
   • IG Username (optional) — for display.
   • Page Access Token — long-lived token with pages_messaging + instagram_manage_messages scopes.
   • App Secret — Meta App → Settings → Basic → App secret (click Show). Used to verify webhook signatures.
4. Click Save. Status flips to Connected.
5. A personal Verify Token is generated and shown — paste it into Meta's webhook subscription form.

Using Instagram DMs in the inbox

• Incoming DMs appear in the inbox as conversations with channel = Instagram. Real-time via webhook.
• Filter the sidebar by clicking the Instagram channel button to see only IG conversations (shows up only when the addon is active).
• Reply from the same reply composer used for email/WhatsApp. Text only (no rich text, no attachments — Meta API limitation for non-attachment-uploaded media).
• Message length: Instagram caps DM bodies at 1,000 bytes. MailTrixy auto-truncates safely at UTF-8 code-point boundaries to fit.
• 24-hour window: Meta only allows replies within 24 hours of the customer's last message (the “customer messaging window”). Outside that window you must use approved Message Tags.

Admin overview page

At /admin/addons/instagram/settings the admin sees:

• How users connect info card with a button to open the user Channels page.
• Webhook URL with a Copy button.
• Connected workspaces — read-only list showing every workspace that has connected, merged from both backends.
• One-time Meta App setup checklist.

The admin page is informational only — credentials are entered per-workspace by the workspace owner at Settings → Channels.

Troubleshooting