> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaanivoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Trigger your first outbound call and verify it works end-to-end

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

> [!NOTE]
>
> **Before you start:** Make sure you have these ready:
>
> * **A Vaani account** → [Create an Account](https://docs.vaanivoice.ai/getting-started/create-account.md)
> * **Your `agent_id` (UUID)** → [Create an Agent](https://docs.vaanivoice.ai/getting-started/create-agent.md)
> * **A connected phone number** → [Set Up Telephony](https://docs.vaanivoice.ai/getting-started/setup-telephony.md)
> * **Your API key** → [Generate an API Key](https://docs.vaanivoice.ai/getting-started/generate-api-key.md)

> [!NOTE]
>
> 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):

```bash cURL theme={null}
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": {}
  }'
```

```python Python theme={null}
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](https://docs.vaanivoice.ai/getting-started/create-agent.md#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](https://docs.vaanivoice.ai/getting-started/setup-telephony.md). |

## Success Response

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

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

> [!TIP]
>
> 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](#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}`:

```json theme={null}
"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](https://docs.vaanivoice.ai/getting-started/create-agent.md#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.

> [!TIP]
>
> **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](https://docs.vaanivoice.ai/api-reference/transcript.md)**
>
> Fetch the full transcript for a completed call using the `call_id`

> **[Set Up a Webhook](https://docs.vaanivoice.ai/guides/webhook-setup.md)**
>
> Get notified automatically when a call starts, completes, or fails

> **[Call History](https://docs.vaanivoice.ai/guides/call-logs.md)**
>
> Browse, filter, and review all your past calls in the dashboard

> **[API Reference](https://docs.vaanivoice.ai/api-reference/introduction.md)**
>
> Explore all available endpoints - call details, audio streaming, and more


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.