# Configuration

> Every voice setting: greeting, language, voicemail, transfer, and limits

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

```typescript
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",
  },
});
```

```bash
curl -X PATCH https://api.zavu.dev/v1/senders/sender_12345/agent \
  -H "Authorization: Bearer $ZAVUDEV_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",
      "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. |

> **Note:**
> 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. |

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

```bash
curl -X POST https://api.zavu.dev/v1/calls \
  -H "Authorization: Bearer $ZAVUDEV_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
  }'
```

## Next Steps

  - [Webhooks](https://www.zavu.dev/docs/guides/voice-agents/webhooks): React to call lifecycle events
  - [Agent Tools](https://www.zavu.dev/docs/guides/ai-agents/tools): Let the agent take actions during a call