Skip to main content

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:

Webhook Payload

When an SMS is received, Burki sends a POST request to your sms_webhook_url with the following payload:

Payload Fields

Provider Support

Provider webhooks are received by Burki at canonical unified endpoints:
  • Twilio: POST /webhooks/sms/twilio
  • Telnyx: POST /webhooks/sms/telnyx
  • Vonage: POST or GET /webhooks/sms/vonage
Legacy aliases remain available for existing provider configurations:
  • /twilio-sms-webhook
  • /telnyx-sms-webhook
  • /vonage-sms-webhook
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

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