Initiate Outbound Call
curl --request POST \
--url https://api.example.com/calls/initiate \
--header 'Content-Type: application/json' \
--data '
{
"assistant_id": 123,
"to_phone_number": "<string>",
"welcome_message": "<string>",
"agenda": "<string>"
}
'import requests
url = "https://api.example.com/calls/initiate"
payload = {
"assistant_id": 123,
"to_phone_number": "<string>",
"welcome_message": "<string>",
"agenda": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
assistant_id: 123,
to_phone_number: '<string>',
welcome_message: '<string>',
agenda: '<string>'
})
};
fetch('https://api.example.com/calls/initiate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/calls/initiate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'assistant_id' => 123,
'to_phone_number' => '<string>',
'welcome_message' => '<string>',
'agenda' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/calls/initiate"
payload := strings.NewReader("{\n \"assistant_id\": 123,\n \"to_phone_number\": \"<string>\",\n \"welcome_message\": \"<string>\",\n \"agenda\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/calls/initiate")
.header("Content-Type", "application/json")
.body("{\n \"assistant_id\": 123,\n \"to_phone_number\": \"<string>\",\n \"welcome_message\": \"<string>\",\n \"agenda\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/calls/initiate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"assistant_id\": 123,\n \"to_phone_number\": \"<string>\",\n \"welcome_message\": \"<string>\",\n \"agenda\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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
Initiate Outbound Call
curl --request POST \
--url https://api.example.com/calls/initiate \
--header 'Content-Type: application/json' \
--data '
{
"assistant_id": 123,
"to_phone_number": "<string>",
"welcome_message": "<string>",
"agenda": "<string>"
}
'import requests
url = "https://api.example.com/calls/initiate"
payload = {
"assistant_id": 123,
"to_phone_number": "<string>",
"welcome_message": "<string>",
"agenda": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
assistant_id: 123,
to_phone_number: '<string>',
welcome_message: '<string>',
agenda: '<string>'
})
};
fetch('https://api.example.com/calls/initiate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/calls/initiate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'assistant_id' => 123,
'to_phone_number' => '<string>',
'welcome_message' => '<string>',
'agenda' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/calls/initiate"
payload := strings.NewReader("{\n \"assistant_id\": 123,\n \"to_phone_number\": \"<string>\",\n \"welcome_message\": \"<string>\",\n \"agenda\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/calls/initiate")
.header("Content-Type", "application/json")
.body("{\n \"assistant_id\": 123,\n \"to_phone_number\": \"<string>\",\n \"welcome_message\": \"<string>\",\n \"agenda\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/calls/initiate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"assistant_id\": 123,\n \"to_phone_number\": \"<string>\",\n \"welcome_message\": \"<string>\",\n \"agenda\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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, it instructs Twilio to place a call. Twilio then makes a request to your
/twiml 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.
Request Body
The request body is a JSON object specifying the details of the outbound call.assistant_id(integer, required): The ID of the assistant that should make the call.to_phone_number(string, required): The destination phone number to call, in E.164 format.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.agenda(string, optional): A specific topic or goal for the call. This can be used to guide the assistant’s conversation.
Request
{
"assistant_id": 123,
"to_phone_number": "+15559876543",
"welcome_message": "Hello, this is a reminder about your appointment tomorrow at 10 AM.",
"agenda": "Remind the user about their upcoming appointment."
}
Response
A successful request will return a200 OK status with a JSON object containing the call_sid from Twilio, confirming that the call has been initiated.
Response
{
"message": "Call initiated successfully",
"call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}