Per-call languages

An agent has a language list you configure once in the dashboard. Sometimes a single agent needs to serve people who speak different languages: a Tamil batch in the morning, a Hindi and English batch in the afternoon, a mixed list where every contact is different, or a web visitor who should be greeted in their own language.

Send __languages when you start the call and it runs in the languages you name, without touching the agent's own settings and without affecting any other call in flight.

It works anywhere you already send custom variables: a single dispatched call, a web call session, and a bulk campaign contact.

If your contacts carry Indian postal codes rather than language names, send __pincode instead and the platform picks the languages for that state.

What it changes

The languages you send replace the agent's configured list for that one call. They are not added to it.

For the call you dialled, they decide:

• how speech is transcribed, so the caller is understood
• which languages the agent is allowed to reply in
• how the agent follows the caller if they switch language mid-call
• which language the call opens in

Everything else about the agent (its prompt, voice, knowledge base, tools) is unchanged.

Dialling one call

Add __languages to the dispatch request. The first language in the list is the one the call opens in.

{
  "agent_id": 158910,
  "to_number": "+15551234567",
  "__languages": ["Tamil", "English"]
}

The response tells you what was used:

{
  "success": true,
  "requestId": 91422,
  "status": "dispatched",
  "languages_applied": ["Tamil", "English"],
  "languages_ignored": []
}

You can also put __languages inside call_context if that suits your integration better. It behaves the same way, and it is never passed to the agent as a context variable.

Starting a web call

Send it with the session's custom variables when you create the session. The visitor is greeted in the first language you name.

{
  "agent_id": 158910,
  "type": "voice",
  "custom_variables": {
    "name": "Rahul",
    "__languages": "Hindi|Gujarati|English"
  }
}

Either form works here: a pipe-separated string as above, or an array. The key is removed before your other variables reach the agent, so name is passed through and __languages is not.

Dialling a campaign

Languages are set per contact, so one campaign can call each person in their own language. A retried or rescheduled contact keeps the languages it was first given.

phone_number,name,__languages
+15551234567,Rahul,Hindi|English
+15559876543,Meera,Tamil
+15550001111,Arjun,

{
  "contact_list": [
    {
      "phone_number": "+15551234567",
      "name": "Rahul",
      "__languages": ["Hindi", "English"]
    },
    {
      "phone_number": "+15559876543",
      "name": "Meera",
      "__languages": ["Tamil"]
    }
  ]
}

Dialling by pincode

If you hold Indian postal codes rather than language names, send __pincode instead of __languages. The platform reads the first two digits to decide the state and runs the call in that state's languages, so you do not have to keep a mapping of your own.

The value must be a full six digit Indian PIN. Anything else is left alone: a five digit US ZIP, a partial code, or a stray number from another column will not be treated as a pincode, and the call runs on the agent's own languages.

{
  "agent_id": 158910,
  "to_number": "+15551234567",
  "__pincode": "700001"
}

That call opens in Bengali. A contact in 600001 opens in Tamil.

It goes everywhere __languages goes: the dispatch request, custom_variables on a web call session, a __pincode column in a bulk CSV, and a __pincode key on a JSON contact.

Two things work differently from __languages:

• __languages wins. If a contact carries both, the pincode is ignored for that call. That is the per-contact escape hatch: override the state mapping for one person without stripping their pincode.
• The pincode stays a variable. Unlike __languages, it is not removed before your fields reach the agent, so the prompt can still reference where the customer is.

__pincode is India only. A value that does not resolve to a state, such as an army post code, a typo, or a postal code from another country, leaves the call on the agent's own configured languages. It is never guessed at, and it does not fall back to Hindi or English.

Twenty three states are mapped. Goa is not, because its PIN codes sit in the 403 range inside Maharashtra's 40 and it has no two digit prefix of its own; a Goa pincode therefore resolves to Maharashtra. Tell us if that matters for your traffic.

What each state opens in

The first language listed is the one the call opens in. OmniDimension maintains this table, and the set for a state can be tuned.

Parameter

Use the same language names shown in your agent's language selector. See Voices and languages for the full list.

Names are matched without case sensitivity, so tamil, Tamil and TAMIL are the same language. Common alternative spellings are understood too: Bangla for Bengali, Oriya for Odia, and Panjabi for Punjabi. The response echoes back the platform's own spelling of each name it applied.

Which language the call opens in

The first language you send is the opening language. The agent greets the caller in it, and the conversation starts there.

For the greeting itself to be spoken in that language, the agent's welcome message must be set to dynamic. A fixed welcome message is spoken exactly as written, in whatever language you wrote it in.

What the greeting will sound like

Your welcome message is treated as the brief for the opening line, not as words to translate. The agent reads what it is meant to achieve, who is calling, why, and what is being asked, then says that in the opening language the way a native speaker would actually say it on a phone call.

This is deliberate. A word-for-word translation of an English line sounds translated, and the greeting is the first thing the caller hears.

So a welcome message written as:

Hello, am I speaking with Rahul? This is Riya from Acme Finance about your loan application.

dialled with __languages: ["Gujarati"] produces a natural Gujarati greeting carrying the same three things: the caller's name, who is calling, and why. It will not be the same sentence rendered word for word.

What stays fixed:

• the same purpose and the same facts, with nothing added
• no second greeting, no extra self-introduction, no small talk
• at most one question
• names, numbers and company names exactly as you wrote them
• everyday English words a speaker of that language would normally use (appointment, payment, OK) stay in English

If your welcome message is an instruction rather than words to say, for example "Greet with good morning or good evening based on the time of day", it is carried out in the opening language and never read out loud.

Before you rely on it

Check the voice. The agent's voice has to be able to speak the languages you send. A voice that only speaks English will not sound right delivering Tamil, whatever the language settings say. Multilingual voices are marked in the voice library.

Check the speech-to-text engine. Soniox and Smallest accept a list of languages and follow whatever you send. Sarvam detects the language automatically and works as-is. Deepgram, Azure and Cartesia are configured with a single language on the agent and keep using it, so transcription on those engines does not follow the call's languages. If you dial in languages the agent was not built for, use Soniox or Smallest.

Send one language for a single-language call. Sending one name pins the call to that language, exactly like an agent configured with one language.

Check the language is one the speech engine supports. The agent can be configured with any language name, including regional ones such as Bhojpuri or Haryanvi, but the speech-to-text engines do not transcribe all of them. When a language has no equivalent on the engine, the agent still replies in it, but the caller's speech is transcribed without a hint for that language and accuracy drops. Soniox covers Bengali, Gujarati, Hindi, Kannada, Malayalam, Marathi, Punjabi, Tamil, Telugu and Urdu, but not Odia. Smallest covers the same list in streaming, minus Punjabi and Urdu, plus Odia. So an Odisha pincode, which opens in Odia, is transcribed on Smallest and not on Soniox.

Use Soniox for the four southern states. Telangana, Andhra Pradesh, Karnataka and Kerala pair a southern language with Hindi, and that pair spans Smallest's regional auto-detect groups. A Smallest agent falls back to the southern language alone on those calls and loses Hindi and English transcription. Soniox handles every state in the table above correctly.

Which speech-to-text engine to use

The languages a call replies in always follow the pincode. What the agent can hear depends on the engine set on the agent, and the two engines cover different languages.

Use Soniox. It covers every language in the state table except Odia, and it transcribes a multi-language call without further constraints. On Soniox the only gap is Odisha, where the agent still speaks Odia but the caller's Odia is not transcribed with a hint for it.

Smallest has one more restriction. It auto-detects only within fixed regional groups: one group is English, Hindi, Gujarati, Marathi, Bengali and Odia, another is English, Tamil, Telugu, Kannada and Malayalam. A call whose languages span both groups falls back to the first language alone. That affects four states in the table, because each pairs a southern language with Hindi:

Hindi and English are still spoken on those calls, they are just not transcribed. Soniox has no such grouping.

Sarvam detects the language on its own and needs no configuration here. Deepgram, Azure and Cartesia are configured with a single language on the agent and keep using it, so on those engines the caller is transcribed in the agent's configured language whatever the pincode says.

Frequently asked questions

Related