Send SMS - Burki Voice AI Docs

This endpoint allows you to send SMS messages through one of your AI assistants. The system automatically determines which telephony provider (Twilio, Telnyx, or Vonage) to use based on the assistant configuration associated with the from_phone_number.

How It Works

Assistant Lookup: The system identifies the assistant based on the from_phone_number
Provider Selection: Automatically uses the assistant’s configured telephony provider
Queue or Send: Either queues the message (with rate limiting) or sends immediately
Response: Returns success status with message ID, provider, and delivery status

Multi-Provider Support: Your assistants can use different telephony providers. The system automatically routes SMS messages through the correct provider based on which assistant owns the phone number.

Request Body

Parameter	Type	Required	Description
`from_phone_number`	string	Yes	Sender phone number (must be assigned to an assistant)
`to_phone_number`	string	Yes	Recipient phone number in E.164 format
`message`	string	Yes	SMS message content (max 1600 characters)
`media_urls`	array	No	List of media URLs for MMS messages
`queue`	boolean	No	If `true` (default), queue with rate limiting. If `false`, send immediately
`idempotency_key`	string	No	Unique key to prevent duplicate sends on retries (max 256 chars)

Basic Request

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Hello! This is a follow-up message from your AI assistant."
}

With All Options

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Hello! This is a follow-up message from your AI assistant.",
  "media_urls": ["https://example.com/image.jpg"],
  "queue": false,
  "idempotency_key": "order:12345:confirmation"
}

Queue vs Immediate Send

Queued (Default)
Immediate

When queue: true (default):

Messages are queued and sent with rate limiting
Helps avoid carrier throttling
Better for bulk sends
Returns status: "queued"

{
  "queue": true
}

When queue: false:

Message is sent immediately
Better for time-sensitive messages
May hit rate limits if sending many messages
Returns status: "sent" or status: "failed"

{
  "queue": false
}

Idempotency

The idempotency_key parameter prevents duplicate messages when retrying failed requests:

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Your order #12345 has shipped!",
  "idempotency_key": "order:12345:shipped:notification"
}

Header Alternative: You can also provide the idempotency key via the Idempotency-Key header. If both are provided, the header takes precedence.

Response

A successful request returns a 200 OK status with details about the message.

{
  "success": true,
  "message_id": "SM1234567890abcdef",
  "message": "SMS queued successfully via telnyx",
  "provider": "telnyx",
  "status": "queued"
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the operation was successful
`message_id`	string	Unique identifier for the message
`message`	string	Human-readable status message
`provider`	string	Telephony provider used (`twilio`, `telnyx`, or `vonage`)
`status`	string	Delivery status: `queued`, `sent`, or `failed`

Error Responses

400 Bad Request

Returned when the request is malformed or contains invalid data.

{
  "detail": "Invalid to_phone_number format. Use E.164 format (e.g., +1234567890)"
}

Common causes:

Missing required fields (from_phone_number, to_phone_number, message)
Invalid phone number format (must be E.164)
Empty message content
Message exceeds 1600 characters

404 Not Found

Returned when no assistant is found for the specified from_phone_number.

{
  "detail": "No assistant found for phone number +1234567890"
}

500 Internal Server Error

Returned when the telephony provider fails to send the message.

{
  "detail": "Failed to send SMS via telnyx"
}

Use Cases

Customer Service Follow-up

Send follow-up messages after customer service calls:

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Thanks for calling! Here's the link we discussed: https://support.example.com/article/123",
  "queue": false
}

Appointment Reminders

Send automated appointment reminders with idempotency:

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Reminder: Your appointment is tomorrow at 2:00 PM. Reply CONFIRM to confirm or RESCHEDULE to change the time.",
  "idempotency_key": "appointment:456:reminder:24h"
}

Bulk Notifications (Queued)

For sending many messages, use the queue to avoid rate limits:

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Flash sale! 50% off all items today only. Shop now: example.com/sale",
  "queue": true
}

Send documents or images via MMS:

{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Here are the documents you requested:",
  "media_urls": [
    "https://yourdomain.com/documents/contract.pdf",
    "https://yourdomain.com/images/diagram.png"
  ]
}

Authentication

This endpoint requires authentication. Include your API key in the request headers:

curl -X POST "https://api.burki.dev/sms/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number": "+1234567890",
    "to_phone_number": "+1555123456",
    "message": "Hello from your AI assistant!"
  }'

Rate Limits

SMS sending is subject to rate limits imposed by the underlying telephony providers:

Twilio: Varies by account type and message volume
Telnyx: Varies by account configuration
Vonage: Varies by account type

Provider Limits: Each telephony provider has its own rate limits and restrictions. Use the queue: true option (default) to let Burki handle rate limiting automatically.

Best Practices

Phone Number Format

Always use E.164 format for phone numbers:

Correct: +1234567890
Incorrect: (123) 456-7890, 123-456-7890, 1234567890

Idempotency Keys

Use meaningful idempotency keys that include:

The type of message (e.g., order, appointment, alert)
A unique identifier (e.g., order ID, appointment ID)
The specific action (e.g., confirmation, reminder)

Examples:

order:12345:confirmation
appointment:789:reminder:24h
chat:session123:msg:456:outbound

Message Content

Keep messages concise and clear
Include clear call-to-action when needed
Respect opt-out requests and regulatory requirements
Consider character limits for international SMS

Error Handling

Always handle potential errors in your code:

import requests

response = requests.post(
    "https://api.burki.dev/sms/send",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "from_phone_number": "+1234567890",
        "to_phone_number": "+1555123456",
        "message": "Hello from your AI assistant!",
        "idempotency_key": "test:123:hello"
    }
)

if response.status_code == 200:
    data = response.json()
    print(f"SMS {data['status']} via {data['provider']}")
    print(f"Message ID: {data['message_id']}")
else:
    print(f"Error: {response.status_code} - {response.json()['detail']}")

Integration Examples

Node.js

const axios = require('axios');

async function sendSMS(fromPhone, toPhone, message, options = {}) {
  try {
    const response = await axios.post('https://api.burki.dev/sms/send', {
      from_phone_number: fromPhone,
      to_phone_number: toPhone,
      message: message,
      queue: options.queue ?? true,
      idempotency_key: options.idempotencyKey
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log(`SMS ${response.data.status}:`, response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to send SMS:', error.response.data);
    throw error;
  }
}

// Usage
sendSMS('+1234567890', '+1555123456', 'Hello!', {
  queue: false,
  idempotencyKey: 'test:123'
});

Python

import requests

def send_sms(from_phone, to_phone, message, media_urls=None, queue=True, idempotency_key=None):
    url = "https://api.burki.dev/sms/send"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {
        "from_phone_number": from_phone,
        "to_phone_number": to_phone,
        "message": message,
        "queue": queue
    }
    
    if media_urls:
        payload["media_urls"] = media_urls
    
    if idempotency_key:
        payload["idempotency_key"] = idempotency_key
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"SMS failed: {response.json()['detail']}")

# Usage
result = send_sms(
    "+1234567890",
    "+1555123456",
    "Your order has shipped!",
    idempotency_key="order:789:shipped"
)
print(f"Status: {result['status']}")

PHP

<?php
function sendSMS($fromPhone, $toPhone, $message, $options = []) {
    $url = 'https://api.burki.dev/sms/send';
    $headers = [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ];
    
    $data = [
        'from_phone_number' => $fromPhone,
        'to_phone_number' => $toPhone,
        'message' => $message,
        'queue' => $options['queue'] ?? true
    ];
    
    if (isset($options['media_urls'])) {
        $data['media_urls'] = $options['media_urls'];
    }
    
    if (isset($options['idempotency_key'])) {
        $data['idempotency_key'] = $options['idempotency_key'];
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("SMS failed: " . $response);
    }
}
?>

API Documentation

Assistants

Assistant Phone Numbers

Assistant Documents (RAG)

Voice Cloning

Calls

Messaging

Phone Number Management

Call Data

Organization

Webhooks & System

Campaigns

WebSockets

Tools & Custom Actions

Assistant Graphs

​How It Works

​Request Body

​Basic Request

​With All Options

​Queue vs Immediate Send

​Idempotency

​Response

​Response Fields

​Error Responses

​400 Bad Request

​404 Not Found

​500 Internal Server Error

​Use Cases

​Customer Service Follow-up

​Appointment Reminders

​Bulk Notifications (Queued)

​Document Sharing (MMS)

​Authentication

​Rate Limits

​Best Practices

​Phone Number Format

​Idempotency Keys

​Message Content

​Error Handling

​Integration Examples

​Node.js

​Python

​PHP

How It Works

Request Body

Basic Request

With All Options

Queue vs Immediate Send

Idempotency

Response

Response Fields

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Use Cases

Customer Service Follow-up

Appointment Reminders

Bulk Notifications (Queued)

Document Sharing (MMS)

Authentication

Rate Limits

Best Practices

Phone Number Format

Idempotency Keys

Message Content

Error Handling

Integration Examples

Node.js

Python

PHP