WhatsApp Webhook Payload
WhatsApp webhooks are sent for messages, reactions, and read receipts.
Example payload
1 { 2 "event": { 3 "id": "evt_wa_abc123", 4 "channel": "whatsapp", 5 "timestamp": 1706640000.0, 6 "data": { 7 "timestamp": 1706640000.0, 8 "direction": "inbound", 9 "platform": "whatsapp", 10 "message_id": "wamid_xyz789", 11 "chat_id": "chat_456", 12 "content": "I'd like to schedule an appointment for next week", 13 "is_from_account": false, 14 "account_id": "acc_123", 15 "sender_attendee": { 16 "attendee_id": "att_789", 17 "attendee_name": "John Doe", 18 "attendee_provider_id": "+15551234567", 19 "attendee_profile_url": "https://..." 20 }, 21 "social_event_type": "message_received", 22 "attendees": [ 23 { 24 "attendee_id": "att_789", 25 "attendee_name": "John Doe", 26 "attendee_provider_id": "+15551234567" 27 } 28 ], 29 "attachments": [ 30 { 31 "id": "att_001", 32 "type": "image", 33 "url": "https://storage.example.com/attachments/img_001.jpg", 34 "mimetype": "image/jpeg", 35 "size": { 36 "width": 1024, 37 "height": 768 38 } 39 } 40 ], 41 "usage_data": { 42 "prompt_tokens": 200, 43 "completion_tokens": 60, 44 "model": "gpt-4" 45 }, 46 "tools_called": ["book_appointment"], 47 "tool_results": { 48 "book_appointment": { 49 "success": true, 50 "datetime": "2024-02-01T10:00:00Z" 51 } 52 }, 53 "analysis_result": { 54 "sentiment": "positive", 55 "intent": "schedule" 56 }, 57 "appointments": [ 58 { 59 "datetime": "2024-02-01T10:00:00Z", 60 "type": "consultation" 61 } 62 ] 63 } 64 }, 65 "lead_id": "lead_123", 66 "lead_contact": { 67 "number": "+15551234567", 68 "email": "john@example.com", 69 "name": "John Doe" 70 }, 71 "business_id": "biz_456", 72 "lead_created": false 73 }
Field reference
Core fields
| Field | Type | Required | Description |
|---|---|---|---|
timestamp | float | Yes | Unix epoch timestamp |
direction | string | Yes | inbound or outbound |
platform | string | Yes | Always whatsapp |
message_id | string | Yes | WhatsApp 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 WhatsApp account ID |
social_event_type | string | Yes | Event type (see values below) |
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 | Display name |
attendee_provider_id | string | Phone number |
attendee_profile_url | string | Profile picture URL (optional) |
Optional fields
| Field | Type | Description |
|---|---|---|
attendees | array | List of conversation participants |
attachments | array | Media attachments |
usage_data | object | LLM token usage |
tools_called | array | List of tool names executed |
tool_calls | array | Raw tool call data |
tool_results | object | Detailed tool execution results |
analysis_result | object | AI analysis output |
appointments | array | Extracted appointment data |
execution_context | object | Source trigger context |
reaction | string | Emoji reaction (for reaction events) |
reaction_sender | object | Who sent the reaction |
attachments array
| Field | Type | Description |
|---|---|---|
id | string | Attachment ID |
type | string | image, video, audio, document, sticker |
url | string | Download URL |
mimetype | string | MIME type |
sticker | boolean | True if sticker |
unavailable | boolean | True if expired/unavailable |
size | object | Dimensions (width, height) for images/videos |
message_id | string | Associated message ID |
Message splitting fields
For long messages that are split:
| Field | Type | Description |
|---|---|---|
split_message_info | object | Split metadata |
original_full_message | string | Complete message before split |
Message accumulation fields
For accumulated rapid messages:
| Field | Type | Description |
|---|---|---|
accumulation_info | object | Accumulation metadata |
accumulated_content | string | Combined message content |