SMS Webhook Payload

SMS webhooks are sent for every inbound and outbound text message. Includes full conversation history.

Example payload

1{
2 "event": {
3 "id": "evt_sms_abc123",
4 "channel": "sms",
5 "timestamp": 1706640000.0,
6 "data": {
7 "timestamp": 1706640000.0,
8 "direction": "outbound",
9 "platform": "sms",
10 "message_id": "msg_xyz789",
11 "sms_status": "sent",
12 "body": "Thanks for reaching out! When works best for a quick call?",
13 "delivery_status": "delivered",
14 "provider": "twilio",
15 "fallback_to_sms": false,
16 "usage_data": {
17 "prompt_tokens": 150,
18 "completion_tokens": 45,
19 "total_tokens": 195,
20 "model": "gpt-4"
21 },
22 "tools_called": ["check_calendar"],
23 "tool_calls": [
24 {
25 "name": "check_calendar",
26 "arguments": { "date": "2024-02-01" },
27 "result": { "available_slots": ["10:00", "14:00", "16:00"] }
28 }
29 ],
30 "attachments": [],
31 "analysis_result": {
32 "sentiment": "positive",
33 "intent": "schedule_meeting"
34 },
35 "appointments": []
36 }
37 },
38 "lead_id": "lead_123",
39 "lead_contact": {
40 "number": "+15551234567",
41 "email": "john@example.com",
42 "name": "John Doe"
43 },
44 "business_id": "biz_456",
45 "lead_created": false,
46 "full_conversation": [
47 {
48 "message_id": "msg_001",
49 "timestamp": 1706639500.0,
50 "direction": "inbound",
51 "body": "Hi, I saw your ad and I'm interested in learning more",
52 "sms_status": "received",
53 "delivery_status": "delivered"
54 },
55 {
56 "message_id": "msg_xyz789",
57 "timestamp": 1706640000.0,
58 "direction": "outbound",
59 "body": "Thanks for reaching out! When works best for a quick call?",
60 "sms_status": "sent",
61 "delivery_status": "delivered",
62 "usage_data": {
63 "prompt_tokens": 150,
64 "completion_tokens": 45,
65 "total_tokens": 195,
66 "model": "gpt-4"
67 },
68 "tools_called": ["check_calendar"]
69 }
70 ]
71}

Field reference

Core fields

FieldTypeRequiredDescription
timestampfloatYesUnix epoch timestamp
directionstringYesinbound or outbound
platformstringYesAlways sms
message_idstringYesUnique message identifier
sms_statusstringYesMessage status
bodystringYesMessage content

sms_status values

ValueDescription
sentMessage sent successfully
receivedInbound message received
failedMessage failed to send

delivery_status values

ValueDescription
queuedIn queue for delivery
sentSent to carrier
deliveredConfirmed delivered
undeliveredCould not deliver
failedDelivery failed

provider values

ValueDescription
twilioSent via Twilio
contiguitySent via Contiguity

Optional fields

FieldTypeDescription
delivery_statusstringCarrier delivery status
providerstringSMS provider used
fallback_to_smsbooleanTrue if iMessage fell back to SMS
usage_dataobjectLLM token usage for AI responses
tools_calledarrayList of tool names executed
tool_callsarrayRaw tool call data
attachmentsarrayMMS attachment URLs
attachment_metadataobjectAttachment details
analysis_resultobjectAI analysis output
appointmentsarrayExtracted appointment data
execution_contextobjectSource trigger context

usage_data object

FieldTypeDescription
prompt_tokensintegerInput tokens used
completion_tokensintegerOutput tokens generated
total_tokensintegerTotal tokens
modelstringLLM model used

full_conversation array

SMS webhooks include full_conversation with the complete thread history. Each message contains:

FieldTypeDescription
message_idstringMessage identifier
timestampfloatUnix epoch timestamp
directionstringinbound or outbound
bodystringMessage content
sms_statusstringStatus
delivery_statusstringDelivery status
usage_dataobjectLLM usage (outbound only)
tools_calledarrayTools executed (outbound only)

The full_conversation array is unique to SMS webhooks and provides complete conversation context for each event.