Skip to main content
POST
/
calls
/
initiate
{
  "message": "<string>",
  "call_sid": "<string>"
}

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.

Programmatically initiate an outbound call from one of your AI assistants to a phone number. This is one of the most powerful features of Burki - it allows you to trigger AI-powered outbound calls from your application logic, enabling use cases like appointment reminders, lead follow-ups, and proactive customer outreach.

​
How It Works

  1. You send a request with the source phone number, destination number, and optional customization
  2. Burki resolves the assistant based on your parameters
  3. The call is placed through your configured telephony provider (Twilio, Telnyx, Vonage, or SIP)
  4. Your AI assistant handles the conversation automatically
Multi-Provider Support: This endpoint works with Twilio, Telnyx, Vonage, and BYO SIP Trunk. The system automatically uses the provider configured for the specified from_phone_number.

​
Request Body

ParameterTypeRequiredDescription
from_phone_numberstringYesPhone number to call from (E.164 format). Must be assigned to an assistant or ConversationFlow in your organization.
to_phone_numberstringYesDestination phone number (E.164 format).
assistant_idintegerNoOverride the default assistant. If not provided, uses the assistant assigned to from_phone_number.
welcome_messagestringNoCustom greeting for this call. Supports {{variable}} template syntax.
agendastringNoCall objective/context for the AI. Supports {{variable}} template syntax.
variablesobjectNoKey-value pairs for template substitution in welcome_message and agenda.

​
Assistant Resolution

The system determines which assistant handles the call:
  1. If assistant_id is provided: Uses that specific assistant
  2. If phone number has a ConversationFlow: Uses the flow’s base assistant and live flow runtime
  3. If phone number has a direct assistant: Uses the assigned assistant

​
Examples

​
Minimal Request

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543"
}

​
With Custom Welcome Message

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "welcome_message": "Hi! This is Sarah from Acme Corp calling about your recent inquiry."
}

​
With Template Variables

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "welcome_message": "Hello {{name}}, this is a reminder about your {{appointment_type}} appointment tomorrow at {{time}}.",
  "agenda": "Confirm the appointment with {{name}} and answer any questions they have.",
  "variables": {
    "name": "John Smith",
    "appointment_type": "dental cleaning",
    "time": "2:30 PM"
  }
}

​
With Assistant Override

{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "assistant_id": 456,
  "welcome_message": "Hi there! I'm calling from our sales team."
}

​
Response

{
  "message": "Call initiated successfully",
  "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
FieldTypeDescription
messagestringStatus message
call_sidstringUnique identifier for the call from your telephony provider

​
Error Responses

​
400 Bad Request

Missing or invalid parameters. 
{
  "detail": "from_phone_number is required"
}

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

​
402 Payment Required

Insufficient account balance. 
{
  "detail": "Insufficient balance. Please add funds to continue making calls."
}

​
403 Forbidden

Phone number or assistant doesn’t belong to your organization. 
{
  "detail": "Unauthorized: phone number +15551234567 does not belong to your organization"
}

​
404 Not Found

No assistant found for the phone number. 
{
  "detail": "No assistant found for phone number +15551234567"
}

​
Use Cases

​
Appointment Reminders

import requests

def send_appointment_reminder(patient_phone, patient_name, appointment_time, appointment_type):
    response = requests.post(
        "https://api.burki.dev/calls/initiate",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "from_phone_number": "+15551234567",
            "to_phone_number": patient_phone,
            "welcome_message": "Hello {{name}}, this is a friendly reminder about your {{type}} appointment scheduled for {{time}}.",
            "agenda": "Confirm the appointment, offer rescheduling if needed, and answer any questions.",
            "variables": {
                "name": patient_name,
                "type": appointment_type,
                "time": appointment_time
            }
        }
    )
    return response.json()

​
Lead Follow-up

const axios = require('axios');

async function followUpWithLead(leadPhone, leadName, productInterest) {
  const response = await axios.post('https://api.burki.dev/calls/initiate', {
    from_phone_number: '+15551234567',
    to_phone_number: leadPhone,
    welcome_message: `Hi {{name}}! I'm following up on your interest in our {{product}}.`,
    agenda: 'Qualify the lead, answer questions about the product, and schedule a demo if interested.',
    variables: {
      name: leadName,
      product: productInterest
    }
  }, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  
  return response.data;
}

​
Bulk Outreach with Campaign

For large-scale outbound calling, consider using the Campaigns API which provides scheduling, retry logic, and analytics.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for initiating an outbound call.

​
to_phone_number
string
required
​
welcome_message
string | null
​
agenda
string | null
​
from_phone_number
string | null
​
assistant_id
integer | null

Optional: Override the default assistant attached to the phone number. If not provided, uses the assistant assigned to from_phone_number.

​
variables
Variables · object

Custom variables for template substitution in welcome_message and agenda using {{variable}} syntax

Response

Successful Response

Response model for initiating an outbound call.

​
message
string
required
​
call_sid
string
required