# Per-call languages (/docs/per-call-languages)

> Set the languages an agent speaks on one specific call, chosen at dial time, without changing the agent's own configuration.

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 [#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 [#dialling-one-call]

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

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

The response tells you what was used:

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

  A call is never rejected because of a language name. Any name that is not
  recognised is listed in `languages_ignored` and skipped. If none of the names
  are recognised, the agent's own languages are used and the call still goes
  out.

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 [#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.

```json
{
  "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 [#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.

  
    Add a `__languages` column to your file. Separate multiple languages with a
    pipe. Commas work too, but a pipe avoids fighting your spreadsheet's own
    comma handling.

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

    Leave the cell empty for any contact who should use the agent's own languages.
    Every other column keeps working as a normal variable you can use in the
    agent's prompt.
  

  
    Add `__languages` to the contact, alongside your other fields.

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

    The same key works when adding contacts to a dynamic campaign.
  

## Dialling by pincode [#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.

```json
{
  "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 [#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.

| State            | PIN prefixes                   | Languages, opening language first    |
| ---------------- | ------------------------------ | ------------------------------------ |
| Delhi            | 11                             | Hindi, English (India), Punjabi      |
| Haryana          | 12, 13                         | Hindi, English (India)               |
| Punjab           | 14, 15, 16                     | Punjabi, Hindi, English (India)      |
| Himachal Pradesh | 17                             | Hindi, English (India)               |
| Jammu & Kashmir  | 18, 19                         | Urdu, Hindi, English (India)         |
| Uttar Pradesh    | 20, 21, 22, 23, 25, 26, 27, 28 | Hindi, English (India), Urdu         |
| Uttarakhand      | 24                             | Hindi, English (India)               |
| Rajasthan        | 30, 31, 32, 33, 34             | Hindi, English (India)               |
| Gujarat          | 36, 37, 38, 39                 | Gujarati, Hindi, English (India)     |
| Maharashtra      | 40, 41, 42, 43, 44             | Marathi, Hindi, English (India)      |
| Madhya Pradesh   | 45, 46, 47, 48                 | Hindi, English (India)               |
| Chhattisgarh     | 49                             | Hindi, English (India)               |
| Telangana        | 50                             | Telugu, Hindi, Urdu, English (India) |
| Andhra Pradesh   | 51, 52, 53                     | Telugu, Hindi, English (India)       |
| Karnataka        | 56, 57, 58, 59                 | Kannada, Hindi, English (India)      |
| Tamil Nadu       | 60, 61, 62, 63, 64             | Tamil, English (India)               |
| Kerala           | 67, 68, 69                     | Malayalam, English (India), Hindi    |
| West Bengal      | 70, 71, 72, 73, 74             | Bengali, Hindi, English (India)      |
| Odisha           | 75, 76, 77                     | Odia, Hindi, English (India)         |
| Assam            | 78                             | Bengali, Hindi, English (India)      |
| North East       | 79                             | English (India), Hindi               |
| Bihar            | 80, 81, 84, 85                 | Hindi, English (India), Urdu         |
| Jharkhand        | 82, 83                         | Hindi, English (India)               |

## Parameter [#parameter]

Use the same language names shown in your agent's language selector. See
[Voices and languages](/docs/dashboard-guides/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 [#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.

  If you use per-call languages, turn on the dynamic welcome message for that
  agent. With a fixed welcome message the greeting stays in its original
  language, though the rest of the conversation still follows the languages you
  sent.

## What the greeting will sound like [#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.

  Without `__languages`, nothing about your greeting changes. A call that does
  not set it still speaks your welcome message exactly as written.

## Before you rely on it [#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 [#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.

| Language    | Soniox | Smallest |
| ----------- | ------ | -------- |
| Bengali     | Yes    | Yes      |
| English     | Yes    | Yes      |
| Gujarati    | Yes    | Yes      |
| Hindi       | Yes    | Yes      |
| Kannada     | Yes    | Yes      |
| Malayalam   | Yes    | Yes      |
| Marathi     | Yes    | Yes      |
| **Odia**    | **No** | Yes      |
| **Punjabi** | Yes    | **No**   |
| Tamil       | Yes    | Yes      |
| Telugu      | Yes    | Yes      |
| **Urdu**    | Yes    | **No**   |

**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:

| State          | On Smallest, transcription falls back to |
| -------------- | ---------------------------------------- |
| Telangana      | Telugu only                              |
| Andhra Pradesh | Telugu only                              |
| Karnataka      | Kannada only                             |
| Kerala         | Malayalam only                           |

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 [#frequently-asked-questions]

  
    No. The languages apply to the one call you dialled. The agent's saved
    configuration is untouched, and other calls running at the same time are
    unaffected.
  

  
    The name is ignored and the call still goes out. On a single dispatch the
    response lists it under `languages_ignored`. If every name is unrecognised,
    the call runs in the agent's own languages.
  

  
    Yes, within the languages you sent. If you send Tamil and English, the agent
    follows the caller between those two. It will not switch to a language you did
    not send.
  

  
    Yes. A retried or rescheduled contact is called with the same languages as the
    original attempt, so a callback continues in the language of the conversation
    it refers to.
  

  
    No. It is a dialling instruction, not a variable. It is removed before your
    other fields are passed to the agent, so it never appears in the conversation
    context.
  

  
    Anywhere you already send custom variables: a dispatched call, a web call
    session, and a bulk campaign contact.
  

  
    Not when you send `__languages`. Your welcome message becomes the brief for
    the opening line, and the agent composes a natural greeting in the opening
    language carrying the same purpose and facts. Word-for-word translation sounds
    translated, which is worse on the first line of a call. Calls without
    `__languages` are unaffected and still say your welcome message as written.
  

  
    No. The languages are chosen when the call is started, and an inbound caller
    arrives without that step, so inbound calls use the agent's configured
    languages.
  

## Related [#related]

  " title="Voices and languages" href="/docs/dashboard-guides/voices-and-languages" description="The languages and voices available, and how to configure them on an agent." />

  " title="Bulk calls" href="/docs/bulk-calls/overview" description="Run a campaign from a contact list, with per-contact fields." />

  " title="Dispatch call API" href="/docs/api-reference/calls/dispatchCall" description="Full request and response reference for dialling a single call." />