API

Calls API

Trigger outbound calls, stream real-time events, download recordings, and export call records.

Live Sandbox

💡

Explore and test these endpoints live in the Vozon Interactive API Playground: /docs/api.

Endpoints catalog

Method	Endpoint path	Required scope	Description
POST	/calls/outbound	calls:trigger	Queue and trigger an outbound voice agent call
GET	/calls	read	Query paginated call history with 11 filter parameters
GET	/calls/{callId}	read	Retrieve complete normalized call details and transcripts
GET	/calls/{callId}/recording	read	Stream or download audio recording file (Range support)
GET	/calls/stream	read	Server-Sent Events (SSE) stream of live call state changes
GET	/calls/export.csv	read	Download filtered historical calls as a CSV spreadsheet
GET	/agents	read	List all organization voice agents and their active models

Pre-flight calling checklist

Agent Live status

Confirm your agent is in 'Live' status in the dashboard. Agents in 'Draft' or 'Review' cannot place outbound calls.

Ready phone number

Ensure your organization has at least one phone number in 'Ready' status with direction 'Outbound' or 'Both' assigned to the agent.

E.164 phone format

The recipient phoneNumber must strictly follow international E.164 format: '+[country_code][number]' with no dashes or spaces (e.g. +919876543210).

Wallet balance

Verify your organization wallet has sufficient credit balance before triggering calls.

Create outbound call

curl

curl -X POST "https://api.vozon.ai/api/v1/calls/outbound" \
  -H "Authorization: Bearer avp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "6701a2b3c4d5e6f7a8b9c0d1",
    "phoneNumber": "+919876543210",
    "metadata": {
      "customerId": "cust_8829",
      "leadSource": "website_demo"
    }
  }'

Field	Type	Required	Description
agentId	string	Yes	ID of the Live agent belonging to your organization.
phoneNumber	string	Yes	Destination phone number in international E.164 format.
phoneNumberId	string	No	Specific outbound number ID. Defaults to the latest ready number assigned to the agent.
metadata	object	No	Custom JSON correlation object returned in call logs, transcripts, and webhooks.

Response (202 Accepted):

json

{
  "callId": "6702b3c4d5e6f7a8b9c0d1e2",
  "roomName": "outbound-call-6701a2b3-1726650000-abcd",
  "participantId": "sip_part_88921",
  "dispatchId": "dispatch_99210"
}

Node.js (TypeScript)

typescript

const response = await fetch("https://api.vozon.ai/api/v1/calls/outbound", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOZON_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "6701a2b3c4d5e6f7a8b9c0d1",
    phoneNumber: "+919876543210",
    metadata: { customerId: "cust_8829" },
  }),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Vozon API Error ${response.status}: ${err.message}`);
}

const call = await response.json();
console.log("Call queued:", call.callId);

Python

python

import os
import requests

response = requests.post(
    "https://api.vozon.ai/api/v1/calls/outbound",
    headers={"Authorization": f"Bearer {os.environ['VOZON_API_KEY']}"},
    json={
        "agentId": "6701a2b3c4d5e6f7a8b9c0d1",
        "phoneNumber": "+919876543210",
        "metadata": {"customerId": "cust_8829"},
    },
    timeout=30,
)
response.raise_for_status()
print("Call accepted:", response.json()["callId"])

Real-time streaming (SSE)

Connect to GET /calls/stream to receive real-time notifications whenever calls start, finish, or error, avoiding unnecessary database polling:

javascript

const eventSource = new EventSource("https://api.vozon.ai/api/v1/calls/stream", {
  headers: { Authorization: `Bearer ${process.env.VOZON_API_KEY}` }
});

eventSource.addEventListener("ready", (e) => console.log("Stream connected:", e.data));
eventSource.addEventListener("calls_changed", (e) => {
  console.log("Call update event:", JSON.parse(e.data));
  // Fetch fresh call details or update your UI
});