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

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.

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"

result = zavu.calls.create(
    to="+56912345678",
    sender_id="sender_12345",
)

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

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

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.

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

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

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

To stop a call in progress, hang up:

await zavu.calls.hangup("call_abc123");

zavu.calls.hangup("call_abc123")

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

Getting Started

Concepts

Guides

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