# 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

- A **sender** with an AI agent configured. See [AI Agent Setup](https://www.zavu.dev/docs/guides/ai-agents/setup).
- A **phone number** assigned to that sender (required for inbound calls). See [Purchasing Phone Numbers](https://www.zavu.dev/docs/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.

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

```typescript
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,
  },
});
```

```bash
curl -X PATCH https://api.zavu.dev/v1/senders/sender_12345/agent \
  -H "Authorization: Bearer $ZAVUDEV_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
    }
  }'
```

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.

> **Note:**
> The voice endpoints are not generated in the language SDKs yet. Use the CLI or
> call the API directly; both are shown throughout this guide.

```bash
npx zavudev calls create --to "+56912345678" --sender sender_12345
```

```bash
curl -X POST https://api.zavu.dev/v1/calls \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+56912345678",
    "senderId": "sender_12345"
  }'
```

```typescript
// `@zavudev/sdk` has no `calls` resource yet, so call the endpoint directly.
const res = await fetch("https://api.zavu.dev/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ZAVUDEV_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "+56912345678", senderId: "sender_12345" }),
});

const { call } = await res.json();
console.log("Call ID:", call.id);
console.log("Status:", call.status); // "queued" or "ringing"
```

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](https://www.zavu.dev/docs/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.

```bash
npx zavudev calls get call_abc123
npx zavudev calls list --status completed --limit 10
```

```bash
curl https://api.zavu.dev/v1/calls/call_abc123 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
const res = await fetch("https://api.zavu.dev/v1/calls/call_abc123", {
  headers: { Authorization: `Bearer ${process.env.ZAVUDEV_API_KEY}` },
});
const { call } = await res.json();

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

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

To stop a call in progress, hang up:

```bash
npx zavudev calls hangup call_abc123
```

```bash
curl -X POST https://api.zavu.dev/v1/calls/call_abc123/hangup \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

## Next Steps

  - [Configuration](https://www.zavu.dev/docs/guides/voice-agents/configuration): Voicemail handling, call transfer, and limits
  - [Webhooks](https://www.zavu.dev/docs/guides/voice-agents/webhooks): Get notified when calls start and end