Instagram Integration

Connect Instagram Direct Messages to your ChatIQ bot to provide AI-powered customer support through Instagram.

Prerequisites

Before you begin, ensure you have:

• ✅ A Meta App in Published/Live mode with Instagram product enabled
• ✅ An Instagram Business or Creator account (not personal)
• ✅ Instagram account connected to a Facebook Page
• ✅ Required permissions requested and approved in Meta App Review

Step 1: Get Your Meta App Credentials

You'll need three credentials from your Meta App:

1. Instagram App Secret

Important: Use the Instagram App Secret, not the main App Secret.

1. Go to: Meta Developers Console
2. Select your app
3. Go to: Use Cases → Instagram API → API setup with Instagram login
4. Find "Instagram app secret" (not "App secret" in Basic Settings)
5. Copy the Instagram App Secret (starts with 0...)

2. Page Access Token

You need a long-lived Page Access Token (never expires for production). Get it via OAuth:

1. Configure OAuth Redirect URI:

   • Go to: Meta App → Facebook Login for Business → Settings
   • Add your redirect URI to "Valid OAuth Redirect URIs" (e.g., https://www.chatiq.io/oauth/callback)

2. Generate User Token:

   • Open OAuth URL in browser (replace YOUR_APP_ID and YOUR_REDIRECT_URI):

     https://www.facebook.com/v20.0/dialog/oauth?client_id=YOUR_APP_ID&redirect_uri=YOUR_REDIRECT_URI&scope=pages_show_list,pages_read_engagement,instagram_basic,instagram_manage_messages&response_type=code
     

   • Authorize and grant permissions
   • Copy the code from the redirect URL

3. Exchange Code for Token:

   curl -G "https://graph.facebook.com/v20.0/oauth/access_token" \
     --data-urlencode "client_id=YOUR_APP_ID" \
     --data-urlencode "redirect_uri=YOUR_REDIRECT_URI" \
     --data-urlencode "client_secret=YOUR_APP_SECRET" \
     --data-urlencode "code=CODE_FROM_REDIRECT"
   

4. Get Page Access Token:

   curl -G "https://graph.facebook.com/YOUR_PAGE_ID" \
     --data-urlencode "fields=access_token,instagram_business_account" \
     --data-urlencode "access_token=USER_TOKEN_FROM_STEP_3"
   

   • Use the access_token from the Page that has instagram_business_account

Alternative (Production Recommended): Use a System User token which never expires:

• Go to: Meta Business Settings → System Users
• Create a System User and assign it to your Page
• Generate token with instagram_basic and instagram_manage_messages permissions

3. Verify Token

Choose any string (e.g., chatiq-instagram-verify). You'll use the same token in Meta webhook settings.

Step 2: Connect Instagram in ChatIQ

1. Go to /dashboard/team/integrations and open the Instagram tab
2. Select bot: Choose the bot you want to connect to Instagram
3. Enter credentials:
   • App Secret: Paste your Instagram App Secret (from Step 1.1)
   • Page Access Token: Paste your Page Access Token (from Step 1.2)
   • Verify Token: Enter a token of your choice (remember this for Step 3)
4. Click Save Instagram Integration
5. Copy the webhook URL shown after saving (format: https://www.chatiq.io/api/integrations/instagram/webhook/[integrationId])

Step 3: Configure Webhook in Meta

1. Go to: Meta Developers Console → Your App

2. Navigate to: Use Cases → Instagram API → Webhooks

3. Add Callback URL:

   • Click Add Callback URL or Configure Webhooks
   • Paste the webhook URL from ChatIQ (Step 2.5)
   • Enter the Verify Token (same as Step 2.3)
   • Click Verify and Save

4. Subscribe to Messages:

   • Find your webhook in the list
   • Under Subscriptions, check messages for Instagram
   • Save changes

5. Enable Webhook Subscription (CRITICAL):

   • Go to: Use Cases → Instagram API → API setup with Instagram login
   • Find your Instagram account in the list
   • Enable the "Webhook Subscription" toggle (must be ON)
   • This is required for real messages to trigger webhooks

Step 4: Test the Integration

1. Send a Direct Message from any Instagram account to your Instagram Business account
2. Check ChatIQ dashboard to verify the message was received and processed
3. Verify you receive an AI-powered reply in Instagram DMs

Troubleshooting

Webhook receives test events but not real messages

• Check: Webhook Subscription toggle is ON (Step 3.5)
• Verify: App is in Published mode (not Development)
• For Development mode: Add message senders as test users in Meta App

Signature verification fails (401 errors)

• Issue: Wrong App Secret used
• Fix: Use the Instagram App Secret from "API setup with Instagram login", not the main App Secret from Basic Settings
• Location: Meta App → Use Cases → Instagram API → API setup with Instagram login

Token expires or gets invalid

• Issue: Using short-lived token
• Fix: Use System User token (never expires) or regenerate Page token following Step 1.2

No webhook events received

• Check: Webhook URL is correct and verified
• Check: Webhook Subscription toggle is ON
• Check: messages is subscribed in webhook settings
• Check: App is Published (for production) or sender is a tester (for Development)

Manage the Integration

After setup, you can:

• Edit credentials: Click "Edit" to update App Secret, Page Access Token, or Verify Token
• Disable/Enable: Toggle integration status
• Delete: Remove the integration
• Copy webhook URL: Get the webhook URL anytime from the integration row

Important Notes

• Instagram App Secret: Always use the Instagram-specific App Secret, not the main App Secret
• Page Access Token: Must be long-lived or System User token for production
• Webhook Subscription: Toggle must be ON for real messages to work
• App Review: Required for production use (non-testers). Submit App Review in Meta App Dashboard.

Need Help?

• Email support@chatiq.io for setup assistance
• Review Meta's Instagram Messaging API documentation