Instagram DM setup
Connect Instagram Messaging so approved users can DM your business account and reach your project's agents.
Use cases#
- Social support — route Instagram DMs to ops or support agents
- Creator and brand inbox automation with human-approved agent access
- Combine with WhatsApp on the same Meta app if you prefer one developer app
Prerequisites#
- Meta Business app with Instagram product enabled
- Instagram professional account linked to a Facebook Page
- Page access token with instagram_manage_messages
- At least one deployed agent in your ViksaAI project
Installation steps#
- 1
Connect Instagram to a Meta app
Enable the Instagram product on your Meta Business app. Link your professional account to a Facebook Page. Note the Instagram account ID and generate a Page access token with
instagram_manage_messagesandpages_manage_metadata. - 2
Configure the webhook
App Dashboard → Webhooks → Instagram. Callback:
https://api.viksaai.com/v1/webhooks/metaUse the same Verify token and App secret as in Channel Hub. Subscribe to messages.
- 3
Connect in Channel Hub
Volt → Channel Hub → Instagram. Paste page access token, Instagram account ID, app secret, verify token, and optional Facebook page ID. Validate and Connect.
- 4
Grant access
Grants use the Instagram scoped sender ID from Meta webhooks (numeric string) — not @username. Use allow-all (*) for public pilot tests.
- 5
Test
DM your Instagram business account from an allowed user. Send plain text during the pilot.
Credentials reference#
| Field | Required | Notes |
|---|---|---|
| Page access token | Yes | instagram_manage_messages scope |
| Instagram account ID | Yes | Routing key for webhook events |
| App secret | Yes | Shared with WhatsApp if same Meta app |
| Verify token | Yes | Must match Meta webhook config |
| Facebook page ID | No | Reference / display |
Message flow#
- User sends a message on the channel.
- The platform posts a webhook to volt-engine-service at /v1/webhooks/*.
- Engine resolves account, org, and project from the global routing index (App ID, phone number ID, tenant key, etc.).
- Access is checked via channel_grants_v1 and optional Viksa project membership.
- The same Think→Act→Observe pipeline loads your project agent catalog and runs agents.
- The reply is sent back through the channel API (Graph, Telegram Bot API, Bot Framework, etc.).