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

<Info>
  **Before you start:** Make sure you have these ready:

  * **A Vaani account** → [Create an Account](/getting-started/create-account)
  * **Your `agent_id` (UUID)** → [Create an Agent](/getting-started/create-agent)
  * **A connected phone number** → [Set Up Telephony](/getting-started/setup-telephony)
  * **Your API key** → [Generate an API Key](/getting-started/generate-api-key)
</Info>

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

## 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):

<CodeGroup>
  ```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())
  ```
</CodeGroup>

## 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](/getting-started/create-agent#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](/getting-started/setup-telephony).                          |

## 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.
</Tip>

## 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](/getting-started/create-agent#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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Tip>
  **Video walkthrough coming soon.** Follow the steps above — they cover everything the video will.
</Tip>

## Next Steps

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

<CardGroup cols={2}>
  <Card title="Get Transcript" icon="file-lines" href="/api-reference/transcript">
    Fetch the full transcript for a completed call using the `call_id`
  </Card>

  <Card title="Set Up a Webhook" icon="webhook" href="/guides/webhook-setup">
    Get notified automatically when a call starts, completes, or fails
  </Card>

  <Card title="Call History" icon="clock-rotate-left" href="/guides/call-logs">
    Browse, filter, and review all your past calls in the dashboard
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Explore all available endpoints — call details, audio streaming, and more
  </Card>
</CardGroup>