Multi-Language Support

Voisnap agents can detect and respond in multiple languages automatically. This guide covers language detection, supported languages, per-language voice configuration, and prompt best practices.

---

How language detection works

By default, Voisnap's STT layer detects the language of the user's first utterance and switches the agent to respond in that language. The detection happens within the first 2–3 seconds of speech.

When a language is detected:

1. STT continues transcribing in the detected language
2. The LLM is instructed to respond in the same language
3. TTS synthesizes audio in the detected language (using the fallback voice if no specific voice is configured)

---

Supported languages

The following languages are supported for auto-detection and full conversation (STT + LLM + TTS):

Language	BCP 47 Code	Auto-detect	Notes
English (US)	en-US	✓	Default
English (UK)	en-GB	✓
English (AU)	en-AU	✓
Spanish (Latin America)	es-419	✓
Spanish (Spain)	es-ES	✓
French	fr-FR	✓
French (Canada)	fr-CA	✓
German	de-DE	✓
Portuguese (Brazil)	pt-BR	✓
Portuguese (Portugal)	pt-PT	✓
Italian	it-IT	✓
Dutch	nl-NL	✓
Polish	pl-PL	✓
Japanese	ja-JP	✓
Korean	ko-KR	✓
Chinese (Mandarin, Simplified)	zh-CN	✓
Chinese (Mandarin, Traditional)	zh-TW	✓
Arabic	ar	✓
Hindi	hi-IN	✓
Russian	ru-RU	✓
Turkish	tr-TR	✓
Swedish	sv-SE	✓
Norwegian	nb-NO	✓
Danish	da-DK	✓

---

Enable auto-detection

client.agents.update(
    AGENT_ID,
    transcription={
        "provider": "deepgram",
        "model": "nova-2",
        "language": "auto",      # enables auto-detection
        "detect_language": True,
    }
)

---

Override language per session

For channels where you already know the user's language (e.g., a Spanish-language landing page), override at the session level:

Outbound call:

call = client.outbound_calls.create(
    agent_id=AGENT_ID,
    to_number="+34912345678",
    metadata={"requested_language": "es-ES"}
)

Web widget:

<script
  src="https://cdn.voisnap.ai/widget/v1/widget.js"
  data-agent-id="agt_01HXK8Z3MNPQRS"
  data-locale="es-419"
  defer
></script>

VoiceHub / WebRtcHub:

wss://api.voisnap.ai/hubs/voice?agentId=...&language=es-419&access_token=...

---

Configure per-language voices

If you want a native-sounding voice for each language, configure languageVoices:

client.agents.update(
    AGENT_ID,
    language_voices={
        "en-US": {
            "provider": "elevenlabs",
            "voice_id": "EXAVITQu4vr4xnSDxMaL",  # Bella (English)
        },
        "es-419": {
            "provider": "elevenlabs",
            "voice_id": "AZnzlk1XvdvUeBnXmlld",  # Domi (Spanish)
        },
        "fr-FR": {
            "provider": "elevenlabs",
            "voice_id": "MF3mGyEYCl7XYWbV9V6O",  # Elli (French)
        },
        "de-DE": {
            "provider": "google",
            "voice_id": "de-DE-Wavenet-F",
        },
        "pt-BR": {
            "provider": "aws",
            "voice_id": "Camila",
        }
    }
)

If a detected language has no specific voice configured, Voisnap falls back to the agent's default voice (which may produce an accent).

---

Per-language system prompts

For best results, add language-specific instructions to your system prompt:

You are Aria, a multilingual customer support agent for Acme Corp.

## Language behavior
- Always respond in the same language the customer uses
- If you detect a language switch mid-conversation, switch your response language immediately
- For Spanish speakers, use "usted" (formal) for new callers; switch to "tú" only if they use it first
- For French speakers from Canada (detectable by accent or "sacré"), use colloquial Québécois expressions
- Greet Japanese customers with "よろしくお願いします" at the start of the call

## Language limitations
- If you receive a language you cannot respond in naturally, respond in English and say:
  "I apologize, I'm not able to assist in [language] right now. Can we continue in English?"

---

Language fallback chain

Configure what happens when the detected language isn't in your supported set:

client.agents.update(
    AGENT_ID,
    language_config={
        "auto_detect": True,
        "default_language": "en-US",
        "supported_languages": ["en-US", "es-419", "fr-FR", "de-DE", "pt-BR"],
        "fallback_behavior": "use_default",  # or "end_call_with_message"
        "fallback_message": "I'm sorry, I can only assist in English, Spanish, French, German, and Portuguese. Goodbye.",
    }
)

---

Testing multi-language

Test each language combination in the sandbox:

test_languages = [
    ("es-419", "+34600000000", "Hola, necesito ayuda con mi pedido"),
    ("fr-FR", "+33600000000", "Bonjour, j'ai une question sur ma facture"),
    ("de-DE", "+49160000000", "Hallo, ich habe eine Frage zu meiner Bestellung"),
]
 
for lang, phone, scenario in test_languages:
    call = client.outbound_calls.create(
        agent_id=AGENT_ID,
        to_number=phone,
        metadata={"requested_language": lang, "test_scenario": scenario}
    )
    print(f"Testing {lang}: {call.id}")