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.

This endpoint is used to programmatically initiate an outbound call from one of your AI assistants to an external phone number. It is a system endpoint that you call from your own application logic, not a webhook for an external service. When you call this endpoint, Burki instructs your telephony provider (Twilio, Telnyx, or Vonage) to place a call. The provider then makes a request to your webhook, passing along the parameters you provide here as metadata. This allows the system to route the call to the correct assistant and begin the conversation.
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

The request body is a JSON object specifying the details of the outbound call.

​
Required Parameters

  • from_phone_number (string, required): The phone number to call from, in E.164 format. This number must be assigned to an assistant or ConversationFlow in your organization.
  • to_phone_number (string, required): The destination phone number to call, in E.164 format.

​
Optional Parameters

  • assistant_id (integer, optional): Override the default assistant attached to the phone number. If not provided, the system uses the assistant assigned to from_phone_number.
  • welcome_message (string, optional): A custom welcome message for the assistant to say at the beginning of the call. If not provided, the assistant’s default greeting will be used. Supports variable substitution using {{variable}} syntax.
  • agenda (string, optional): A specific topic or goal for the call. This can be used to guide the assistant’s conversation. Supports variable substitution using {{variable}} syntax.
  • variables (object, optional): A dictionary of custom variables for template substitution in the welcome_message and agenda. Variables can be referenced using double curly brackets, e.g., {{name}}, {{company}}, etc.

​
Assistant Resolution Logic

The system determines which assistant handles the call using the following priority:
  1. If assistant_id is provided: Use the specified assistant (must belong to your organization)
  2. If from_phone_number is assigned to a ConversationFlow: Use the flow’s base assistant and live flow runtime
  3. If from_phone_number is assigned to an assistant: Use that assistant
If no assistant can be resolved through the above logic, the request will fail with a 404 error.

​
Examples

​
Basic Call (Using Phone Number’s Default Assistant)

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

​
Call with Custom Message and Variables

Request
{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "welcome_message": "Hello {{name}}, this is a reminder about your appointment tomorrow at {{time}}.",
  "agenda": "Remind {{name}} about their upcoming {{appointment_type}} appointment.",
  "variables": {
    "name": "John Doe",
    "time": "10 AM",
    "appointment_type": "dental"
  }
}

​
Call with Assistant Override

Use a different assistant than the one assigned to the phone number:
Request
{
  "from_phone_number": "+15551234567",
  "to_phone_number": "+15559876543",
  "assistant_id": 456,
  "welcome_message": "Hi there! I'm calling about your recent inquiry."
}

​
Response

A successful request will return a 200 OK status with a JSON object containing the call_sid from your telephony provider, confirming that the call has been initiated.
Response
{
  "message": "Call initiated successfully",
  "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

​
Error Responses

​
400 Bad Request

Returned when required parameters are missing or invalid. 
{
  "detail": "from_phone_number is required"
}

​
402 Payment Required

Returned when your organization has insufficient funds. 
{
  "detail": "Insufficient balance. Please add funds to continue making calls."
}

​
403 Forbidden

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

​
404 Not Found

Returned when no assistant can be resolved for the call. 
{
  "detail": "No assistant found for phone number +15551234567"
}

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