Instagram Business Integration#

Connect your Instagram Business account via Facebook Login OAuth to send and receive direct messages.

Overview#

Property	Value
Platform Type	`INSTAGRAM`
Authentication	OAuth (Facebook Login)
Webhook Type	Shared
Message Limit	1000 characters

Features#

Send and receive direct messages
Rich media (images, videos)
Story mentions and replies
Message reactions
Automatic token management (60-day refresh)

Prerequisites#

Instagram Business or Creator account
Account linked to a Facebook Page
Facebook Business Manager access

**Important**: Personal Instagram accounts cannot use the Messaging API. You must convert to a Business or Creator account.

Account Requirements#

Instagram Business Account#

Open Instagram app → Settings → Account
Select “Switch to Professional Account”
Choose “Business”
Connect to your Facebook Page

Facebook Page Link#

Your Instagram account must be linked to a Facebook Page:

Go to Facebook Page settings
Select “Instagram” from the menu
Click “Connect Account”
Log in to Instagram and authorize

Setup Guide#

Step 1: Connect via OAuth#

In Outeract console, go to Connections → Add Connection
Select Instagram Business
Click Connect with Facebook
Log in to Facebook
Select the Facebook Page linked to your Instagram
Grant required permissions:
- instagram_manage_messages
- pages_messaging
- pages_manage_metadata
Connection is created automatically

Step 2: Webhook Configuration#

Instagram uses a shared webhook architecture:

One webhook URL handles all Instagram connections
Routing is automatic based on Instagram Business Account ID
Configure once in your Meta App settings

Step 3: Verify Connection#

Open the connection in the console and run a health check. It reports whether the connection is valid, a summary message, and the per-test results.

Sending Messages#

Text Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_instagram_123"
    recipientUserId: "user-uuid"
    message: "Thanks for reaching out!"
  ) {
    id
    eventTypeName
  }
}

Image Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_instagram_123"
    recipientUserId: "user-uuid"
    message: "Check this out!"
    fileIds: ["file_xyz789"]
  ) {
    id
  }
}

Supported Message Types#

Type	Send	Receive	Notes
Text	✓	✓	Up to 1000 characters
Images	✓	✓	JPEG, PNG
Videos	-	✓	Receive only
Stories	-	✓	Story mentions
Reactions	✓	✓	Heart reaction

External ID Format#

Instagram uses Scoped User IDs (IGSID):

Type	Format	Example
User ID	17-digit number	`17841412345678901`

**Note**: Instagram IDs are scoped to your app. The same user has different IDs across different apps.

24-Hour Messaging Window#

Instagram enforces a messaging window similar to WhatsApp:

Human Agent Tag: Send within 7 days of user message
Standard Tag: Send within 24 hours

Outside these windows, you cannot initiate messages.

Webhook Events#

Inbound Message#

{
  "event_id": "evt_abc123",
  "event_type": "message.inbound",
  "payload": {
    "message": {
      "text": "Hi there!",
      "role": "user"
    },
    "platform": "instagram",
    "external_message_id": "aWdfZAG..."
  },
  "edges": {
    "sent_by": {
      "external_id": "17841412345678901"
    }
  }
}

Story Mention#

{
  "event_id": "evt_xyz789",
  "event_type": "story.mention",
  "payload": {
    "story_id": "17841456789012345",
    "media_type": "image"
  }
}

Token Management#

Instagram uses Page Access Tokens:

Duration: 60 days (long-lived)
Auto-refresh: Outeract refreshes before expiry
Reconnect: If issues occur, reconnect via OAuth

Rate Limits#

Scope	Limit
Per user	250 messages/24 hours
API calls	200 calls/user/hour

Troubleshooting#

“Permission denied”#

Verify Instagram account is Business/Creator type
Check Facebook Page is linked
Ensure required permissions are granted

“User not found”#

Verify Instagram Scoped User ID is correct
Check user hasn’t blocked your account
Ensure user has messaged you first

“Token expired”#

Tokens auto-refresh every 60 days
If persistent, reconnect via OAuth
Check Facebook Page permissions

“Cannot send message”#

Verify within 24-hour/7-day window
Check if user has messaging enabled
Ensure account isn’t restricted

“Outside messaging window”#

Outeract detects this error (Meta error subcode 2534023) and returns an OUTSIDE_MESSAGING_WINDOW error
The failed message event is recorded with delivery_status.failed_at set and delivery_status.error_type of messaging_window_closed
Instagram requires users to message you first; you have 24 hours to respond freely

Security#

Instagram webhook signatures use HMAC-SHA256:

Signature in X-Hub-Signature-256 header
Validated against your App Secret
Invalid requests are rejected