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
| Field | Type | Required | Description |
|---|---|---|---|
timestamp | float | Yes | Unix epoch timestamp |
direction | string | Yes | inbound or outbound |
platform | string | Yes | Always sms |
message_id | string | Yes | Unique message identifier |
sms_status | string | Yes | Message status |
body | string | Yes | Message content |
sms_status values
| Value | Description |
|---|---|
sent | Message sent successfully |
received | Inbound message received |
failed | Message failed to send |
delivery_status values
| Value | Description |
|---|---|
queued | In queue for delivery |
sent | Sent to carrier |
delivered | Confirmed delivered |
undelivered | Could not deliver |
failed | Delivery failed |
provider values
| Value | Description |
|---|---|
twilio | Sent via Twilio |
contiguity | Sent via Contiguity |
Optional fields
| Field | Type | Description |
|---|---|---|
delivery_status | string | Carrier delivery status |
provider | string | SMS provider used |
fallback_to_sms | boolean | True if iMessage fell back to SMS |
usage_data | object | LLM token usage for AI responses |
tools_called | array | List of tool names executed |
tool_calls | array | Raw tool call data |
attachments | array | MMS attachment URLs |
attachment_metadata | object | Attachment details |
analysis_result | object | AI analysis output |
appointments | array | Extracted appointment data |
execution_context | object | Source trigger context |
usage_data object
| Field | Type | Description |
|---|---|---|
prompt_tokens | integer | Input tokens used |
completion_tokens | integer | Output tokens generated |
total_tokens | integer | Total tokens |
model | string | LLM model used |
full_conversation array
SMS webhooks include full_conversation with the complete thread history. Each message contains:
| Field | Type | Description |
|---|---|---|
message_id | string | Message identifier |
timestamp | float | Unix epoch timestamp |
direction | string | inbound or outbound |
body | string | Message content |
sms_status | string | Status |
delivery_status | string | Delivery status |
usage_data | object | LLM usage (outbound only) |
tools_called | array | Tools executed (outbound only) |
The full_conversation array is unique to SMS webhooks and provides complete conversation context for each event.