> ## 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.
# Initiate Outbound Call
> Initiates an outbound call from an assistant to a specified phone number.
This endpoint is protected and requires authentication.
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)
```json Request theme={null}
{
"from_phone_number": "+15551234567",
"to_phone_number": "+15559876543"
}
```
### Call with Custom Message and Variables
```json Request theme={null}
{
"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:
```json Request theme={null}
{
"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.
```json Response theme={null}
{
"message": "Call initiated successfully",
"call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```
## Error Responses
### 400 Bad Request
Returned when required parameters are missing or invalid.
```json theme={null}
{
"detail": "from_phone_number is required"
}
```
### 402 Payment Required
Returned when your organization has insufficient funds.
```json theme={null}
{
"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.
```json theme={null}
{
"detail": "Unauthorized: phone number +15551234567 does not belong to your organization"
}
```
### 404 Not Found
Returned when no assistant can be resolved for the call.
```json theme={null}
{
"detail": "No assistant found for phone number +15551234567"
}
```
## OpenAPI
````yaml POST /calls/initiate
openapi: 3.1.0
info:
title: Burki
description: A system that uses AI to answer customer Calls.
version: 0.1.0
servers: []
security: []
paths:
/calls/initiate:
post:
summary: Initiate Outbound Call
description: >-
Initiates an outbound call from an assistant to a specified phone
number.
This endpoint is protected and requires authentication.
operationId: initiate_outbound_call_calls_initiate_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateCallRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateCallResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
InitiateCallRequest:
properties:
to_phone_number:
type: string
title: To Phone Number
welcome_message:
anyOf:
- type: string
- type: 'null'
title: Welcome Message
agenda:
anyOf:
- type: string
- type: 'null'
title: Agenda
from_phone_number:
anyOf:
- type: string
- type: 'null'
title: From Phone Number
assistant_id:
anyOf:
- type: integer
- type: 'null'
title: Assistant Id
description: >-
Optional: Override the default assistant attached to the phone
number. If not provided, uses the assistant assigned to
from_phone_number.
variables:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Variables
description: >-
Custom variables for template substitution in welcome_message and
agenda using {{variable}} syntax
type: object
required:
- to_phone_number
title: InitiateCallRequest
description: Request model for initiating an outbound call.
InitiateCallResponse:
properties:
message:
type: string
title: Message
call_sid:
type: string
title: Call Sid
type: object
required:
- message
- call_sid
title: InitiateCallResponse
description: Response model for initiating an outbound call.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````