​
Overview

When an SMS is received by your assistant’s phone number, Burki can forward the SMS data to your configured webhook URL. This allows you to integrate SMS functionality into your applications.

​
Webhook Configuration

To receive SMS webhooks, configure the sms_webhook_url field when creating or updating an assistant. For Twilio, you can also optionally specify a messaging_service_sid: 
const response = await fetch('https://api.burki.ai/api/v1/assistants', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "SMS Assistant",
    sms_webhook_url: "https://your-app.com/webhooks/sms",
    messaging_service_sid: "MG1234567890abcdef1234567890abcdef", // Optional: Twilio Messaging Service SID
    // ... other assistant configuration
  })
});

​
Webhook Payload

When an SMS is received, Burki sends a POST request to your sms_webhook_url with the following payload: 
{
  "type": "sms_received",
  "timestamp": "2024-01-15T10:30:00.123456",
  "data": {
    "message_id": "SM123abc...",
    "from": "+1234567890",
    "to": "+1987654321", 
    "body": "Hello, this is a test message",
    "media_urls": ["https://example.com/image.jpg"],
    "provider": "twilio"
  }
}

​
Payload Fields

FieldTypeDescription
typestringAlways "sms_received" for incoming SMS
timestampstringISO 8601 timestamp when the webhook was sent
data.message_idstringUnique identifier for the SMS message
data.fromstringPhone number that sent the SMS (E.164 format)
data.tostringPhone number that received the SMS (your assistant’s number)
data.bodystringText content of the SMS message
data.media_urlsarrayURLs of any media attachments (MMS)
data.providerstringTelephony provider ("twilio" or "telnyx")

​
Provider Support

SMS webhooks work with both supported telephony providers:
  • Twilio: Receives webhooks at /twilio-sms-webhook
  • Telnyx: Receives webhooks at /telnyx-webhook (shared with voice events)
The payload format is normalized between providers, so your webhook handler works regardless of the underlying provider.

​
Webhook Requirements

​
Response

Your webhook endpoint should respond with:
  • Status Code: 200 (OK)
  • Response Time: Under 10 seconds
  • Body: Any response body is acceptable

​
Security

  • HTTPS Required: Your webhook URL must use HTTPS
  • User-Agent: Webhooks are sent with User-Agent: Burki-SMS-Webhook/1.0
  • Timeout: Requests timeout after 10 seconds

​
Example Implementation

app.post('/webhooks/sms', express.json(), (req, res) => {
  const { type, timestamp, data } = req.body;
  
  if (type === 'sms_received') {
    console.log(`SMS from ${data.from} to ${data.to}: ${data.body}`);
    
    // Process the SMS message
    if (data.body.toLowerCase().includes('help')) {
      // Send response SMS via Burki API
      sendResponseSMS(data.from, "How can I help you?");
    }
    
    // Handle media attachments
    if (data.media_urls.length > 0) {
      console.log(`Received ${data.media_urls.length} media attachments`);
    }
  }
  
  res.status(200).send('OK');
});

​
Troubleshooting

​
Common Issues

  1. No webhooks received
    • Verify sms_webhook_url is set on your assistant
    • Check that your endpoint is publicly accessible
    • Ensure your server responds with 200 status
  2. Webhooks timing out
    • Your endpoint must respond within 10 seconds
    • Consider processing SMS asynchronously
  3. Missing SMS messages
    • Verify your assistant’s phone number is correctly configured
    • Check that SMS capabilities are enabled on your phone number

​
Testing

You can test your SMS webhook by:
  1. Sending an SMS to your assistant’s phone number
  2. Checking your webhook endpoint logs
  3. Using the live transcript WebSocket to monitor events

​
Next Steps