> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. |
| `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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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",
    },
  });
  ```

  ```python Python theme={null}
  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",
      },
  )
  ```

  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

## 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.
</Note>

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  await zavu.calls.create({
    to: "+56912345678",
    senderId: "sender_12345",
    greeting: "Hi, this is Acme calling to confirm your delivery for tomorrow.",
    maxDurationMinutes: 5,
  });
  ```

  ```python Python theme={null}
  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,
  )
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/guides/voice-agents/webhooks">
    React to call lifecycle events
  </Card>

  <Card title="Agent Tools" icon="wrench" href="/guides/ai-agents/tools">
    Let the agent take actions during a call
  </Card>
</CardGroup>