Skip to main content
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:
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": {}
  }'

​
Request Fields Explained

FieldTypeRequiredDescription
agent_idstring (UUID)YesThe agent to handle this call. Copy this from your Agent Config dashboard.
contact_numberstringYesThe phone number to call, in E.164 format (e.g. +919876543210).
namestringNoA display name for the contact. Appears in your Call History for easy reference.
metadataobjectNoKey-value pairs that get injected into your agent’s prompt. See Understanding Metadata Variables.
voicestringNoOverride the agent’s default voice for this specific call. Omit to use the voice configured on the agent.
outbound_numberstringNoOverride 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:
  1. Your phone should ring within a few seconds. Answer it — you’ll hear your agent speaking based on the prompt you configured.
  2. Have a short conversation with the agent to test how it handles responses.
  3. 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 CodeMeaningHow to Fix
401 UnauthorizedYour API key is missing or invalidCheck the X-API-Key header. Make sure it’s spelled correctly and the key is active.
400 Bad RequestA required field is missing or malformedVerify that agent_id and contact_number are both present and correctly formatted.
404 Not FoundThe agent_id doesn’t exist in your workspaceDouble-check the UUID. Copy it fresh from your Agent Config dashboard.
422 Unprocessable EntityA 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

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.
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.
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.
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