Instagram Webhook Payload
Instagram webhooks are sent for direct messages, reactions, and read receipts.
Example payload
1 { 2 "event": { 3 "id": "evt_ig_abc123", 4 "channel": "instagram", 5 "timestamp": 1706640000.0, 6 "data": { 7 "timestamp": 1706640000.0, 8 "direction": "inbound", 9 "platform": "instagram", 10 "message_id": "igmid_xyz789", 11 "chat_id": "chat_456", 12 "content": "Hey! I saw your post about coaching services", 13 "is_from_account": false, 14 "account_id": "acc_123", 15 "sender_attendee": { 16 "attendee_id": "att_789", 17 "attendee_name": "johndoe", 18 "attendee_provider_id": "17841234567890", 19 "attendee_profile_url": "https://instagram.com/johndoe" 20 }, 21 "social_event_type": "message_received", 22 "attendees": [ 23 { 24 "attendee_id": "att_789", 25 "attendee_name": "johndoe", 26 "attendee_provider_id": "17841234567890" 27 } 28 ], 29 "attachments": [], 30 "usage_data": { 31 "prompt_tokens": 180, 32 "completion_tokens": 55, 33 "model": "gpt-4" 34 }, 35 "tools_called": [], 36 "analysis_result": { 37 "sentiment": "curious", 38 "intent": "inquiry" 39 } 40 } 41 }, 42 "lead_id": "lead_123", 43 "lead_contact": { 44 "number": "", 45 "email": "", 46 "name": "johndoe" 47 }, 48 "business_id": "biz_456", 49 "lead_created": true 50 }
Field reference
Core fields
| Field | Type | Required | Description |
|---|---|---|---|
timestamp | float | Yes | Unix epoch timestamp |
direction | string | Yes | inbound or outbound |
platform | string | Yes | Always instagram |
message_id | string | Yes | Instagram message ID |
chat_id | string | Yes | Conversation thread ID |
content | string | Yes | Message content |
is_from_account | boolean | Yes | True if sent by connected account |
account_id | string | Yes | Connected Instagram account ID |
social_event_type | string | Yes | Event type |
social_event_type values
| Value | Description |
|---|---|
message_received | New message received |
message_reaction | Reaction added to message |
message_read | Message marked as read |
message_edited | Message was edited |
message_deleted | Message was deleted |
sender_attendee object
| Field | Type | Description |
|---|---|---|
attendee_id | string | Internal attendee ID |
attendee_name | string | Instagram username |
attendee_provider_id | string | Instagram user ID |
attendee_profile_url | string | Profile URL (optional) |
Optional fields
| Field | Type | Description |
|---|---|---|
attendees | array | Conversation participants |
attachments | array | Media attachments |
usage_data | object | LLM token usage |
tools_called | array | Tool names executed |
tool_calls | array | Raw tool call data |
tool_results | object | Tool execution results |
analysis_result | object | AI analysis output |
appointments | array | Extracted appointments |
execution_context | object | Source trigger context |
reaction | string | Emoji (for reactions) |
reaction_sender | object | Reaction sender info |
attachments array
| Field | Type | Description |
|---|---|---|
id | string | Attachment ID |
type | string | image, video, audio, story_mention, reel |
url | string | Download URL |
mimetype | string | MIME type |
unavailable | boolean | True if expired |
size | object | Dimensions |
Instagram leads may not have phone or email initially. Use the conversation to collect contact information.