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

# Multilingual Agent Quickstart

> Build a two-language voice agent via the API — start from a single-language agent, add a second language, and confirm the switch works.

This guide builds a working **English + Hindi** agent over the API in a few steps. Prefer clicking through a UI instead? Use the [dashboard guide](/docs/customizations/multilingual-languages-support) — it covers the exact same setup without any code.

<Info>
  Don't have a key yet? Follow [Generate an API key](/docs/api-reference/introduction) first. Telephone calls consume wallet credits, so keep a test number handy.
</Info>

## Prerequisites

* A Bolna API key (`export BOLNA_API_KEY="bn-xxxx"`)
* A recipient phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format, e.g. `+919876543210`
* A voice and transcription provider for each language — this guide uses ElevenLabs (English) and Sarvam (Hindi); see [supported providers](/docs/providers) for other options

<Steps>
  <Step title="Start from a single-language agent">
    This is the same minimal body as the [API Quickstart](/docs/quickstarts/api) — nothing multilingual yet:

    ```json theme={"system"}
    {
      "agent_config": {
        "agent_name": "Support Agent",
        "agent_welcome_message": "Hi! How can I help you today?",
        "tasks": [{
          "task_type": "conversation",
          "toolchain": { "execution": "sequential", "pipelines": [["transcriber", "llm", "synthesizer"]] },
          "tools_config": {
            "llm_agent": {
              "agent_type": "simple_llm_agent",
              "agent_flow_type": "streaming",
              "llm_config": { "provider": "openai", "model": "gpt-4.1-mini", "max_tokens": 150, "temperature": 0.2 }
            },
            "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en", "stream": true, "encoding": "linear16", "sampling_rate": 16000, "endpointing": 250 },
            "synthesizer": { "provider": "elevenlabs", "provider_config": { "voice_id": "21m00Tcm4TlvDq8ikWAM", "model": "eleven_turbo_v2_5" }, "stream": true, "buffer_size": 250, "audio_format": "wav" },
            "input": { "provider": "plivo", "format": "wav" },
            "output": { "provider": "plivo", "format": "wav" }
          },
          "task_config": { "call_terminate": 90, "hangup_after_silence": 10 }
        }]
      },
      "agent_prompts": { "task_1": { "system_prompt": "You are a helpful support assistant. Keep replies short." } }
    }
    ```
  </Step>

  <Step title="Add a multilingual_config block">
    Add `multilingual_config` inside the same `tools_config`, with an entry for each language. The top-level `transcriber`/`synthesizer` from Step 1 become the English entry's base:

    ```json theme={"system"}
    "multilingual_config": {
      "enabled": true,
      "active_language": "en",
      "languages": {
        "en": {
          "system_prompt": "You are a helpful support assistant. Keep replies short."
        },
        "hi": {
          "transcriber": { "language": "hi" },
          "synthesizer": { "provider": "sarvam", "provider_config": { "voice_id": "anushka", "model": "bulbul:v2" } },
          "system_prompt": "आप एक सहायक सपोर्ट एजेंट हैं। संक्षेप में उत्तर दें।",
          "handoff_message": "ठीक है, मैं हिंदी में बात करता हूँ।",
          "agent_name": "राज"
        }
      }
    }
    ```

    `enabled: true` and at least two entries in `languages` are required. See the [Config Reference](/docs/customizations/multilingual-config-reference) for every field, how per-language overrides layer onto the base, and `language_switch_trigger`.
  </Step>

  <Step title="Create the agent">
    Nest the block from Step 2 into Step 1's `tools_config` and create the agent:

    <CodeGroup>
      ```bash curl theme={"system"}
      curl https://api.bolna.ai/v2/agent \
        -H "Authorization: Bearer $BOLNA_API_KEY" \
        -H "Content-Type: application/json" \
        -d @agent.json
      ```

      ```python Python theme={"system"}
      import os, urllib.request, json

      with open("agent.json") as f:
          body = json.load(f)

      req = urllib.request.Request(
          "https://api.bolna.ai/v2/agent",
          data=json.dumps(body).encode(),
          headers={"Authorization": f"Bearer {os.environ['BOLNA_API_KEY']}",
                   "Content-Type": "application/json"},
      )
      print(json.load(urllib.request.urlopen(req)))
      ```
    </CodeGroup>

    ```json 201 Response theme={"system"}
    { "agent_id": "123e4567-e89b-12d3-a456-426655440000", "state": "created" }
    ```
  </Step>

  <Step title="Place a test call">
    Call it exactly as in the [API Quickstart](/docs/quickstarts/api), using this `agent_id`. Answer in English, then reply in Hindi — the agent should switch recognition, voice, and replies together within that turn. See [How Language Switching Works](/docs/customizations/language-switching-behavior) for exactly what should (and shouldn't) trigger a switch, and pull the transcript from [`GET /executions/{id}`](/docs/api-reference/executions/get_execution) to confirm.
  </Step>
</Steps>

## Adding this to an existing agent

`multilingual_config` lives under `tools_config`, which isn't in the [`PATCH`](/docs/api-reference/agent/v2/patch_update) endpoint's updatable-attributes list. To add multilingual support to an agent you already have, use [`PUT /v2/agent/{agent_id}`](/docs/api-reference/agent/v2/update) with your full existing config plus the `multilingual_config` block from Step 2 — `PUT` replaces the whole agent, so include everything, not just what changed.

## Next steps

<CardGroup cols={2}>
  <Card title="How Language Switching Works" icon="ear-listen" href="/docs/customizations/language-switching-behavior">
    The decision engine behind mid-call switching, and what triggers it
  </Card>

  <Card title="Config Reference (API)" icon="code" href="/docs/customizations/multilingual-config-reference">
    Every `multilingual_config` field, in depth
  </Card>

  <Card title="Auto-Switch System Messages" icon="shuffle" href="/docs/customizations/auto-switch-multilingual-messages">
    Localize the hangup, user-online, and tool-call messages too
  </Card>

  <Card title="Non-English Prompts" icon="language" href="/docs/writing-prompts-in-non-english-languages">
    Write each language's prompt well — native script, code-mixing, register
  </Card>
</CardGroup>