Voice AI Agents

Make Outbound Calls

Welcome to the Vozzo Make Call documentation. Instantly place AI-powered voice calls to one or more recipients using a single API request and your custom Voice AI Agents—perfect for real-time outreach, notifications, and conversational automation.

What is the Make Call Endpoint?

The Make Call endpoint allows you to trigger outbound calls on demand using a configured Vozzo AI agent. Unlike campaigns (which are designed for large-scale orchestration), this endpoint is optimized for immediate or scheduled individual calls with full control over timing, language, metadata, and post-call evaluation.

Common use cases include:

One-off customer support callbacks
Instant lead engagement
Appointment confirmations
Internal alerts or escalations

API Architecture

The Make Call endpoint follows RESTful principles with JSON payloads and standard HTTP methods:

Authentication: Bearer token-based security with API keys
Base URL:
https://backend.vozzo.ai
Format: JSON request and response bodies
Endpoint: API version included in endpoint paths ( POST /v1alpha/dispatcher)

Trigger Calls Instantly

Start a voice call immediately or schedule it for later with fine-grained time window controls, timezone handling, and agent configuration.

What you need to make a call

Before calling the API, ensure you have:

1.
API Key: Your Vozzo Bearer token
2.
Agent UUID: The AI agent that will handle the call
3.
Phone Number: Recipient phone number in E.164 format
4.
Schedule Config: Time window and timezone preferences

How the Make Call Flow Works

Select an AI agent using agent_uuid
Define scheduling rules (date, time window, weekends)
Attach recipient-specific metadata (name, context, language)
Vozzo places the call and tracks execution automatically

Endpoint Overview

Make a Call

POST /v1alpha/dispatcherTrigger a new outbound call

Step 1: Verify Authentication

Ensure your Bearer token is valid before making a call.

Code
 
curl --request GET \
  --url https://backend.vozzo.ai/v1alpha/auth/me \
  --header 'Authorization: Token YOUR_API_KEY'

Step 2: Make Your First Call

Trigger a scheduled outbound AI call using the Dispatcher API.

Code
 
curl --request POST \
  --url https://backend.vozzo.ai/v1alpha/dispatcher \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_uuid": "042cd5ea-07e9-4b49-8782-658d8128889d",
    "prompt_history_id": null,
    "scheduled_call_config": {
      "searchable_attr": "phone_number",
      "timeslot_settings": {
        "timezone": "IST",
        "allow_on_weekends": false,
        "start_time": "09:00",
        "end_time": "18:00",
        "start_date": "2026-02-04"
      }
    },
    "post_call_config": {
      "goals": [],
      "criteria": [],
      "buckets": [],
      "tags": [],
      "questions": []
    },
    "scheduled_call_data": [
      {
        "to_phone_number": "+916376526334",
        "agent_language": "Hindi",
        "metadata": "{\"name\":\"john\"}"
      }
    ]
  }'

Understanding the Request

Field	Description
agent_uuid	AI agent that will place the call
scheduled_call_config	Controls scheduling rules and allowed time windows
scheduled_call_data	Recipient list and per-call personalization data
post_call_config	Optional configuration for tagging, scoring, and analytics

Scheduled Call Data Structure


Code
 
{
  "to_phone_number": "+916376526334",
  "agent_language": "Hindi",
  "metadata": "{\"name\":\"john\"}"
}

to_phone_number: E.164 formatted phone number
agent_language: Language the agent will speak
metadata: JSON string for call personalization

Expected Response


Code
 
{
"success": true,
"message": "Call scheduled successfully",
"data": {
    "call_id": "9e8a0f1c-5a21-4d9c-9f91-8a21c2a7d123",
    "status": "SCHEDULED",
    "scheduled_for": "2026-02-04T09:00:00+05:30"
}
}

Success! Your AI call is now queued and will be executed within the defined time window.

How to Integrate API

Make Call (Dispatcher)

Endpoint

POST {{baseUrl}}/v1alpha/dispatcher

Trigger an outbound AI-powered voice call instantly or schedule it within a defined time window. This endpoint supports single or bulk recipients, personalization via metadata, and advanced scheduling rules.

Headers

Header	Value	Required	Description
Authorization	Bearer <ACCESS_TOKEN>	Yes	OAuth Bearer token obtained after authentication
Content-Type	application/json	Yes	Indicates JSON request body

Request Body

Field	Type	Required	Description
agent_uuid	string (uuid)	Yes	UUID of the AI agent that will handle the call
prompt_history_id	string \| null	No	Reference to previous conversation history, if any
scheduled_call_config	object	Yes	Defines scheduling rules, time window, and timezone
post_call_config	object	No	Optional configuration for goals, tags, scoring, and analytics
scheduled_call_data	object[]	Yes	List of recipients and call-specific parameters

curl --request POST \
  --url https://backend.vozzo.ai/v1alpha/dispatcher \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_uuid": "042cd5ea-07e9-4b49-8782-658d8128889d",
    "prompt_history_id": null,
    "scheduled_call_config": {
      "searchable_attr": "phone_number",
      "timeslot_settings": {
        "timezone": "IST",
        "allow_on_weekends": false,
        "start_time": "09:00",
        "end_time": "18:00",
        "start_date": "2026-02-04"
      }
    },
    "post_call_config": {
      "goals": [],
      "criteria": [],
      "buckets": [],
      "tags": [],
      "questions": []
    },
    "scheduled_call_data": [
      {
        "to_phone_number": "+916376526334",
        "agent_language": "Hindi",
        "metadata": "{\"name\":\"john\"}"
      }
    ]
  }'

Example Request Body


Code
 
      {
      "agent_uuid": "042cd5ea-07e9-4b49-8782-658d8128889d",
      "prompt_history_id": null,
      "scheduled_call_config": {
          "searchable_attr": "phone_number",
          "timeslot_settings": {
          "timezone": "IST",
          "allow_on_weekends": false,
          "start_time": "09:00",
          "end_time": "18:00",
          "start_date": "2026-02-04"
          }
      },
      "post_call_config": {
          "goals": [],
          "criteria": [],
          "buckets": [],
          "tags": [],
          "questions": []
      },
      "scheduled_call_data": [
          {
          "to_phone_number": "+916376526334",
          "agent_language": "Hindi",
          "metadata": "{\"name\":\"john\"}"
          }
      ]
      }

Common Pitfalls

Problem: Using an expired Bearer token

Problem: Sending metadata as an object instead of a JSON string

Problem: Invalid phone number format

Problem: "Invalid date format"

Problem: Scheduling calls outside allowed hours

Best Practices

Start with a single test number

Keep metadata small and meaningful

Respect recipient timezones and consent

Log call_id for debugging and audits

Next Steps

Explore Dispatcher API

Learn how to batch calls, add scoring, and post-call analytics

Support

Need help?

Email: support@vozzo.ai
Full API documentation
Developer community

Last modified on July 24, 2026

Deploy on Phone Agent Workflow