Voice Calls with the 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.

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.

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.

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:

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.

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.

Voice Agents overview — configuring the agent that answers
Voice webhooks — call.* event payloads

​Place a Call

​With Overrides

​Get a Call and Its Transcript

​List Calls

​Hang Up a Call

​Requirements and Errors

​Related