Configuration

Voice behavior lives in the voice object on the sender's agent. Update it with PATCH /v1/senders/{senderId}/agent. All fields except enabled are optional and fall back to sensible defaults.

Settings Reference

Field	Type	Default	Description
`enabled`	boolean	—	Whether the agent handles calls. When `false`, the number is not answered and outbound calls are rejected.
`greeting`	string	—	Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.
`language`	string	auto	BCP-47 code for speech recognition and synthesis (e.g. `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
`ttsVoiceId`	string	follows `language`	Voice used to speak. List the valid ids with `npx zavudev agents voices`; a value that is not one of them is rejected. Defaults to a voice for the agent's `language`.
`interruptible`	boolean	`true`	Whether the caller can interrupt the agent while it speaks (barge-in).
`maxCallDurationMinutes`	integer	`15`	Hard cap on call length (1–120). The call ends automatically when reached.
`maxIdleSeconds`	integer	`30`	How long the agent waits during silence before ending the call (5–300).
`voicemailAction`	string	`hangup`	What to do when voicemail is detected on an outbound call: `hangup` or `leave_message`.
`voicemailMessage`	string	—	Message spoken when `voicemailAction` is `leave_message`. Falls back to `greeting`.
`transferPhoneNumber`	string	—	E.164 number the agent can transfer the call to. Enables a transfer tool the agent can use to reach a human.

Full Example


await zavu.senders.agent.update("sender_12345", {
  voice: {
    enabled: true,
    greeting: "Hi, thanks for calling Acme. How can I help you today?",
    language: "en",
    ttsVoiceId: "aura-2-thalia-en",
    interruptible: true,
    maxCallDurationMinutes: 20,
    maxIdleSeconds: 30,
    voicemailAction: "leave_message",
    voicemailMessage: "This is Acme. We missed you — please call us back at your convenience.",
    transferPhoneNumber: "+14155551234",
  },
});

Greeting

The greeting is the first thing the caller hears. Keep it short and specific — it sets the tone and tells the caller who they reached.

With a greeting, the agent speaks first.
Without one, the agent stays silent and lets the caller start. This suits inbound support lines where the caller already knows why they called.

Voicemail Handling

On outbound calls, Zavu detects when an answering machine or voicemail picks up instead of a person.

`voicemailAction`	Behavior
`hangup` (default)	End the call silently. Best when a voicemail is not useful.
`leave_message`	Speak `voicemailMessage` (or the `greeting` if unset), then hang up.

Transferring to a Human

Set transferPhoneNumber to give the agent a way to escalate. The agent receives a transfer tool it can invoke when a caller needs a person, forwarding the call to that number. Instruct the agent in its system prompt when to transfer — for example, on billing disputes or explicit requests for a human.

Barge-in

With interruptible: true (the default), the caller can talk over the agent and the agent stops to listen. This makes conversations feel natural. Set it to false for scripted messages that must play in full, such as compliance disclosures.

Limits

Limit	Field	Range	Default
Maximum call duration	`maxCallDurationMinutes`	1–120	15
Idle timeout	`maxIdleSeconds`	5–300	30

The duration limit is a hard stop that protects against runaway calls and cost. The idle timeout ends a call when neither side speaks for the configured period.

Per-Call Overrides

Two settings can be overridden for a single outbound call in POST /v1/calls, without changing the agent:

Body field	Overrides
`greeting`	The agent's configured `greeting` for this call only.
`maxDurationMinutes`	The agent's `maxCallDurationMinutes` for this call only.


npx zavudev calls create \
  --to "+56912345678" \
  --sender sender_12345 \
  --greeting "Hi, this is Acme calling to confirm your delivery for tomorrow." \
  --max-minutes 5

Next Steps

Webhooks

React to call lifecycle events

Agent Tools

Let the agent take actions during a call