Skip to content
DashboardGet API key

Voice Calls with the TypeScript SDK

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

View .md

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
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
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
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
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 queued, ringing or in_progress; a call that already ended returns 409 conflict.

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