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

# Voice Settings

> Greeting modes, opening messages, and voicemail behavior on the Assistants API

The `voice_settings` object on the Assistants API controls how an assistant
opens a phone call and what it does when it reaches voicemail. It is accepted
on `POST /v3/assistants` and `PATCH /v3/assistants/{id}`. Successful
`POST /v3/assistants` responses and `GET /v3/assistants/{id}` return it (the
list endpoint does not include it).

## Three concepts, kept distinct

The API deliberately separates three things that are easy to conflate:

* **Greeting text** — `inbound_greeting` / `outbound_greeting`. Context text
  that feeds the `{{greeting}}` template variable your prompt can reference.
  It is *not* spoken automatically. These remain writable via the top-level
  body fields; inside `voice_settings` they appear read-only for convenience.
* **Opening message** — what the assistant literally says first on a call,
  per direction (`inbound_opening_message` / `outbound_opening_message`).
  Only used in `fixed` greeting mode.
* **Voicemail behavior** — `voicemail_message`. When voicemail is detected:
  an empty or `null` value means the assistant hangs up; a non-empty value is
  spoken to the voicemail, after which the assistant stops.

## Greeting modes

| `greeting_mode` | Behavior                                                       |
| --------------- | -------------------------------------------------------------- |
| `dynamic`       | The AI generates a natural opener per call (default).          |
| `fixed`         | The assistant speaks your configured opening message verbatim. |
| `contact_first` | The assistant stays silent until the contact speaks.           |

Rules the API enforces:

1. `fixed` mode requires at least one opening message. Switching an existing
   assistant to `fixed` keeps its stored messages, so a mode-only update is
   valid when messages already exist.
2. Opening messages are only accepted while the effective mode is `fixed` —
   set `greeting_mode: "fixed"` in the same request if needed.
3. In `fixed` mode, sending `null` for one direction clears it, as long as at
   least one opening message remains.

Template variables inside opening messages (for example a contact first-name
placeholder) are passed through verbatim and resolve per call.

## Example

Request — put an assistant into fixed mode with per-direction openers and a
voicemail message:

```json theme={null}
PATCH /v3/assistants/{id}
{
  "voice_settings": {
    "greeting_mode": "fixed",
    "inbound_opening_message": "Thanks for calling Acme — this is Ava. How can I help?",
    "outbound_opening_message": "Hi {{contact.first_name}}, this is Ava from Acme!",
    "voicemail_message": "Sorry we missed you — we'll try again soon."
  }
}
```

Response — `GET /v3/assistants/{id}` then returns:

```json theme={null}
{
  "voice_settings": {
    "greeting_mode": "fixed",
    "inbound_opening_message": "Thanks for calling Acme — this is Ava. How can I help?",
    "outbound_opening_message": "Hi {{contact.first_name}}, this is Ava from Acme!",
    "inbound_greeting": null,
    "outbound_greeting": null,
    "voicemail_message": "Sorry we missed you — we'll try again soon.",
    "enable_voicemail_detection": false
  }
}
```

## Notes

* `enable_voicemail_detection` records intent and is returned on read, but
  voicemail detection is currently platform-managed — the flag does not yet
  change runtime behavior.
* Reverting an assistant to a previous version does **not** restore
  `voice_settings`; greeting mode, opening messages, and voicemail behavior
  keep their current values.