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

FieldTypeRequiredDescription
timestampfloatYesUnix epoch timestamp
directionstringYesinbound or outbound
platformstringYesAlways whatsapp
message_idstringYesWhatsApp message ID
chat_idstringYesConversation thread ID
contentstringYesMessage content
is_from_accountbooleanYesTrue if sent by connected account
account_idstringYesConnected WhatsApp account ID
social_event_typestringYesEvent type (see values below)

social_event_type values

ValueDescription
message_receivedNew message received
message_reactionReaction added to message
message_readMessage marked as read
message_editedMessage was edited
message_deletedMessage was deleted

sender_attendee object

FieldTypeDescription
attendee_idstringInternal attendee ID
attendee_namestringDisplay name
attendee_provider_idstringPhone number
attendee_profile_urlstringProfile picture URL (optional)

Optional fields

FieldTypeDescription
attendeesarrayList of conversation participants
attachmentsarrayMedia attachments
usage_dataobjectLLM token usage
tools_calledarrayList of tool names executed
tool_callsarrayRaw tool call data
tool_resultsobjectDetailed tool execution results
analysis_resultobjectAI analysis output
appointmentsarrayExtracted appointment data
execution_contextobjectSource trigger context
reactionstringEmoji reaction (for reaction events)
reaction_senderobjectWho sent the reaction

attachments array

FieldTypeDescription
idstringAttachment ID
typestringimage, video, audio, document, sticker
urlstringDownload URL
mimetypestringMIME type
stickerbooleanTrue if sticker
unavailablebooleanTrue if expired/unavailable
sizeobjectDimensions (width, height) for images/videos
message_idstringAssociated message ID

Message splitting fields

For long messages that are split:

FieldTypeDescription
split_message_infoobjectSplit metadata
original_full_messagestringComplete message before split

Message accumulation fields

For accumulated rapid messages:

FieldTypeDescription
accumulation_infoobjectAccumulation metadata
accumulated_contentstringCombined message content