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.
`switch_tool_description`	string	no	—	Overrides the description of the `switch_language` tool the LLM uses to change languages mid-call.

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.
`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. A common setup uses Deepgram for English transcription and Sarvam for Hindi, with ElevenLabs voice for English and Sarvam voice for Hindi.

Language switching

Once multilingual_config is enabled, Bolna injects a switch_language tool so the LLM can change language mid-call, and runs language detection in parallel so the agent can follow the caller automatically.

Prompt-driven: describe when to switch in your prompt (for example “switch to Hindi if the user speaks Hindi”). The LLM calls switch_language and the transcriber, synthesizer, and active system prompt all switch together.
Auto-detection: after a few conversation turns Bolna identifies the dominant language and switches system messages to match. See Auto-Switch Languages.
switch_tool_description: customize how the switch tool is described to the LLM when you need tighter control over switching behavior.

Full example

A two-language agent (English primary, Hindi secondary) 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",
            "switch_tool_description": "Switch the conversation language when the caller changes language.",
            "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

Language	Code	Language	Code	Language	Code
English	`en`	Hindi	`hi`	Bengali	`bn`
Assamese	`as`	French	`fr`	Gujarati	`gu`
Indonesian	`id`	Kannada	`kn`	Malay	`ms`
Malayalam	`ml`	Marathi	`mr`	Odia	`od`
Punjabi	`pa`	Spanish	`es`	Tamil	`ta`
Telugu	`te`	Urdu	`ur`	Dutch	`nl`

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

Auto-Switch Languages

Auto-detect and switch system messages by language

Non-English Prompts

Write per-language prompts in native scripts

Create Agent API

Full agent creation API reference

Overview & Evaluation

Concepts

Build & Configure Agents

Voice & Knowledge

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

Language switching

Full example

Supported languages

Next Steps

Multilingual Support

Auto-Switch Languages

Non-English Prompts

Create Agent API

​Where it lives

​Top-level fields

​Per-language entry

​How overrides layer onto the base

​Language switching

​Full example

​Supported languages

​Next Steps

Multilingual Support

Auto-Switch Languages

Non-English Prompts

Create Agent API

Where it lives

Top-level fields

Per-language entry

How overrides layer onto the base

Language switching

Full example

Supported languages

Next Steps