Multilingual Agent Quickstart

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 — it covers the exact same setup without any code.

Don’t have a key yet? Follow Generate an API key first. Telephone calls consume wallet credits, so keep a test number handy.

Prerequisites

A Bolna API key (export BOLNA_API_KEY="bn-xxxx")
A recipient phone number in 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 for other options

Start from a single-language agent

This is the same minimal body as the API Quickstart — nothing multilingual yet:

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

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:

"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 for every field, how per-language overrides layer onto the base, and language_switch_trigger.

Create the agent

Nest the block from Step 2 into Step 1’s tools_config and create the agent:

curl https://api.bolna.ai/v2/agent \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent.json

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)))

201 Response

{ "agent_id": "123e4567-e89b-12d3-a456-426655440000", "state": "created" }

Place a test call

Call it exactly as in the API Quickstart, 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 for exactly what should (and shouldn’t) trigger a switch, and pull the transcript from GET /executions/{id} to confirm.

Adding this to an existing agent

multilingual_config lives under tools_config, which isn’t in the PATCH endpoint’s updatable-attributes list. To add multilingual support to an agent you already have, use PUT /v2/agent/{agent_id} 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

How Language Switching Works

The decision engine behind mid-call switching, and what triggers it

Config Reference (API)

Every multilingual_config field, in depth

Auto-Switch System Messages

Localize the hangup, user-online, and tool-call messages too

Non-English Prompts

Write each language’s prompt well — native script, code-mixing, register

Quickstarts

Phone Numbers & Calling Setup

Outbound Calling

Inbound Calling

Native Telephony Integrations

Managing Live Calls

Prompting & Personalization

Tools & Function Calling

Post-Call & Analytics

No-Code & Automation

SIP Trunking Guide

Multilingual Agent Quickstart

Prerequisites

Adding this to an existing agent

Next steps

How Language Switching Works

Config Reference (API)

Auto-Switch System Messages

Non-English Prompts

​Prerequisites

​Adding this to an existing agent

​Next steps

How Language Switching Works

Config Reference (API)

Auto-Switch System Messages

Non-English Prompts

Prerequisites

Adding this to an existing agent

Next steps