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

# Voice Calls with the TypeScript SDK

> Place outbound voice-agent calls, read transcripts, and hang up active calls via the Zavu TypeScript SDK.

Voice calls are conversations handled by the AI agent configured on a sender. Placing a call dials the recipient and connects them to the agent — speech recognition, the agent's LLM, and speech synthesis run in Zavu's managed voice pipeline.

The `calls` resource is available since `@zavudev/sdk` 0.56.0.

## Place a Call

`to` is the only required field. The sender's agent must have `voice.enabled: true`.

```typescript theme={null}
const { call } = await client.calls.create({
  to: "+56912345678",
});

console.log(call.id, call.status); // call_xxx "queued"
```

### With Overrides

`greeting`, `language`, and `maxDurationMinutes` override the agent's configuration for this call only. `metadata` is returned on the call object and included in voice webhooks.

```typescript theme={null}
const { call } = await client.calls.create({
  to: "+56912345678",
  senderId: "snd_abc123",
  greeting: "Hi, this is Acme calling about your appointment.",
  language: "es-ES", // or "auto" to follow the caller
  maxDurationMinutes: 10,
  metadata: { campaign: "appointment_reminders" },
});
```

The call is returned immediately with status `queued` while it starts dialing. Track progress via the `call.initiated`, `call.answered`, `call.completed`, and `call.failed` webhook events, or by polling `calls.retrieve`.

## Get a Call and Its Transcript

Fetching a single call includes the full transcript once the conversation has produced turns. Each turn is `{ seq, role, text }` where `role` is `user`, `assistant`, or `tool`.

```typescript theme={null}
const { call } = await client.calls.retrieve("call_abc123");

console.log(call.status, call.durationSeconds, call.endReason, call.cost);

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

`durationSeconds`, `endReason`, `turnCount`, and `cost` populate once the call ends. `cost` is the total in USD, combining the managed voice pipeline and telephony.

## List Calls

Transcripts are omitted from list responses — fetch a single call to get one. The list auto-paginates:

```typescript theme={null}
for await (const call of client.calls.list({
  status: "completed",
  direction: "outbound",
})) {
  console.log(call.id, call.to, call.durationSeconds);
}
```

## Hang Up a Call

Ends an active call. The call must still be `ringing` or `in_progress`; anything else returns an error.

```typescript theme={null}
const { call } = await client.calls.hangup("call_abc123");

console.log(call.status);
```

## Requirements and Errors

* The sender's agent needs `voice.enabled: true`, or `create` fails with `400 "The sender's agent does not have voice enabled"`.
* Placing and hanging up calls is not available with test-mode API keys; reads are.
* Calls are billed per connected minute plus telephony from your prepaid balance. `402 insufficient_balance` means the balance cannot cover the call.

## Related

* [Voice Agents overview](/guides/voice-agents/overview) — configuring the agent that answers
* [Voice webhooks](/guides/voice-agents/webhooks) — `call.*` event payloads