Multilingual Config Reference

When you build an agent through the dashboard, Bolna generates the multilingual configuration for you. If you create or update agents over the API instead, you provide that configuration directly through the multilingual_config object. This page documents the object: where it lives, every field, its validation rules, and how Bolna expands it for the call.

Where it lives

multilingual_config sits inside tools_config on the first task of the agent payload you send to POST /v2/agent:

{
  "agent_config": {
    "tasks": [
      {
        "tools_config": {
          "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
          "synthesizer": { "provider": "elevenlabs", "provider_config": { "voice_id": "..." } },
          "multilingual_config": {
            "enabled": true,
            "active_language": "en",
            "languages": { }
          }
        }
      }
    ]
  }
}

The top-level transcriber and synthesizer act as the base. Each language in multilingual_config.languages starts from that base and applies its own overrides on top. The agent opens the call in active_language.

Top-level fields

Field	Type	Required	Default	Description
`enabled`	boolean	yes	`false`	Must be `true` for multilingual to take effect. When `false` (or omitted), the object is dropped and the agent runs single-language.
`active_language`	string	no	`"en"`	Language code the agent starts the call in. Must be a key in `languages`.
`languages`	object	yes	—	Map of language code to a per-language config. Minimum 2 languages.
`language_switch_trigger`	string	no	`"requested_or_auto_detected"`	When the agent may change language. `"requested_or_auto_detected"` allows both caller requests and automatic detection; `"caller_requested"` restricts switching to explicit caller requests. This is what the dashboard’s language switching dropdown sets.

Two validation rules are enforced on agent create and update:

languages must contain at least 2 entries.
active_language must be one of the keys in languages.

Failing either returns Invalid multilingual config and the agent is not saved.

Per-language entry

Each value in languages is keyed by an ISO 639-1 code and has this shape:

{
  "hi": {
    "transcriber": {
      "language": "hi"
    },
    "synthesizer": {
      "provider": "sarvam",
      "provider_config": {
        "voice_id": "anushka",
        "model": "bulbul:v2"
      }
    },
    "system_prompt": "आप एक सहायक एजेंट हैं। हिंदी में संक्षेप में उत्तर दें।",
    "handoff_message": "ठीक है, मैं हिंदी में बात करता हूँ।",
    "agent_name": "राज"
  }
}

Field	Type	Required	Description
`transcriber`	object	no	Speech-to-text override for this language. If omitted, the base transcriber is used with the language code applied. Must include `language`; extra provider fields are allowed (for example `model`, `language_hints`).
`synthesizer`	object	yes	Text-to-speech config for this language. Requires `provider` and `provider_config`. Optional `buffer_size`. Extra fields are allowed.
`system_prompt`	string	no	Prompt activated while the agent speaks this language. Write it in the language’s native script.
`handoff_message`	string	no	Message played when the agent switches to this language. Shown as Hand-in message in the dashboard.
`agent_name`	string	no	Agent name used while speaking this language.

How overrides layer onto the base

Transcriber: the per-language transcriber is merged onto the base transcriber, then the language field is resolved to the provider’s expected format (for example Sarvam hi becomes hi-IN). If you omit transcriber, the base transcriber is reused with the language code set to the entry’s key.
Synthesizer: if the per-language provider matches the base, only the differing keys (including a shallow merge of provider_config) are applied. If the provider differs, the per-language synthesizer replaces the base entirely. For sarvam, smallest, cartesia, openai, pixa, and polly, the language is resolved into provider_config.language automatically.

This lets each language use a different STT and TTS provider — see Per-Language Configuration for a worked example.

Full example

A two-language agent (English default, Hindi additional) with a different STT and TTS provider per language:

{
  "agent_config": {
    "tasks": [
      {
        "tools_config": {
          "transcriber": {
            "provider": "deepgram",
            "model": "nova-3",
            "language": "en"
          },
          "synthesizer": {
            "provider": "elevenlabs",
            "provider_config": {
              "voice_id": "21m00Tcm4TlvDq8ikWAM",
              "model": "eleven_turbo_v2_5"
            }
          },
          "multilingual_config": {
            "enabled": true,
            "active_language": "en",
            "language_switch_trigger": "requested_or_auto_detected",
            "languages": {
              "en": {
                "synthesizer": {
                  "provider": "elevenlabs",
                  "provider_config": {
                    "voice_id": "21m00Tcm4TlvDq8ikWAM",
                    "model": "eleven_turbo_v2_5"
                  }
                },
                "system_prompt": "You are a helpful assistant. Keep replies short.",
                "agent_name": "Alex"
              },
              "hi": {
                "transcriber": {
                  "language": "hi"
                },
                "synthesizer": {
                  "provider": "sarvam",
                  "provider_config": {
                    "voice_id": "anushka",
                    "model": "bulbul:v2"
                  }
                },
                "system_prompt": "आप एक सहायक एजेंट हैं। हिंदी में संक्षेप में उत्तर दें।",
                "handoff_message": "ठीक है, मैं हिंदी में बात करता हूँ।",
                "agent_name": "राज"
              }
            }
          }
        }
      }
    ]
  }
}

Supported languages

See the Multilingual Support guide for the full list of language codes valid as keys in languages. Provider support varies by language. Pick an STT and TTS provider per language that covers it. For Indian languages, Sarvam covers the widest set.

Next Steps

Multilingual Support

Set up the same agent from the dashboard

How Language Switching Works

The detection engine behind language_switch_trigger

Auto-Switch Languages

Auto-detect and switch system messages by language

Non-English Prompts

Write per-language prompts in native scripts

Multilingual Agent Quickstart

Build a two-language agent over the API step by step

Overview & Evaluation

Concepts

Build & Configure Agents

Voice & Knowledge

Workflows

Integrations

Multilingual Voice Agents

Advanced Capabilities

Graph Agents

Enterprise & Security

Pricing

Multilingual Config Reference

Where it lives

Top-level fields

Per-language entry

How overrides layer onto the base

Full example

Supported languages

Next Steps

Multilingual Support

How Language Switching Works

Auto-Switch Languages

Non-English Prompts

Multilingual Agent Quickstart

​Where it lives

​Top-level fields

​Per-language entry

​How overrides layer onto the base

​Full example

​Supported languages

​Next Steps

Multilingual Support

How Language Switching Works

Auto-Switch Languages

Non-English Prompts

Multilingual Agent Quickstart

Where it lives

Top-level fields

Per-language entry

How overrides layer onto the base

Full example

Supported languages

Next Steps