Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.burki.dev/llms.txt

Use this file to discover all available pages before exploring further.

SMS Messaging

Send text messages and multimedia content through your AI assistants using Twilio, Telnyx, or Vonage

Overview

The messaging system allows your AI assistants to send SMS and MMS messages to customers and users. The platform supports Twilio, Telnyx, and Vonage, automatically selecting the provider from the sending phone number’s configured provider.

Key Features

Multi-Provider Support

Send through Twilio, Telnyx, or Vonage based on the provider attached to the sending phone number

MMS Support

Send images, documents, and other media files alongside text messages

Assistant-Based Routing

Messages are automatically routed through the correct provider based on the sending assistant

E.164 Validation

Automatic phone number format validation ensures reliable delivery

How It Works

The messaging system follows a simple but powerful flow:
  1. Assistant Lookup: The system identifies which assistant owns the from_phone_number
  2. Provider Selection: Determines whether to use Twilio, Telnyx, or Vonage from the sender phone number’s provider configuration
  3. Message Delivery: Sends the message through the appropriate provider’s API
  4. Response: Returns confirmation with message ID and provider information

Provider Configuration

Per-Assistant Providers

Each assistant can be configured with different telephony providers:
{
  "assistant_id": 123,
  "name": "Customer Service Bot",
  "telnyx_config": {
    "api_key": "KEY_xxxx",
    "connection_id": "xxxx-xxxx-xxxx"
  },
  "twilio_config": {
    "account_sid": "ACxxxx",
    "auth_token": "xxxx"
  }
}

Provider Selection

The provider is determined by the owned phone number used as from_phone_number. If the number is a Telnyx number, Burki sends through Telnyx; if it is a Twilio or Vonage number, Burki uses that provider. This avoids guessing based on which credentials are present.

Supported Message Types

SMS (Text Messages)

Send plain text messages up to 1600 characters:
{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Your appointment is confirmed for tomorrow at 2 PM."
}

MMS (Multimedia Messages)

Send images, documents, and other media files:
{
  "from_phone_number": "+1234567890",
  "to_phone_number": "+1555123456",
  "message": "Here are your test results:",
  "media_urls": [
    "https://yourdomain.com/results.pdf",
    "https://yourdomain.com/chart.png"
  ]
}

Use Cases

Customer Service

Send follow-up messages after customer service calls with links to resources, ticket numbers, or additional information.
Automated appointment reminders with confirmation options and rescheduling links.
Shipping notifications, delivery confirmations, and order status updates.
Share troubleshooting guides, user manuals, and how-to videos via MMS.

Sales & Marketing

Personalized follow-up messages after sales calls with proposals and pricing information.
Send event invitations, webinar links, and calendar attachments.
Share product announcements, feature updates, and release notes.
Special offers, discount codes, and promotional materials (with proper consent).

Healthcare

Appointment confirmations and pre-visit instructions for healthcare workflows. Use a signed BAA and avoid sending PHI unless your full deployment is configured for the required compliance posture.
Automated medication reminders and refill notifications.
Secure delivery of test results and lab reports via encrypted links.
Personalized health tips and wellness recommendations.

Integration Patterns

Post-Call Follow-up

Automatically send follow-up messages after calls end:
# After a call ends, send follow-up SMS
async def handle_call_end(call_sid, assistant_id, customer_phone):
    # Get call summary or transcript
    summary = await get_call_summary(call_sid)
    
    # Send follow-up SMS
    response = await send_sms({
        "from_phone_number": assistant.phone_number,
        "to_phone_number": customer_phone,
        "message": f"Thanks for calling! Summary: {summary}. Questions? Reply to this message."
    })

Scheduled Messaging

Set up scheduled messaging workflows:
# Schedule appointment reminder
import schedule
import time

def send_appointment_reminder():
    appointments = get_upcoming_appointments()
    
    for appointment in appointments:
        send_sms({
            "from_phone_number": appointment.assistant_phone,
            "to_phone_number": appointment.customer_phone,
            "message": f"Reminder: Your appointment is tomorrow at {appointment.time}"
        })

# Run every day at 6 PM
schedule.every().day.at("18:00").do(send_appointment_reminder)

Interactive Workflows

Create two-way messaging workflows:
# Handle normalized Burki SMS webhook payloads sent to your assistant's sms_webhook_url
@app.post("/webhooks/sms")
async def handle_incoming_sms(request):
    payload = await request.json()
    if payload.get("type") != "sms_received":
        return {"ok": True}

    sms_data = payload["data"]
    message = sms_data["body"].lower()
    from_phone = sms_data["from"]
    
    if 'confirm' in message:
        await send_sms({
            "from_phone_number": ASSISTANT_PHONE,
            "to_phone_number": from_phone,
            "message": "Your appointment is confirmed! See you tomorrow."
        })
    elif 'reschedule' in message:
        await send_sms({
            "from_phone_number": ASSISTANT_PHONE,
            "to_phone_number": from_phone,
            "message": "Please call us at (555) 123-4567 to reschedule."
        })

Best Practices

Compliance & Regulations

Regulatory Compliance: Always ensure compliance with local regulations like TCPA (US), GDPR (EU), and CASL (Canada) when sending SMS messages.
  • Opt-in Required: Only send messages to users who have explicitly opted in
  • Opt-out Mechanism: Always provide a way for users to unsubscribe (e.g., “Reply STOP to opt out”)
  • Business Hours: Respect time zones and send messages during appropriate hours
  • Content Guidelines: Follow carrier guidelines for message content and frequency

Message Optimization

  • Keep It Concise: SMS works best with short, clear messages
  • Include CTAs: Provide clear next steps or calls to action
  • Personalization: Use customer names and relevant context
  • Timing: Send messages at appropriate times based on user preferences

Error Handling

Always implement proper error handling:
try:
    response = await send_sms(message_data)
    logger.info(f"SMS sent successfully: {response['message_id']}")
except HTTPException as e:
    if e.status_code == 404:
        logger.error("Assistant not found for phone number")
    elif e.status_code == 400:
        logger.error("Invalid phone number format")
    else:
        logger.error(f"SMS failed: {e.detail}")

Rate Limiting

Be mindful of rate limits:
  • Twilio: Varies by account type and sender setup
  • Telnyx: Varies by account configuration
  • Vonage: Varies by account type and sender setup
  • Best Practice: Implement queuing for high-volume scenarios

Getting Started

1

Configure Your Assistant

Set up your assistant with Twilio, Telnyx, or Vonage credentials in the dashboard.
2

Assign Phone Numbers

Assign phone numbers to your assistants that will be used as sender numbers.
3

Send Your First SMS

Use the /sms/send endpoint to send your first message.
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!"
  }'
4

Handle Responses

Implement proper error handling and response processing in your application.

Next Steps

API Reference

Detailed API documentation for the SMS endpoint

SMS Conversations

Conversation, session, export, and archive APIs

SMS Logs

Delivery logs, stats, and debug timelines

SMS Compliance

Verify SMS use cases and outbound eligibility

SMS 10DLC

Carrier campaign helpers for Telnyx, Twilio, and Vonage

Telephony Providers

Learn about configuring Twilio, Telnyx, and Vonage providers

Webhooks

Set up webhooks to handle incoming SMS responses

Phone Numbers

Manage phone numbers for your assistants