> ## Documentation Index
> Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Start a Call in a Chosen Language
> Start a multilingual Bolna voice agent's call in any of its configured languages, per call, with agent_data.language on the API or an agent_language variable in batches, inbound data, and workflows.
A [multilingual agent](/docs/customizations/multilingual-languages-support) normally opens every call in its default language (`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](/docs/customizations/language-switching-behavior) behaviour for the rest of the call.
Starting in a language switches the starting transcriber, voice, and per-language prompt together, and the welcome message is spoken in that language's voice. Calls that don't ask for a language behave exactly as before.
***
## Two ways to set it
| Method | Where it works | Example |
| - | - | - |
| **`agent_data.language`** | [`POST /call`](/docs/api-reference/calls/make) and the web-call [session mint](/docs/developer-resources/sdks/web-call#start-in-a-chosen-language) | `"agent_data": { "language": "hi" }` |
| **`agent_language` variable** | Anywhere call variables are set: `user_data` on `/call`, a [batch](/docs/outbound/batch-calling) CSV column, [inbound caller data](/docs/customizations/identify-incoming-callers) (CSV, Google Sheet, or API), [inbound SIP header](/docs/sip-trunking/byot-inbound-headers) mappings, and workflow variables | `"user_data": { "agent_language": "hi" }` |
The value must be one of the language keys in the agent's `multilingual_config.languages` (the languages you added in the [Agent Tab](/docs/agent-setup/agent-tab#managing-languages)). 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
Pass `language` inside `agent_data`:
```bash curl theme={"system"}
curl https://api.bolna.ai/call \
-H "Authorization: Bearer $BOLNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "123e4567-e89b-12d3-a456-426655440000",
"recipient_phone_number": "+919876543210",
"agent_data": { "language": "hi" }
}'
```
```python Python theme={"system"}
import os, requests
requests.post(
"https://api.bolna.ai/call",
headers={"Authorization": f"Bearer {os.environ['BOLNA_API_KEY']}"},
json={
"agent_id": "123e4567-e89b-12d3-a456-426655440000",
"recipient_phone_number": "+919876543210",
"agent_data": {"language": "hi"},
},
)
```
Or, equivalently, as a call variable in `user_data`:
```json theme={"system"}
{
"agent_id": "123e4567-e89b-12d3-a456-426655440000",
"recipient_phone_number": "+919876543210",
"user_data": { "agent_language": "hi", "name": "Asha" }
}
```
The language is checked when you place the call. `/call` returns a `400` when:
* the language is not configured on the agent (the error lists the allowed ones)
* `agent_data.language` is set on a single-language agent
* `agent_data.language` and `user_data.agent_language` name different languages
* `agent_data.voice_id` is sent together with a language: each language speaks with its own configured voice, so the voice override would be ignored
If the request pins an `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 an `agent_language` column to the CSV:
```csv batch_with_languages.csv theme={"system"}
contact_number,first_name,agent_language
+919876543210,Asha,hi
+919812345678,Karthik,ta
+14155550123,Emma,en
+919900112233,Ravi,
```
Each row starts in its own language. A blank cell means the row starts in the agent's default language.
Rows are checked when the batch is uploaded. A row naming a language the agent doesn't have is marked `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, return `agent_language` as a field from your [caller data source](/docs/customizations/identify-incoming-callers) (CSV, Google Sheet, or API), or map a carrier's [SIP header](/docs/sip-trunking/byot-inbound-headers) to a variable named `agent_language`. In workflows, set it as a workflow variable.
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
| Component | Behaviour when a call starts in a chosen language |
| - | - |
| Transcriber | Starts on that language's transcriber |
| Voice | Starts on that language's voice |
| Prompt | Uses that language's prompt, including per-language rich prompts |
| Welcome message audio | Spoken in that language's voice |
| Welcome message text | **Unchanged.** The welcome message is a single string. For a per-language greeting, put a variable in it (for example `{{greeting}}`) and pass the localized text with the call |
| Default filler and transfer messages | Use the chosen language |
| Mid-call switching | Works as usual. The chosen language is only where the call starts |
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.
***
## Checking which language a call started in
Whenever a call asks for a language, the execution records both the requested and the applied value under `usage_breakdown.agent_language`:
```json theme={"system"}
"agent_language": { "requested": "HI", "applied": "hi" }
```
An `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}`](/docs/api-reference/executions/get_execution).
***
## Next Steps
Add languages, voices, and per-language prompts
What happens after the call starts
The `multilingual_config` object and `active_language`
CSV format and running batches