Start a Call in a Chosen Language

A multilingual agent 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 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` and the web-call session mint	`"agent_data": { "language": "hi" }`
`agent_language` variable	Anywhere call variables are set: `user_data` on `/call`, a batch CSV column, inbound caller data (CSV, Google Sheet, or API), inbound SIP header 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). 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:

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" }
  }'

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:

{
  "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:

batch_with_languages.csv

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 (CSV, Google Sheet, or API), or map a carrier’s SIP header 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:

"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}.

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_language

Batch Calling

CSV format and running batches

Overview & Evaluation

Concepts

Build & Configure Agents

Voice & Knowledge

Workflows

Integrations

Multilingual Voice Agents

Advanced Capabilities

Graph Agents

Enterprise & Security

Pricing

Start a Call in a Chosen Language

Two ways to set it

Precedence

Single-language agents

From the Call API

From a batch

From inbound calls and workflows

What changes, and what doesn’t

Checking which language a call started in

Next Steps

Multilingual Support

How Language Switching Works

Config Reference (API)

Batch Calling

​Two ways to set it

​Precedence

​Single-language agents

​From the Call API

​From a batch

​From inbound calls and workflows

​What changes, and what doesn’t

​Checking which language a call started in

​Next Steps

Multilingual Support

How Language Switching Works

Config Reference (API)

Batch Calling

Two ways to set it

Precedence

Single-language agents

From the Call API

From a batch

From inbound calls and workflows

What changes, and what doesn’t

Checking which language a call started in

Next Steps