{
"message": "<string>",
"call_sid": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Webhooks & System
Initiate Outbound Call
Initiates an outbound call from an assistant to a specified phone number. This endpoint is protected and requires authentication.
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 tofrom_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 thewelcome_messageandagenda. 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:- If
assistant_idis provided: Use the specified assistant (must belong to your organization) - If
from_phone_numberis assigned to a ConversationFlow: Use the flow’s base assistant and live flow runtime - If
from_phone_numberis 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 a200 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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Request model for initiating an outbound call.
Optional: Override the default assistant attached to the phone number. If not provided, uses the assistant assigned to from_phone_number.
Custom variables for template substitution in welcome_message and agenda using {{variable}} syntax
⌘I