Create realtime session
curl --request POST \
--url https://app.autocalls.ai/api/user/realtime/session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"assistant_id": "<string>",
"variables": {},
"external_identifier": "<string>"
}
'import requests
url = "https://app.autocalls.ai/api/user/realtime/session"
payload = {
"assistant_id": "<string>",
"variables": {},
"external_identifier": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({assistant_id: '<string>', variables: {}, external_identifier: '<string>'})
};
fetch('https://app.autocalls.ai/api/user/realtime/session', 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://app.autocalls.ai/api/user/realtime/session",
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' => '<string>',
'variables' => [
],
'external_identifier' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://app.autocalls.ai/api/user/realtime/session"
payload := strings.NewReader("{\n \"assistant_id\": \"<string>\",\n \"variables\": {},\n \"external_identifier\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://app.autocalls.ai/api/user/realtime/session")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"assistant_id\": \"<string>\",\n \"variables\": {},\n \"external_identifier\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.autocalls.ai/api/user/realtime/session")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"assistant_id\": \"<string>\",\n \"variables\": {},\n \"external_identifier\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"url": "<string>",
"token": "<string>",
"expires_in": 123,
"success": true,
"error": "<string>",
"error_code": "<string>"
}Realtime
Create realtime session
Mint a short-lived url and token so a browser can start a realtime voice session with an assistant
POST
/
user
/
realtime
/
session
Create realtime session
curl --request POST \
--url https://app.autocalls.ai/api/user/realtime/session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"assistant_id": "<string>",
"variables": {},
"external_identifier": "<string>"
}
'import requests
url = "https://app.autocalls.ai/api/user/realtime/session"
payload = {
"assistant_id": "<string>",
"variables": {},
"external_identifier": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({assistant_id: '<string>', variables: {}, external_identifier: '<string>'})
};
fetch('https://app.autocalls.ai/api/user/realtime/session', 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://app.autocalls.ai/api/user/realtime/session",
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' => '<string>',
'variables' => [
],
'external_identifier' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://app.autocalls.ai/api/user/realtime/session"
payload := strings.NewReader("{\n \"assistant_id\": \"<string>\",\n \"variables\": {},\n \"external_identifier\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://app.autocalls.ai/api/user/realtime/session")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"assistant_id\": \"<string>\",\n \"variables\": {},\n \"external_identifier\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.autocalls.ai/api/user/realtime/session")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"assistant_id\": \"<string>\",\n \"variables\": {},\n \"external_identifier\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"url": "<string>",
"token": "<string>",
"expires_in": 123,
"success": true,
"error": "<string>",
"error_code": "<string>"
}Use this endpoint from your backend. It returns
The token expires after 15 minutes. Start the browser session before it expires.
Minting a token does not create a Call History row. A row appears only after the browser connects and the session actually starts. Unused tokens leave no call record.
See Realtime voice SDK for events and a full example.
{ url, token } for the browser SDK. Never put your API key in frontend code.
Rate limited to 10 requests per minute per authenticated user.Concurrent cap of 10 sessions per account. Unused tokens count toward this cap until they expire (15 minutes). In-progress website-widget voice sessions on the same account also count.
Request body
string
required
The assistant UUID. Use the
uuid field from Get Assistants, not the numeric id.object
Optional context variables passed into the assistant (prompt variables). Keys and scalar values only. Maximum 50 keys.
string
Optional CRM or customer id. Passed through as a variable when not already set.Maximum length: 255 characters.
Response
string
Session id (UUID). Useful for your own logging.
string
Media server URL. Pass this to the browser SDK. Do not expose it in a public repo or log it in client analytics.
string
Short-lived session token. Treat it like a password. Pass it to the browser SDK only.
number
Token lifetime in seconds. Currently 900 (15 minutes).
Browser SDK
Install@voice-session/web and pass url and token from this response. Do not send the API key to the browser.
import { RealtimeSession } from "@voice-session/web";
const session = new RealtimeSession({ url, token });
session.on("transcript", ({ role, text, final }) => {
if (final) {
console.log(role, text);
}
});
session.on("agent_state", (state) => {
console.log(state);
});
await session.start({ microphone: true });
Example
curl -X POST "https://app.autocalls.ai/api/user/realtime/session" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"assistant_id": "a7b3c942-5f1e-4d28-8c59-2e4f7a8b9c3d",
"variables": {
"name": "Jane"
},
"external_identifier": "crm-99"
}'
{
"id": "2c4f1a8e-3b7d-4e9a-9c1f-8d6b2a0e5f33",
"url": "wss://example.invalid",
"token": "short-lived-token",
"expires_in": 900
}
Error responses
boolean
false when the request failsstring
Human-readable error message
string
One of
ASSISTANT_NOT_FOUND, ASSISTANT_BLOCKED, INSUFFICIENT_BALANCE, CONCURRENT_LIMIT, CONNECTION_FAILED| Status | error_code | When |
|---|---|---|
| 401 | Missing or invalid API key | |
| 402 | INSUFFICIENT_BALANCE | The account does not have enough minutes to start a voice session |
| 403 | ASSISTANT_BLOCKED | The assistant or account is unavailable for compliance review |
| 404 | ASSISTANT_NOT_FOUND | Unknown UUID, or the assistant does not belong to the authenticated user |
| 422 | Validation failed (assistant_id must be a UUID) | |
| 429 | CONCURRENT_LIMIT | 10 unused or live realtime sessions already exist for this account |
| 429 | Rate limit exceeded (10 session creations per minute) | |
| 503 | CONNECTION_FAILED | The session could not be created. Retry shortly |

