Backups

Each of the three engines an agent runs on - transcriber, model and voice - can have a fallback: a second one, from a different provider, that takes over if the first provider stops responding during a call. You set them with PATCH /v1/agents/{agent_id} (or on create), like any other setting.

What to send

Block	Send	Filled in for you	Example
`transcriber.fallback`	`model`	`provider`	`{ "model": "nova-3-general" }`
`model.fallback`	`model`	`provider`	`{ "model": "gemini-3.5-flash-lite" }`
`voice.fallback`	`provider` and `voice_id`	`model`	`{ "provider": "sarvam", "voice_id": "shubh" }`

A model id belongs to exactly one provider, so for the transcriber and the model you only name the model - a provider you send is ignored. A voice id does not say whose voice it is, so the voice backup needs both. Pick values from the catalogues: GET /v1/transcribers, GET /v1/models, and GET /v1/voices?provider=.

Example

PATCH /v1/agents/{agent_id}

{
  "transcriber": { "fallback": { "model": "nova-3-general" } },
  "model":       { "fallback": { "model": "gemini-3.5-flash-lite" } },
  "voice":       { "fallback": { "provider": "sarvam", "voice_id": "shubh" } }
}

The response is the whole agent. Each block now shows its backup in full, next to the main engine it stands in for:

{
  "transcriber": {
    "provider": "sarvam", "model": "saaras:v4",
    "fallback": { "provider": "deepgram", "model": "nova-3-general" }
  },
  "model": {
    "provider": "openai", "model": "gpt-5.4-nano",
    "fallback": { "provider": "gemini", "model": "gemini-3.5-flash-lite" }
  },
  "voice": {
    "provider": "vocily", "model": "v2",
    "fallback": { "provider": "sarvam", "model": "bulbul:v3", "voice_id": "shubh" }
  }
}

Read fallback back to confirm it was saved. If it comes back null, there is no backup.

Rules

The backup must be from a different provider

What fails during an outage is the provider - it is unreachable, the key is rejected, the region is down - and every model behind it fails together. So a backup on the same provider as the main engine is refused:

// model is gpt-5.4-nano (openai), and so is this backup
{ "model": { "fallback": { "model": "gpt-5-mini" } } }

{ "detail": { "code": "document_invalid",
  "message": "model.fallback: 'gpt-5-mini' is on the same provider as the main model (openai), so it would fail with it. Choose one from a different provider." },
  "code": "BAD_REQUEST" }

Changing the main engine onto the backup’s provider is the same clash, and refused the same way.

Changing one field keeps the others

fallback merges like the rest of the body. { "voice": { "fallback": { "voice_id": "anushka" } } } changes the backup voice and keeps its provider. The exception is the voice backup’s provider: a voice belongs to its provider, so switching provider without a voice_id clears the old voice and the request is refused until you name one. Send both together:

{ "voice": { "fallback": { "provider": "cartesia", "voice_id": "<a Cartesia voice id>" } } }

Remove a backup with null

{ "model": { "fallback": null } }

During a call

The backup is only used if the main provider stops responding. When it is, the agent switches for the rest of that call - it does not go back and forth.

Block	What the caller notices
`transcriber`	A short announcement, and the conversation returns to the agent’s primary language
`voice`	A short announcement, and the conversation returns to the primary language
`model`	A pause on that turn, and nothing else

A backup only has to support the agent’s primary language, which is why a failover returns the conversation to it - see If a provider fails mid-call. The call is billed at the engine it actually ran on.

Errors

Status	`detail.code`	When	`detail.message`
`400`	`voice_config_invalid`	`transcriber.fallback.model` is not in `GET /v1/transcribers`	`Unsupported backup speech model: nope. Supported: …`
`400`	`voice_config_invalid`	`model.fallback.model` is not in `GET /v1/models`	`Unsupported backup LLM model: nope. Supported: …`
`400`	`voice_config_invalid`	`voice.fallback` has no `provider`	`The backup voice names no provider, so it could never be used. Choose one of: …`
`400`	`voice_config_invalid`	`voice.fallback.provider` is not a voice provider	`Unknown backup voice provider 'acme'. Supported: …`
`400`	`voice_config_invalid`	`voice.fallback` has no `voice_id`	`The backup voice names no voice. A provider alone cannot speak — choose one of its voices.`
`400`	`document_invalid`	the backup is on the main engine’s own provider	`model.fallback: 'gpt-5-mini' is on the same provider as the main model (openai)…`
`422`	`validation_error`	`fallback` is not an object, e.g. a bare string	`model.fallback: Must be an object.`

A backup the configuration itself refuses reads voice_config_invalid:

{
  "detail": {
    "code": "voice_config_invalid",
    "message": "Unsupported backup LLM model: nope. Supported: gemini-3.5-flash, gemini-3.5-flash-lite, …"
  },
  "code": "BAD_REQUEST"
}

The same-provider clash reads document_invalid: the field is real and the value well-formed, but the agent cannot use it - the example above under Rules shows it in full. A 422 lists every problem in the request - see Validation errors.

Calls

Chats

Phone Numbers

Knowledge Bases

Agents

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

What to send

Example

Rules

The backup must be from a different provider

Changing one field keeps the others

Remove a backup with null

During a call

Errors

​What to send

​Example

​Rules

​The backup must be from a different provider

​Changing one field keeps the others

​Remove a backup with null

​During a call

​Errors

What to send

Example

Rules

The backup must be from a different provider

Changing one field keeps the others

Remove a backup with null

During a call

Errors