Quickstart

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.
A phone number assigned to that sender (required for inbound calls). See Purchasing Phone Numbers.

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.

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

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,
    },
)

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.

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.

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

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"
  }'

// `@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:

Assign a phone number to the sender (see Purchasing Phone Numbers).
Confirm the sender’s agent has voice.enabled set to true (Step 1).
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.

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

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

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:

npx zavudev calls hangup call_abc123

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

Getting Started

Build agents

Send & receive

Operate

Developer tools

Prerequisites

Step 1 — Enable Voice on the Agent

Step 2 — Place an Outbound Call

Step 3 — Receive Inbound Calls

Read the Call and Transcript

Next Steps

Configuration

Webhooks

​Prerequisites

​Step 1 — Enable Voice on the Agent

​Step 2 — Place an Outbound Call

​Step 3 — Receive Inbound Calls

​Read the Call and Transcript

​Next Steps

Configuration

Webhooks

Prerequisites

Step 1 — Enable Voice on the Agent

Step 2 — Place an Outbound Call

Step 3 — Receive Inbound Calls

Read the Call and Transcript

Next Steps