Quickstart

You’ve set up your account, created an agent, connected a phone number, and generated an API key. Now let’s put it all together and make your first outbound call.

Prerequisites

Before you start: Make sure you have these ready:

A Vaani account → Create an Account
Your agent_id (UUID) → Create an Agent
A connected phone number → Set Up Telephony
Your API key → Generate an API Key

Have a personal phone handy to receive the test call. You’ll use your own number as the contact_number so you can hear the agent in action.

Trigger a Call

Replace YOUR_API_KEY and YOUR_AGENT_ID with your actual values, and set contact_number to the phone number you want to call (your own mobile is perfect for testing):

curl -X POST 'https://api.vaanivoice.ai/api/trigger-call/' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "contact_number": "+919876543210",
    "name": "Test Call",
    "metadata": {}
  }'

import os
import requests

response = requests.post(
    "https://api.vaanivoice.ai/api/trigger-call/",
    headers={
        "X-API-Key": os.getenv("VAANI_API_KEY"),
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "YOUR_AGENT_ID",
        "contact_number": "+919876543210",
        "name": "Test Call",
        "metadata": {}
    }
)

print(response.json())

Request Fields Explained

Field	Type	Required	Description
`agent_id`	string (UUID)	Yes	The agent to handle this call. Copy this from your Agent Config dashboard.
`contact_number`	string	Yes	The phone number to call, in E.164 format (e.g. `+919876543210`).
`name`	string	No	A display name for the contact. Appears in your Call History for easy reference.
`metadata`	object	No	Key-value pairs that get injected into your agent’s prompt. See Understanding Metadata Variables.
`voice`	string	No	Override the agent’s default voice for this specific call. Omit to use the voice configured on the agent.
`outbound_number`	string	No	Override the caller ID for this specific call. Must be a number configured in your Telephony settings.

Success Response

If everything is set up correctly, you’ll get a response like this:

{
  "success": true,
  "message": "Call initiated successfully",
  "output": {
    "agent_name": "my-sales-agent",
    "call_id": "room-f5237622"
  },
  "error": null
}

Save the call_id (e.g. room-f5237622). You’ll use it to fetch the transcript, audio recording, and detailed call information after the call completes.

Verify It Worked

After triggering the call:

Your phone should ring within a few seconds. Answer it — you’ll hear your agent speaking based on the prompt you configured.
Have a short conversation with the agent to test how it handles responses.
After the call ends, go to Call History in your dashboard. You should see the call with its transcript, duration, and status.

If your phone didn’t ring, check the Troubleshooting section below.

Understanding Metadata

The metadata field lets you pass dynamic values into your agent’s prompt at call time. For example, if your agent’s prompt uses {customer_name} and {property_name}:

"metadata": {
  "customer_name": "Rahul Sharma",
  "property_name": "Prateek Laurel"
}

Vaani replaces the placeholders before the call starts, so your agent greets the caller by name and references the right property. For a detailed walkthrough of how metadata variables work, see Understanding Metadata Variables.

Common Error Responses

If something goes wrong, the API returns an error response. Here are the most common ones:

Status Code	Meaning	How to Fix
`401 Unauthorized`	Your API key is missing or invalid	Check the `X-API-Key` header. Make sure it’s spelled correctly and the key is active.
`400 Bad Request`	A required field is missing or malformed	Verify that `agent_id` and `contact_number` are both present and correctly formatted.
`404 Not Found`	The `agent_id` doesn’t exist in your workspace	Double-check the UUID. Copy it fresh from your Agent Config dashboard.
`422 Unprocessable Entity`	A field value is invalid (e.g. phone number not in E.164)	Check that `contact_number` uses E.164 format: `+[country code][number]`, no spaces or dashes.

Troubleshooting

My phone didn't ring

Check three things: (1) contact_number is in E.164 format (e.g. +919876543210, not 09876543210), (2) your agent has a phone number assigned in Telephony settings, and (3) the phone you’re calling is turned on and has signal. Also verify the API response was "success": true — if not, check the error message.

The call connected but the agent didn't say anything

This usually means the agent’s prompt is empty or misconfigured. Go to Agent Config, open your agent, and verify the prompt field has content. Also check that the language and voice settings are valid.

I got a successful response but the call still failed

A "success": true response means the call was initiated, not that it completed. The call can still fail if the recipient doesn’t answer, the number is invalid, or there’s a network issue. Check Call History in your dashboard for the call’s status and any error details.

How do I test without calling a real phone?

Currently, Vaani requires a real phone number to receive calls. Use your own mobile number for testing — it’s the quickest way to hear your agent and verify everything works.

Video walkthrough coming soon. Follow the steps above — they cover everything the video will.

Next Steps

You’ve made your first call! Here’s where to go from here:

Get Transcript

Fetch the full transcript for a completed call using the call_id

Set Up a Webhook

Get notified automatically when a call starts, completes, or fails

Call History

Browse, filter, and review all your past calls in the dashboard

API Reference

Explore all available endpoints — call details, audio streaming, and more

Getting Started

Guides

Prerequisites

Trigger a Call

Request Fields Explained

Success Response

Verify It Worked

Understanding Metadata

Common Error Responses

Troubleshooting

Next Steps

Get Transcript

Set Up a Webhook

Call History

API Reference

​Prerequisites

​Trigger a Call

​Request Fields Explained

​Success Response

​Verify It Worked

​Understanding Metadata

​Common Error Responses

​Troubleshooting

​Next Steps

Get Transcript

Set Up a Webhook

Call History

API Reference

Prerequisites

Trigger a Call

Request Fields Explained

Success Response

Verify It Worked

Understanding Metadata

Common Error Responses

Troubleshooting

Next Steps