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

# Quickstart

> Enable voice on your agent and place your first call

This guide takes you from an existing text agent to a working phone agent in three steps.

## Prerequisites

* The **Voice Agents** feature enabled for your team. Voice endpoints return `403` until it is.
* A **sender** with an AI agent configured. See [AI Agent Setup](/guides/ai-agents/setup).
* A **phone number** assigned to that sender (required for inbound calls). See [Purchasing Phone Numbers](/guides/phone-numbers/purchasing).

<Note>
  Voice calls run against live infrastructure and are not available with test-mode API keys. Use a `zv_live_` key.
</Note>

## Step 1 — Enable Voice on the Agent

Voice is a property of the agent. Patch the agent with a `voice` object to turn it on and set a greeting.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Zavudev from "@zavudev/sdk";

  const zavu = new Zavudev({
    apiKey: process.env["ZAVUDEV_API_KEY"],
  });

  await zavu.senders.agent.update("sender_12345", {
    voice: {
      enabled: true,
      greeting: "Hi, thanks for calling Acme. How can I help you today?",
      language: "en",
      interruptible: true,
      maxCallDurationMinutes: 15,
    },
  });
  ```

  ```python Python theme={null}
  import os
  from zavudev import Zavudev

  zavu = Zavudev(api_key=os.environ.get("ZAVUDEV_API_KEY"))

  zavu.senders.agent.update(
      "sender_12345",
      voice={
          "enabled": True,
          "greeting": "Hi, thanks for calling Acme. How can I help you today?",
          "language": "en",
          "interruptible": True,
          "maxCallDurationMinutes": 15,
      },
  )
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.zavu.dev/v1/senders/sender_12345/agent \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "voice": {
        "enabled": true,
        "greeting": "Hi, thanks for calling Acme. How can I help you today?",
        "language": "en",
        "interruptible": true,
        "maxCallDurationMinutes": 15
      }
    }'
  ```
</CodeGroup>

The agent keeps its existing provider, model, system prompt, tools, and knowledge bases. Voice only adds how it behaves on a call.

## Step 2 — Place an Outbound Call

Call `POST /v1/calls` with the recipient's number. Zavu dials them, and the agent takes over when they answer.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { call } = await zavu.calls.create({
    to: "+56912345678",
    senderId: "sender_12345",
  });

  console.log("Call ID:", call.id);
  console.log("Status:", call.status); // "queued" or "ringing"
  ```

  ```python Python theme={null}
  result = zavu.calls.create(
      to="+56912345678",
      sender_id="sender_12345",
  )

  print("Call ID:", result.call.id)
  print("Status:", result.call.status)  # "queued" or "ringing"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/calls \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+56912345678",
      "senderId": "sender_12345"
    }'
  ```
</CodeGroup>

The response is `202` with the call in `queued` or `ringing` status. `senderId` is optional — the project's default sender is used when omitted.

## Step 3 — Receive Inbound Calls

Inbound calls need no extra code. When someone dials a phone number assigned to the sender, Zavu answers with the voice agent automatically.

To set it up:

1. Assign a phone number to the sender (see [Purchasing Phone Numbers](/guides/phone-numbers/purchasing)).
2. Confirm the sender's agent has `voice.enabled` set to `true` (Step 1).
3. Call the number. The agent answers with its greeting and holds the conversation.

## Read the Call and Transcript

Retrieve a call to read its outcome and full transcript. The transcript is a list of turns in order.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { call } = await zavu.calls.retrieve("call_abc123");

  console.log("Status:", call.status);
  console.log("Duration (s):", call.durationSeconds);

  for (const turn of call.transcript ?? []) {
    console.log(`${turn.role}: ${turn.text}`);
  }
  ```

  ```python Python theme={null}
  result = zavu.calls.retrieve("call_abc123")
  call = result.call

  print("Status:", call.status)
  print("Duration (s):", call.duration_seconds)

  for turn in call.transcript or []:
      print(f"{turn.role}: {turn.text}")
  ```

  ```bash cURL theme={null}
  curl https://api.zavu.dev/v1/calls/call_abc123 \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```
</CodeGroup>

To stop a call in progress, hang up:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await zavu.calls.hangup("call_abc123");
  ```

  ```python Python theme={null}
  zavu.calls.hangup("call_abc123")
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/calls/call_abc123/hangup \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/guides/voice-agents/configuration">
    Voicemail handling, call transfer, and limits
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/voice-agents/webhooks">
    Get notified when calls start and end
  </Card>
</CardGroup>