Skip to main content
POST
/
calls
/
initiate
{
  "message": "<string>",
  "call_sid": "<string>"
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
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 | null

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