Instagram Messaging Permissions Setup

Problem

Instagram messages are received successfully, but replies fail with error:

Error #3: Application does not have the capability to make this API call.

Solution: Add Instagram Messaging Permissions

Step 1: Open Meta App Dashboard

1. Go to: https://developers.facebook.com/apps/1798607127362076
2. Navigate to App Settings → Basic

Step 2: Add Instagram Product

1. In left sidebar, click "Add Product" (if not already added)
2. Find "Instagram" and click "Set Up"
3. This will add Instagram Graph API to your app

Step 3: Request Permissions

For Development/Testing (Quick Setup)

1. Go to App Review → Permissions and Features

2. Find these permissions:

   • ✅ pages_messaging (already enabled for Messenger)
   • ⚠️ instagram_basic - Click "Request" or "Add"
   • ⚠️ instagram_manage_messages - Click "Request" or "Add"
   • ⚠️ instagram_content_publish (optional - for posting content)

3. For Development Mode apps, these are automatically granted for:

   • App Admins
   • App Developers
   • App Testers

For Production (App Review Required)

1. Go to App Review → Permissions and Features

2. For each permission, click "Request Advanced Access"

3. Fill out the submission form:

   • How you'll use this permission: "To send automated responses to Instagram Direct Messages for customer support chatbot"
   • Screencast: Show your app receiving and replying to Instagram messages
   • Privacy Policy URL: Provide your privacy policy link

4. Submit for review (can take 1-3 days)

Step 4: Configure Instagram Business Account

1. Go to Instagram Settings (in Meta App Dashboard)
2. Click "Add or Remove Instagram Accounts"
3. Select your Instagram Business account
4. Make sure it's linked to your Facebook Page: 800539023147890

Step 5: Verify Permissions

Check Current Permissions

# Get your Page Access Token
curl -X GET "https://graph.facebook.com/v17.0/800539023147890?fields=access_token&access_token=YOUR_USER_ACCESS_TOKEN"

# Check token permissions
curl -X GET "https://graph.facebook.com/v17.0/debug_token?input_token=PAGE_ACCESS_TOKEN&access_token=APP_ID|APP_SECRET"

Expected response should include:

{
  "scopes": [
    "pages_messaging",
    "instagram_basic",
    "instagram_manage_messages",
    "pages_show_list",
    "pages_read_engagement"
  ]
}

Test Instagram Messaging API

# Test sending a message
curl -X POST "https://graph.facebook.com/v17.0/17841477440552555/messages" \
  -H "Authorization: Bearer PAGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "id": "2060154861451428"
    },
    "message": {
      "text": "Test message from API"
    }
  }'

Expected Success:

{
  "recipient_id": "2060154861451428",
  "message_id": "mid.xxxxx"
}

If still error #3: Permissions not granted or Instagram account not properly linked

Step 6: Re-authenticate (If Needed)

After adding permissions, you need to re-authenticate to get new tokens with updated scopes:

1. Go to your app: https://dma-test.acebox.eu
2. Navigate to Channels → Create Channel → Instagram
3. Click "Connect with Meta" again
4. Authorize with the new permissions
5. This will update tokens in meta_access_tokens table

Or use the OAuth URL directly:

https://api.dma-test.acebox.eu/v1/meta/oauth/authorize?tenant_id=YOUR_TENANT_ID

Step 7: Verify in Backend

Check that new tokens have the correct permissions:

# Check tokens in database
docker exec voice-agent-backend npx tsx -e "
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();
const tokens = await prisma.metaAccessToken.findMany({
  where: { 
    tenant_id: '6b9dd1df-4b12-4b1d-aef9-8e8cc3875c2e',
    token_type: 'instagram'
  },
  select: { external_id: true, expires_at: true, created_at: true }
});
console.log(JSON.stringify(tokens, null, 2));
await prisma.\$disconnect();
"

Troubleshooting

Still Getting Error #3?

1. Check App Mode:

   • Development Mode: Only admins/developers/testers can use the app
   • Live Mode: Need App Review approval for permissions

2. Check Instagram Account Type:

   • Must be Instagram Business or Instagram Creator account
   • Personal Instagram accounts cannot receive messages via API
   • Convert at: Instagram Settings → Account → Switch to Professional Account

3. Check Page Connection:

   • Instagram account must be linked to Facebook Page
   • Go to: Facebook Page Settings → Instagram → Connect Account

4. Check Message Settings:

   • Instagram → Settings → Privacy → Messages
   • Enable "Allow message requests from everyone"

5. Token Expiration:

   • Check if token expired: expires_at in database
   • Re-authenticate if expired

Error: "Instagram account not linked to Page"

# Check Page's Instagram account
curl -X GET "https://graph.facebook.com/v17.0/800539023147890?fields=instagram_business_account&access_token=PAGE_TOKEN"

Should return:

{
  "instagram_business_account": {
    "id": "17841477440552555"
  }
}

Error: "User not authorized"

The Instagram account must be:

• Connected to Facebook Page 800539023147890
• Page admin must authorize the app
• App must have instagram_manage_messages permission

Required Permissions Summary

Permission	Purpose	Status
pages_messaging	Send/receive Messenger messages	✅ Already enabled
pages_show_list	List user's Facebook Pages	✅ Already enabled
pages_read_engagement	Read Page engagement data	✅ Already enabled
instagram_basic	Access basic Instagram data	⚠️ NEED TO ADD
instagram_manage_messages	Send/receive Instagram DMs	⚠️ NEED TO ADD

After Setup

Once permissions are added and tokens refreshed, test again:

# Send a message to your Instagram
# Then check logs
docker logs voice-agent-backend 2>&1 | grep "instagram" | tail -20

Expected logs:

meta.webhook.event_received (object: instagram)
meta.webhook.message_extracted
meta.conversation.processing_started
message_sender.send_initiated
✅ meta.message.chunk_sent (no errors)
✅ meta.conversation.processing_completed

Documentation Links

• Instagram Messaging API
• Instagram Permissions
• App Review
• Instagram Business Account Setup

---

Quick Checklist

• [ ] Add Instagram product to Meta App
• [ ] Request instagram_basic permission
• [ ] Request instagram_manage_messages permission
• [ ] Verify Instagram Business account is linked to Page
• [ ] Re-authenticate to get new tokens with updated permissions
• [ ] Test sending a message
• [ ] Check backend logs for successful delivery

After completing these steps, Instagram replies should work! 🎉