It’s best not to write language-switching instructions into your prompt — the system handles switching itself, independently of what your prompt says.
What changes on a switch
When the agent decides the caller has moved to a different configured language, three things change together, mid-call:Recognition
Speech-to-text starts transcribing the new language accurately.
Voice
Text-to-speech speaks in the voice you set for that language.
Replies
The agent commits to the new language until the caller clearly moves again.
The decision engine: two listeners, one decision per turn
You don’t need the internals to use the feature — see Setting Up Languages for that — but this model explains almost every “why did, or didn’t, it switch?” question. While your agent talks, two things listen at once:
At the end of each thing the caller says, Bolna compares the two and asks: is the caller now substantively speaking a different supported language? If yes, it switches; if it’s a stray English word, a “hello”, or a phone number, it stays put.
It never gets stuck
It never gets stuck
If a caller says something the current recognizer can’t decode and then pauses, the agent still evaluates it using the background detector, instead of waiting forever in the wrong language.
This is the default 'requested or auto detected' behavior
This is the default 'requested or auto detected' behavior
If you set the switch trigger to “the caller requested for it,” the background detector still listens, but the agent only switches when the caller explicitly asks — directly requesting a language, asking “can you speak X?”, or answering the agent’s own question about which language to use. Simply speaking another language won’t move it.Over the API this is the
language_switch_trigger field: "requested_or_auto_detected" (the default, described above) or "caller_requested" (explicit-only). See the Config Reference for the full field definition.What triggers a switch — and what doesn’t
The agent is deliberately conservative: it switches when a caller has genuinely moved to another language, and ignores the everyday word-mixing of natural speech. (This describes the default “requested or auto detected” trigger. If you’ve set the agent to “the caller requested for it,” only the explicit requests in the first column below switch it — everything else stays put.)- ✅ It switches when…
- ❌ It stays put when…
Closely related languages get extra care. Look-alike languages — Hindi / Marathi / Urdu, or the Telugu / Tamil / Kannada / Malayalam group — are decided from the grammar of the sentence, not a single word, so the agent doesn’t flap back and forth. A switch between two similar languages needs a clearer signal than English → Hindi.
Supported languages for automatic detection
The languages your agent can switch between are exactly the ones you add to it. Automatic detection itself is tuned for English and the major Indian languages:Bolna handles additional languages across the platform (for example French, Spanish, and Dutch — see the full supported-language list), but mid-call auto-switching is centered on the eleven languages above. Each language you add also needs a voice and transcription provider that supports it — coverage varies by provider, so choose your per-language providers accordingly.
Getting the best results
Set a native voice for every language
The single biggest quality lever. Leaving a secondary language on a default English voice is the most common mistake — a Hindi switch spoken in an English voice sounds wrong.
Write each prompt in its native script
With localized examples — not a translated-on-the-fly English prompt.
Add every language callers might use
The agent can only switch to languages you’ve configured.
Choose your default language carefully
Pick the one most calls open in, so the opening turn is right before any switch.
Cover system messages for every language
So a caller who switches doesn’t hear an English fallback mid-conversation. See Auto-Switch Languages.
Test with real, code-mixed speech
A full sentence in the second language (should switch), a sentence with one English word dropped in (should not), and a number read-out (should not).
Troubleshooting
My agent isn't switching
My agent isn't switching
Check, in order:
- Are at least two languages configured on the agent (multilingual enabled)?
- Is the language the caller is speaking added to the agent, with a voice set?
- Is the caller saying a full phrase in that language — not just a word or a number?
- Is the switch trigger set to “the caller requested for it”? In that mode the caller has to explicitly ask — just speaking the language won’t switch it. Use “requested or auto detected” for automatic switching.
It switched when the caller said only one English word
It switched when the caller said only one English word
It shouldn’t — a single borrowed word is treated as code-mixing and the agent should stay. If it’s consistent, report it with the call recording.
It switched while the caller read out an order number or OTP
It switched while the caller read out an order number or OTP
It shouldn’t — numbers, codes, and spelled-out identifiers are ignored as language evidence. Report the call if it happens.
It keeps flip-flopping between two similar languages
It keeps flip-flopping between two similar languages
Similar languages (e.g. Hindi / Marathi) are the hardest case. Make sure both are configured on the agent with the correct voice and transcription — the agent can only settle on languages you’ve actually set up.
Once it switches, will it switch back on its own?
Once it switches, will it switch back on its own?
Only when the caller clearly moves again. After a switch the agent commits to the new language, so a single stray word won’t bounce it back.
Next Steps
Multilingual Support
Set up languages, prompts, and hand-in messages
Auto-Switch System Messages
Localize hangup, user-online, and tool-call messages
Config Reference (API)
The
multilingual_config object and language_switch_triggerNon-English Prompts
Write per-language prompts in native scripts