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.
`ttsVoice`	string	neutral	Name of the Zavu voice used to speak. Choose from the voices available in the dashboard.
`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",
    ttsVoice: "aria",
    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",
  },
});

zavu.senders.agent.update(
    "sender_12345",
    voice={
        "enabled": True,
        "greeting": "Hi, thanks for calling Acme. How can I help you today?",
        "language": "en",
        "ttsVoice": "aria",
        "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",
    },
)

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",
      "ttsVoice": "aria",
      "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.

Voicemail detection applies to outbound calls only. Inbound calls are always answered by the agent.

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.

await zavu.calls.create({
  to: "+56912345678",
  senderId: "sender_12345",
  greeting: "Hi, this is Acme calling to confirm your delivery for tomorrow.",
  maxDurationMinutes: 5,
});

zavu.calls.create(
    to="+56912345678",
    sender_id="sender_12345",
    greeting="Hi, this is Acme calling to confirm your delivery for tomorrow.",
    max_duration_minutes=5,
)

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",
    "greeting": "Hi, this is Acme calling to confirm your delivery for tomorrow.",
    "maxDurationMinutes": 5
  }'

Getting Started

Concepts

Guides

Configuration

Settings Reference

Full Example

Greeting

Voicemail Handling

Transferring to a Human

Barge-in

Limits

Per-Call Overrides

Next Steps

Webhooks

Agent Tools

​Settings Reference

​Full Example

​Greeting

​Voicemail Handling

​Transferring to a Human

​Barge-in

​Limits

​Per-Call Overrides

​Next Steps

Webhooks

Agent Tools

Settings Reference

Full Example

Greeting

Voicemail Handling

Transferring to a Human

Barge-in

Limits

Per-Call Overrides

Next Steps