Instagram Integration
Connect your Instagram Business account to SuperWaba and manage all Instagram DMs, story replies, and mentions from a single unified inbox — powered by AI automation.
Capabilities
Messaging
| Feature | Description |
|---|---|
| Receive DMs | All Instagram Direct Messages appear in your unified inbox |
| Send replies | Reply to DMs directly from SuperWaba |
| Media messages | Receive and view images, videos, reels, and voice messages inline |
| Story replies | Receive and respond to story reply messages |
| Story mentions | Get notified when someone mentions you in their story |
| Shared posts | View posts/reels shared via DM with media preview |
| Quick replies | Send saved reply templates for common questions |
AI Automation
| Feature | Description |
|---|---|
| AI auto-reply | AI agents respond to Instagram DMs automatically 24/7 |
| Product recommendations | AI suggests products from your catalog based on conversation context |
| FAQ handling | AI answers common questions using your knowledge base |
| Lead qualification | AI asks qualifying questions and tags contacts |
| Language detection | AI responds in the customer's language automatically |
| Smart escalation | AI hands off to a human agent when it can't resolve the issue |
| Conversation summary | AI generates summaries for agents taking over |
Automation workflows
| Automation | Description |
|---|---|
| Welcome message | Auto-send greeting when someone DMs for the first time |
| Away message | Automatic response outside business hours |
| Story mention thank-you | Auto-reply when someone mentions you in their story |
| Follow-up messages | Send follow-ups if customer doesn't respond after X hours |
| Auto-tagging | Automatically tag contacts based on conversation content |
| Auto-assign | Route conversations to specific team members by topic |
Contact & CRM
| Feature | Description |
|---|---|
| Profile sync | Instagram username, display name, and profile photo imported |
| Contact enrichment | Merge Instagram contacts with WhatsApp/Messenger contacts |
| Labels & tags | Organize Instagram contacts with custom labels |
| Notes | Add internal notes to Instagram conversations |
| Contact history | View full conversation history across all channels |
| Export contacts | Export Instagram contact list with metadata |
Analytics & insights
| Feature | Description |
|---|---|
| Response time tracking | Monitor average response times for Instagram DMs |
| AI resolution rate | Percentage of conversations resolved without human |
| Message volume | Track incoming/outgoing DM volume over time |
| Peak hours | Identify when most Instagram DMs come in |
| Agent performance | Track individual agent response metrics |
Prerequisites
- An Instagram Business or Creator account
- A Facebook Page connected to your Instagram account
- Admin access to the Facebook Page
- Messaging enabled in Instagram Settings > Privacy > Messages
Setup steps
- Go to Settings > Integrations > Instagram
- Click Connect Instagram
- Sign in with Facebook and grant the required permissions (see Meta permissions below)
- Select the Instagram account to connect
- SuperWaba automatically subscribes to message webhooks
- (Optional) Configure AI agent for Instagram channel
Message types supported
Incoming (receive)
| Type | Supported | Notes |
|---|---|---|
| Text | Yes | Regular DM text messages |
| Image | Yes | Photos sent in DMs, with lightbox preview |
| Video | Yes | Videos and reels shared in DMs |
| Voice | Yes | Voice messages (audio clips) |
| Story reply | Yes | Reply to your story, includes story context |
| Story mention | Yes | Someone mentions your account in their story |
| Shared post/reel | Yes | Posts or reels forwarded via DM |
| Sticker | Yes | Instagram stickers |
| GIF | Yes | Animated GIFs |
Outgoing (send)
| Type | Supported | Notes |
|---|---|---|
| Text | Yes | Plain text replies |
| Image | Yes | Send images in DMs |
| Generic template | Yes | Card with image, title, subtitle, buttons |
| Quick replies | Yes | Buttons for fast responses |
| Heart/reaction | No | Instagram API limitation |
AI agent on Instagram
Your AI agent works across Instagram just like WhatsApp:
- Same knowledge base — AI uses your uploaded documents, URLs, and FAQs
- Same personality — Consistent tone and brand voice across channels
- Same escalation rules — Triggers human handoff based on your configured rules
- Channel-aware — AI knows it's on Instagram and adapts (no template messages, respects media limitations)
Configure AI for Instagram
-
Enable Instagram channel
-
Set Instagram-specific behavior (optional):
- Custom welcome message for Instagram DMs
- Different business hours for Instagram
- Instagram-specific escalation triggers
Limitations
| Limitation | Details |
|---|---|
| No template messages | Instagram API doesn't support pre-approved templates like WhatsApp |
| No interactive lists | Only quick reply buttons are supported |
| 24-hour window | You can only reply within 24 hours of the last customer message. Enable Human Agent to extend to 7 days (see below) |
| Rate limit | 200 messages per hour per Instagram account |
| No broadcast | Cannot send proactive messages (customer must message first) |
| Media reply only | Images only; no document or location sharing via Instagram API |
Human Agent — 7-day messaging window
Instagram enforces a 24-hour messaging window: you can only reply within 24 hours of the customer's last message. After that, the conversation locks.
SuperWaba supports the Human Agent tag (HUMAN_AGENT), which extends this window to 7 days — allowing support agents to reply to messages that came in during off-hours, weekends, or for cases that take longer to resolve.
How to use
- Open an Instagram conversation in the SuperWaba inbox
- In the chat input area, click the Human Agent toggle — it turns green and shows "Human Agent ON"
- Send your message — it will be delivered even if the 24-hour window has expired (within 7 days)
- Hover over the (i) icon next to the toggle for a detailed explanation
When to use
- Customer messaged on Friday evening and you're replying Monday morning
- Complex support cases (refunds, escalations) that take more than 24 hours
- Any reply to a message older than 24 hours but less than 7 days
Important rules
- Only for human agents — Meta requires that
HUMAN_AGENTis used only when a real person is responding, never by bots or automated systems - 7-day maximum — messages older than 7 days cannot be replied to, even with Human Agent enabled
- Requires Meta approval — the Human Agent permission must be approved via Meta App Review before it works in production
Developer API
You can also use the Human Agent tag via the Developer API:
curl -X POST 'https://app.superwaba.com/api/developer/v1/instagram/send-message' \
-H 'x-api-key: sk_live_abc123...' \
-H 'Content-Type: application/json' \
-d '{
"to": "instagram_user_id",
"type": "text",
"text": "Hi! Following up on your question from yesterday.",
"tag": "HUMAN_AGENT"
}'
Meta App permissions
SuperWaba requires the following Meta/Facebook permissions to operate. These are requested when you connect your Instagram account.
Required permissions
| Permission | What it does | Used for |
|---|---|---|
instagram_business_basic | Access Instagram Business account info | Profile sync, account identification |
instagram_business_manage_messages | Read and send Instagram DMs | Receiving and replying to DMs in the inbox |
instagram_business_manage_comments | Read and manage Instagram comments | Comment notifications, auto-reply to comments |
pages_show_list | List Facebook Pages the user manages | Page selection during Instagram/Messenger setup |
pages_read_user_content | Read posts and content on the Page | Story mention detection, shared post previews |
pages_manage_metadata | Manage Page settings and webhooks | Subscribing to Instagram messaging webhooks |
pages_manage_engagement | Manage Page engagement (likes, comments) | Reaction handling on Messenger and Page |
pages_read_engagement | Read Page engagement data | Analytics and message read receipts |
pages_messaging | Send and receive Messenger messages | Messenger inbox integration |
business_management | Manage business assets | Linking Instagram account to Facebook Page |
public_profile | Access public profile info | User authentication and display name |
Human Agent | Send messages using the HUMAN_AGENT tag | Extends 24h messaging window to 7 days for live support |
Meta App Review — screencast guide
Some permissions require Meta App Review before they work in production. Meta asks for a description and a screencast (screen recording) for each permission.
What to record for Human Agent
Record a 1–2 minute screen recording showing:
- Open SuperWaba → navigate to the Inbox
- Open an Instagram conversation with a customer
- Show the chat input area — point out the "Human Agent" toggle button
- Click the toggle ON — it turns green and shows "Human Agent ON"
- Hover over the (i) icon — show the tooltip explaining the feature
- Type and send a message with the toggle enabled
- Show the message delivered in the chat thread
Sample description for Human Agent
SuperWaba is a multi-channel customer support platform that connects businesses to their customers via WhatsApp, Instagram, and Facebook Messenger.
We use the Human Agent tag to extend the 24-hour Instagram messaging window to 7 days, allowing our live support agents to continue assisting customers whose cases take longer than 24 hours to resolve (e.g., refunds, escalations, technical troubleshooting).
The tag is only applied when a human agent explicitly enables it via a toggle in our inbox UI — it is never sent automatically by bots. It is also available via our Developer API for backend integrations that route messages through human support teams.
What to record for other permissions
For most permissions, the screencast should show the feature that uses the permission:
| Permission | What to show in screencast |
|---|---|
instagram_business_manage_messages | Open inbox → show received DM → type and send a reply |
instagram_business_manage_comments | Show a comment notification or auto-reply configuration |
pages_messaging | Open a Messenger conversation → send and receive messages |
pages_manage_metadata | Show Settings → Integrations → Instagram connected (webhook active) |
pages_show_list | Show the Page selection dropdown during setup |
business_management | Show Settings → Integrations → connecting an Instagram account |
tip
Record screencasts in development mode where app admins/developers can use permissions before approval. Meta reviewers understand this.
Troubleshooting
| Issue | Solution |
|---|---|
| DMs not appearing | Verify account is Business/Creator (not personal) |
| Token expired | Re-authenticate — Instagram tokens expire every 60 days |
| Story mentions missing | Check pages_manage_metadata permission is granted |
| AI not responding | Verify Instagram channel is enabled in AI Agent settings |
| Media not loading | Check Instagram CDN URLs haven't expired (they expire after ~1 hour) |
| Wrong account connected | Disconnect and reconnect with the correct Facebook Page |
Re-authenticate
Instagram tokens expire every 60 days. When expired:
- Go to Settings > Integrations > Instagram
- Click Reconnect
- Re-authorize with Facebook
- No configuration is lost — only the token is refreshed