Skip to main content
POST
/
messaging
/
sms
/
receive
curl -X POST https://api.avoca.ai/v1/messaging/sms/receive \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+13105551234",
    "to": "+13105556789",
    "body": "I need to reschedule my appointment tomorrow",
    "messageId": "SM123456789",
    "timestamp": "2024-01-20T10:30:00Z",
    "metadata": {
      "segments": 1,
      "fromCity": "Los Angeles",
      "fromState": "CA"
    }
  }'

{
  "success": true,
  "action": "auto_reply",
  "reply": {
    "message": "I can help you reschedule your appointment. What day and time would work better for you? You can reply with options like 'Monday morning' or 'Tuesday afternoon'.",
    "delay_seconds": 2
  },
  "data": {
    "conversation_id": "conv_sms_789",
    "customer_id": "cust_456",
    "intent": "reschedule_request",
    "appointment_id": "appt_123"
  }
}
This webhook endpoint processes incoming SMS messages from customers. Configure your SMS provider (e.g., Twilio) to forward messages to this endpoint.

​
Webhook Payload

​
from
string
required
Sender’s phone number in E.164 format (e.g., +13105551234)
​
to
string
required
Recipient phone number (your Avoca number)
​
body
string
required
The text content of the SMS message
​
messageId
string
required
Unique identifier from the SMS provider
​
timestamp
string
required
ISO 8601 timestamp when message was received
​
media
array
Array of media attachments (MMS)
​
metadata
object
Additional provider-specific metadata

​
Response

The webhook should return a response indicating how to handle the message.
​
success
boolean
Whether the message was processed successfully
​
action
string
Action taken on the message:
  • auto_reply - AI will respond automatically
  • create_ticket - Create ServiceTitan ticket
  • forward - Forward to human agent
  • ignore - No action needed
​
reply
object
Auto-reply configuration if applicable
​
data
object
Processing results
curl -X POST https://api.avoca.ai/v1/messaging/sms/receive \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+13105551234",
    "to": "+13105556789",
    "body": "I need to reschedule my appointment tomorrow",
    "messageId": "SM123456789",
    "timestamp": "2024-01-20T10:30:00Z",
    "metadata": {
      "segments": 1,
      "fromCity": "Los Angeles",
      "fromState": "CA"
    }
  }'

{
  "success": true,
  "action": "auto_reply",
  "reply": {
    "message": "I can help you reschedule your appointment. What day and time would work better for you? You can reply with options like 'Monday morning' or 'Tuesday afternoon'.",
    "delay_seconds": 2
  },
  "data": {
    "conversation_id": "conv_sms_789",
    "customer_id": "cust_456",
    "intent": "reschedule_request",
    "appointment_id": "appt_123"
  }
}

​
Common SMS Intents

The system automatically detects and handles common SMS intents:
IntentKeywordsAction
Confirmation”confirm”, “yes”, “y”Confirm appointment
Reschedule”reschedule”, “change time”Start reschedule flow
Cancel”cancel”, “can’t make it”Cancel appointment
Emergency”emergency”, “urgent”, “asap”Priority routing
Stop”stop”, “unsubscribe”Opt-out handling
Help”help”, “info”Send help message