active_language). When you already know the customer’s likely language, from your CRM, the campaign, or the region, you can start that call in any other language the agent has configured instead. The agent keeps its full language switching behavior for the rest of the call.
Starting in a language switches the starting transcriber, voice, and per-language prompt together, and the call opens with that language’s own welcome message when one is set. Calls that don’t ask for a language behave exactly as before.
Two ways to set it
The value must be one of the language keys in the agent’s
multilingual_config.languages (the languages you added in the Agent Tab). It is matched case-insensitively, so HI and hi both start the call in Hindi.
Precedence
agent_data.language wins over the agent_language variable, which wins over the agent’s default language. On /call and the web-call mint, setting both to different languages is rejected with a 400; set only one.
Single-language agents
agent_language only picks a language on a multilingual agent. On any other agent it stays an ordinary prompt variable, so existing agents that already use a variable with that name keep working unchanged. agent_data.language, on the other hand, returns a 400 on a single-language agent.
From the call API
Passlanguage inside agent_data:
user_data:
/call returns a 400 when:
- the language is not configured on the agent (the error lists the allowed ones)
agent_data.languageis set on a single-language agentagent_data.languageanduser_data.agent_languagename different languagesagent_data.voice_idis sent together with a language: each language speaks with its own configured voice, so the voice override would be ignored
agent_version_id, the language is checked against that version’s languages. Scheduled calls keep their language until they fire, and a callback the agent books when the caller asks to be called back later starts in the same language as the original call.
From a batch
Add anagent_language column to the CSV:
batch_with_languages.csv
error with the reason, just like a row with a bad phone number, and the rest of the batch runs normally.
From inbound calls and workflows
For inbound calls, returnagent_language as a field from your caller data source (CSV, Google Sheet, or API). In workflows, set it as a workflow variable.
You can also map a carrier’s SIP header to a variable named agent_language: a custom X- header such as X-Language on SIP trunks, or any SIP header on Legacy SIP trunks (deprecated).
These paths have no request to reject, so an unknown language doesn’t fail the call: it starts in the agent’s default language instead.
What changes, and what doesn’t
Every call is checked once more when it is prepared, against the agent version it actually runs. If the language is no longer on the agent (for example, it was removed after a batch was uploaded), the call starts in the default language rather than failing.
Welcome message per language
Each language can have its own welcome message, so a call that starts in Hindi greets in Hindi without any extra call data. Set it from the Translations button in the welcome message field, in the Agent Tab or the graph agent editor, or aswelcome_message on the language’s entry over the API.
The call picks its welcome message in this order:
- The welcome message of the language the call starts in: the one passed with
agent_data.languageoragent_language, or the default language when none is passed - The agent’s welcome message (
agent_welcome_message), when that language has none or it is blank
Variables work in every language’s message, for example
नमस्ते {{name}}, and take their values from the same call data as the rest of the agent. You no longer need a {{greeting}} variable with localized text in every call or CSV row to greet in the caller’s language.
Checking which language a call started in
Whenever a call asks for a language, the execution records both the requested and the applied value underusage_breakdown.agent_language:
applied of null means the requested language wasn’t available and the call fell back to the agent’s default language. Fetch it with GET /executions/{execution_id}.
Next steps
Multilingual support
Add languages, voices, and per-language prompts
How language switching works
What happens after the call starts
Config reference (API)
The
multilingual_config object and active_languageBatch calling
CSV format and running batches