> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Instagram DM Integration
> Enable AI-powered Instagram Direct Messages for your assistants
## What is Instagram DM Integration?
Instagram DM Integration lets your IllumiChat assistants respond to Instagram Direct Messages automatically. When someone messages your Instagram account, your assistant reads the message, generates a helpful response, and sends it back — all via Instagram DM.
Perfect for:
* **Customer support**: Let customers DM you for instant AI-powered help
* **Lead engagement**: Capture and respond to inbound leads from Instagram 24/7
* **Story interactions**: Automatically respond to story replies and mentions
* **Conversation starters**: Set up icebreaker questions to guide conversations
Instagram DM Integration connects via the **Meta Graph API** using OAuth. You'll authorize IllumiChat to manage messages on behalf of your Instagram Professional Account.
## Getting Started
### Prerequisites
Before setting up Instagram DM, you'll need:
1. An IllumiChat workspace with **Admin** access
2. An **Instagram Professional Account** (Business or Creator)
3. A **Facebook Page** linked to your Instagram account
4. Message access enabled in your Meta App settings
To check your account type, go to Instagram Settings → Account → Switch to Professional Account. Both Business and Creator accounts work.
### 1. Connect Your Instagram Account
1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **Instagram** card
4. Review the prerequisites checklist
5. Click **Connect with Instagram**
6. Log in to Facebook and authorize the required permissions
7. Select the Instagram account you want to connect
8. Click **Connect**
IllumiChat will:
* Verify your Instagram account has messaging enabled
* Set up the webhook to receive incoming messages
* Encrypt and store your access token securely
### 2. Configure Settings
After connecting, configure your Instagram DM settings:
| Option | Default | Description |
| ------------------------ | ------- | ----------------------------------------------- |
| **Enabled** | On | Toggle Instagram DM on or off |
| **Max Message Length** | 1000 | Maximum characters per response (50-1000) |
| **Contact Matching** | On | Match Instagram users to existing contacts |
| **Auto-Create Contacts** | On | Create contacts for new Instagram conversations |
### 3. Configure Story Interactions
Instagram DM supports automatic responses to story interactions:
| Setting | Options | Description |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------- |
| **Story Reply AI Context** | On/Off | Include story context when generating AI responses to story replies |
| **Story Mention Auto-Reply** | AI / Template / Disabled | How to respond when someone mentions you in their story |
| **Story Mention Template** | Custom text | Pre-written message for template auto-replies |
### 4. Set Up Icebreakers
Icebreakers are conversation starters that appear when someone opens a new DM with your Instagram account. They help guide users to common topics.
* Add up to **4 icebreakers**
* Each question can be up to **80 characters**
* Icebreakers are synced to Instagram via the Meta API
Good icebreakers are short, action-oriented questions like "What services do you offer?" or "How can I schedule an appointment?"
### 5. Test It Out
Send a Direct Message to your connected Instagram account. Within a few seconds, you should receive an AI-generated response.
## How It Works
When someone sends a DM to your Instagram account:
1. **Meta receives the message** and forwards it to IllumiChat via webhook
2. **IllumiChat validates** the request using the X-Hub-Signature-256 header
3. **A conversation session** is created (or resumed) for that user
4. **Your assistant generates a response** using its system prompt with Instagram-specific guidelines
5. **The response is formatted** — markdown is stripped and the message is kept under 1000 characters
6. **The response is sent back** via the Meta Send API
7. **The full conversation** is saved to your chat history for review
Your assistant automatically adapts to Instagram by keeping responses concise, using a casual tone, and including emojis where appropriate.
### Message Handling
Instagram DMs have a **1000 character limit**. If your assistant generates a longer response:
* Markdown formatting is automatically stripped (headers, bold, code blocks, links)
* The message is split at sentence boundaries into multiple messages
* Each chunk is sent as a separate DM to maintain readability
### Story Replies
When someone replies to your Instagram Story, your assistant can use that context to generate a more relevant response. The AI knows the user is engaging with your story content and can acknowledge that naturally.
### Story Mentions
When someone mentions your account in their Story, IllumiChat can:
* **AI mode**: Generate a personalized thank-you message
* **Template mode**: Send your pre-written template message
* **Disabled**: No auto-reply (the mention is still tracked in analytics)
### Icebreaker Taps
When a user taps an icebreaker question, it creates a new conversation and triggers an AI response tailored to that topic.
## Instagram Analytics
Track how your Instagram DM integration is performing from the **Analytics** dashboard.
### Usage Metrics
* **Total Messages**: Inbound and outbound message counts
* **Delivery Rate**: Percentage of messages successfully delivered
* **Active Conversations**: Currently active DM conversations
* **Story Interactions**: Total story replies and mentions received
* **Icebreaker Taps**: How often conversation starters are used
### Conversation Sources
See how users are initiating conversations:
* **Direct**: Standard DM conversations
* **Story Reply**: Users replying to your stories
* **Story Mention**: Users mentioning you in their stories
* **Icebreaker**: Users tapping icebreaker questions
### Daily Breakdown
View message volume by day to identify trends and peak usage periods. The chart shows inbound vs outbound messages over time.
Access analytics from your assistant's **Channels → Instagram** detail page. Filter by time period: **7 days**, **30 days**, or **90 days**.
## Conversations
Browse active Instagram DM conversations from the **Recent Conversations** section on the Instagram channel page. Each conversation shows:
* Instagram username and profile picture
* **AI** or **Human** badge (whether AI is actively responding)
* Initiation source badge (Direct, Story Reply, Story Mention, Icebreaker)
* Message count and last activity time
## AI control
You can turn off AI replies for Instagram without disconnecting the channel: in the Instagram settings, toggle **"AI replies to Instagram messages"** off. Conversations still arrive in the [Universal Inbox](/features/inbox) — your team just handles them manually instead of the AI. This channel-level switch combines with the per-conversation **Pause AI** control in the inbox: if either says off, the AI stays quiet. See the [Universal Inbox guide](/features/inbox#ai-control) for details.
## Best Practices
Add Instagram-specific instructions to your assistant's system prompt. For example: "Keep responses casual and friendly. Use emojis naturally. Keep responses under 500 characters when possible."
Set up icebreakers that reflect your most common customer questions. This helps users get answers faster and reduces off-topic messages.
When enabled, your assistant knows the user is replying to a story and can acknowledge their engagement naturally, leading to more authentic conversations.
Use **AI mode** for personalized responses, **Template mode** for consistent branding, or **Disabled** if you prefer to handle mentions manually.
Check your delivery rate and conversation sources. High story interaction rates indicate good content engagement, while icebreaker usage shows your conversation starters are effective.
Instagram users expect quick, snappy replies. Aim for responses under 500 characters when possible. Longer responses are automatically split into multiple messages.
## Troubleshooting
### No Instagram accounts found during setup
* Ensure the Facebook user authorizing the connection is an **admin** of the Facebook Page
* The Facebook Page must be **linked** to an Instagram Professional Account
* If re-authorizing, make sure to grant **all** requested permissions (especially `pages_read_engagement`)
* The setup screen will display a diagnostic hint explaining why no accounts were found
### Not receiving messages
* Verify your Instagram account is a **Professional Account** (Business or Creator)
* Check that Instagram DM is **enabled** in your configuration
* Ensure your Facebook Page is properly linked to your Instagram account
* Verify the connection status shows **Active** on the config page
### Token expired
Instagram access tokens can expire or be revoked. If you see a "Token Expired" warning:
1. Go to your assistant's **Channels → Instagram** page
2. Click **Reconnect** to re-authorize with Facebook
3. Your existing configuration and conversation history are preserved
### Icebreakers not showing
* Icebreakers may take up to **24 hours** to appear on Instagram
* Check that the sync status shows "Synced to Meta" after saving
* Verify your icebreakers meet the limits (max 4, max 80 characters each)
### Messages not delivering
* Check the **Analytics** dashboard for failed message counts
* Ensure the conversation is within Instagram's **24-hour messaging window**
* Verify your Meta App has the required permissions
### Story auto-replies not working
* Confirm the **Story Mention Auto-Reply** setting is not set to "Disabled"
* For template mode, verify you've entered a template message
* Check that your assistant is enabled and the Instagram channel is active
Instagram has a **24-hour messaging window**. Your assistant can only send messages to users who have messaged you within the last 24 hours. After that, you'll need the user to send a new message to reopen the window.
Contact support for Instagram DM setup assistance