> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # languages > Configure the spoken language of your AI Agent, as well as the TTS engine, voice, and fillers. [tts-providers]: /docs/platform/voice/tts#compare-providers-and-models [voices-and-languages]: /docs/platform/voice/tts [swaig-functions]: /docs/swml/reference/calling/ai/swaig/functions [deepgram-codes]: https://developers.deepgram.com/docs/models-languages-overview#nova-3 [multilingual]: /docs/swml/reference/calling/ai/multilingual [openai-asr-engine]: /docs/swml/reference/calling/ai/params#paramsopenai_asr_engine [turn-filler-sources]: /docs/swml/reference/calling/ai/params#paramsturn_filler_sources [ai-pronounce]: /docs/swml/reference/calling/ai#aipronounce [cartesia]: /docs/platform/voice/tts/cartesia [elevenlabs]: /docs/platform/voice/tts/elevenlabs [fish]: /docs/platform/voice/tts/fish [inworld]: /docs/platform/voice/tts/inworld [minimax]: /docs/platform/voice/tts/minimax [rime]: /docs/platform/voice/tts/rime [smallest]: /docs/platform/voice/tts/smallest Use `ai.languages` to configure the spoken language of your AI Agent, as well as the TTS engine, voice, and fillers. Use [`ai.multilingual`][multilingual] instead when a single call may move between languages and you want the agent to follow the caller. If your agent only ever speaks one language, set the voice on a single entry, or leave `languages` out and set the voice directly. > **Warning** > > `languages` and [`multilingual`][multilingual] are mutually exclusive. If both are set, SignalWire > uses `multilingual` and ignores `languages` entirely. To use `languages`, remove the `multilingual` > key rather than emptying it. ## **Properties** **`ai.languages`** `object[]` An array of objects that accept the following properties. --- **`languages[].name`** `string` — required Name of the language ("French", "English", etc). This value is used in the system prompt to instruct the LLM what language is being spoken. --- **`languages[].code`** `string | string[]` — required Set the language code for ASR (Automatic Speech Recognition) (STT (Speech-to-text)) purposes. By default, SignalWire uses Deepgram's Nova-3 STT engine, so this value should match a code from Deepgram's [Nova-3 language codes table][deepgram-codes]. Supply an array to have this voice listen for up to three codes at once. Set it to `multi` to have the engine transcribe whichever of its supported languages the caller speaks, rather than one fixed language. The agent still answers in this entry's single `voice`. To answer in the caller's language as well, use [`ai.multilingual`][multilingual] instead, which builds on the same code-switching mode and adds a voice per language. > **Info** > > If a different STT model was selected using the [`openai_asr_engine` parameter][openai-asr-engine], you must select a code supported by that engine. --- **`languages[].voice`** `string` — required String format: `.`, with an optional `:` suffix for engines that offer a choice of model. Select engine from `gcloud`, `polly`, `amazon`, `azure`, `openai`, `elevenlabs`, `deepgram`, `cartesia`, `rime`, `inworld`, `minimax`, `groq-tts`, `mistral`, `grok`, `smallest`, `fish`, or `speechify`. Select voice from [TTS provider reference][tts-providers]. For example, `"gcloud.fr-FR-Neural2-B"` or `"elevenlabs.rachel:eleven_flash_v2_5"`. Always name the engine: a bare voice id resolves against a default engine that can change. See [`voice` usage](#use-voice-strings) for more details. --- **`languages[].auto_emotion`** `boolean` — default: false Lets the AI vary its emotion as it speaks. A global emotion, or specific emotions for certain topics, can be set within the prompt of the AI. > **Warning** > > Only works with the [Cartesia][cartesia] and [MiniMax][minimax] TTS engines. For a fixed MiniMax emotion, use [`params.emotion`](#paramsemotion) instead. --- **`languages[].auto_speed`** `boolean` — default: false Lets the AI vary its speaking speed during the conversation. The speed behavior can be defined in the prompt of the AI. > **Warning** > > Only works with the [Cartesia][cartesia], [ElevenLabs][elevenlabs], [MiniMax][minimax], [Rime][rime], [Inworld][inworld], [Smallest][smallest], and [Fish][fish] TTS engines. --- **`languages[].function_fillers`** `string[]` — default: None An array of strings to be used as fillers in the conversation when the agent is calling a [`SWAIG function`][swaig-functions]. The filler is played asynchronously during the function call. --- **`languages[].listen_language`** `string | string[]` A legacy alias for `code`, kept so that documents written before `code` existed keep working. It is read only when `code` is absent, so it has no effect alongside `code`. Write `code` in new documents. --- **`languages[].model`** `string` — default: None The model to use for the specified TTS engine (e.g. `coda`). Set this only if the `voice` string does not already carry a `:` suffix — a suffix on the `voice` string wins, and this key is then ignored without a warning. Check the [TTS provider reference][tts-providers] for the available models. --- **`languages[].speech_fillers`** `string[]` — default: None An array of strings to be used as fillers in the conversation. This helps the AI break silence between responses. > **Note** > > `speech_fillers` are used between every 'turn' taken by the LLM, including at the beginning of the call. For more targeted fillers, consider using `function_fillers`. --- **`languages[].turn_fillers`** `string[]` Short backchannels played while the caller still has the floor and the agent is deliberately waiting, as when they spell a name or read out a number, to signal it is still listening. Which waits earn one is set by [`params.turn_filler_sources`][turn-filler-sources]. > **Note** > > Unlike the language-keyed map on [`ai.multilingual`][multilingual], this is a plain array, because the entry already fixes the language. --- **`languages[].params`** `object` — default: None TTS engine-specific parameters for this language. --- **`params.similarity`** `number` — default: 0.75 The similarity slider dictates how closely the AI should adhere to the original voice when attempting to replicate it. The higher the similarity, the closer the AI will sound to the original voice. Valid values range from `0.0` to `1.0`. > **Info** > > Only works with the ElevenLabs TTS engine. --- **`params.stability`** `number` — default: 0.50 The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice. Valid values range from `0.0` to `1.0`. > **Info** > > Only works with the ElevenLabs TTS engine. --- **`params.speakingRate`** `number` — default: 1.0 Adjusts how quickly the voice speaks. Values below `1.0` slow the voice down; values above `1.0` speed it up. Valid values range from `0.5` to `1.5`. > **Info** > > Only works with the Inworld TTS engine. --- **`params.temperature`** `number` — default: 1.0 Controls the randomness and expressiveness of the generated speech. Lower values produce a more consistent, predictable delivery; higher values introduce more variation. Valid values range from `0.0` to `2.0`. > **Info** > > Only works with the Inworld TTS engine. --- **`params.speed`** `number` — default: 1.0 How quickly the voice speaks. Values below `1.0` slow the voice down; values above `1.0` speed it up. Valid values range from `0.5` to `2.0`. > **Info** > > Only works with the MiniMax TTS engine. --- **`params.vol`** `number` — default: 1.0 The speaking volume. Lower values are quieter. Valid values range from `0.1` to `1.0`. > **Info** > > Only works with the MiniMax TTS engine. --- **`params.pitch`** `integer` — default: 0 The pitch shift in semitones. Negative values lower the pitch; positive values raise it. Valid values range from `-12` to `12`. > **Info** > > Only works with the MiniMax TTS engine. --- **`params.emotion`** `string` A fixed emotional tone for the generated speech. Valid values are `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, and `neutral`. To vary the emotion automatically during a conversation, use [`languages[].auto_emotion`](#languagesauto_emotion) instead. > **Info** > > Only works with the MiniMax TTS engine. --- **`languages[].pronounce`** `object[]` Pronunciation replacements applied only while this language is active. Each entry takes the same `replace`, `with`, and `ignore_case` properties as [`ai.pronounce`][ai-pronounce], which applies to the whole call instead. --- **`languages[].fillers`** `string[]` — deprecated A deprecated spelling of `function_fillers`, and never used for speech fillers. An explicit `function_fillers` on the same entry takes precedence over it. **Deprecated**: Use `function_fillers` instead. --- **`languages[].engine`** `string` — deprecated The engine to use for the language. For example, `"elevenlabs"`. **Deprecated.** Set the engine with the [`voice`](#use-voice-strings) parameter. --- ## Use `voice` strings Compose the `voice` string using the `.` syntax, optionally followed by `:`. First, select your engine using the `gcloud`, `polly`, `amazon`, `azure`, `openai`, `elevenlabs`, `deepgram`, `cartesia`, `rime`, `inworld`, `minimax`, `groq-tts`, `mistral`, `grok`, `smallest`, `fish`, or `speechify` identifier. Append a period (`.`), and then the specific voice ID from the TTS provider, giving `gcloud.en-US-Casual-K`. Where an engine offers more than one model, append a colon (`:`) and the model ID, as in `elevenlabs.rachel:eleven_flash_v2_5`. Refer to SignalWire's [Supported Voices and Languages][tts-providers] for guides on configuring voice ID strings for each provider. > **Warning** > > Always include the engine. A voice ID on its own — `en-US-Casual-K` rather than `gcloud.en-US-Casual-K` — > is resolved against a default engine, and that default can change. A voice string that names its > engine keeps working regardless. ## **Supported voices and languages** SignalWire's cloud platform integrates with leading text-to-speech providers. For a comprehensive list of supported engines, languages, and voices, refer to our documentation on [Supported Voices and Languages][voices-and-languages]. ## **Examples** ### Set a single language This example uses `ai.languages` to configure a specific English-speaking voice from ElevenLabs. #### YAML ```yaml ai: languages: - name: English code: en-US voice: elevenlabs.rachel speech_fillers: - one moment please, - hmm... - let's see, ``` #### JSON ```json { "ai": { "languages": [ { "name": "English", "code": "en-US", "voice": "elevenlabs.rachel", "speech_fillers": [ "one moment please,", "hmm...", "let's see," ] } ] } } ``` ### Set multiple languages This example uses `ai.languages` to configure multiple languages using different TTS engines. The `code` comes from the ASR engine's list and the voice id from the TTS provider's, so the two do not have to use the same spelling of a language. #### YAML ```yaml ai: languages: - name: Mandarin code: zh-TW voice: gcloud.cmn-TW-Standard-A - name: English code: en-US voice: elevenlabs.rachel ``` #### JSON ```json { "ai": { "languages": [ { "name": "Mandarin", "code": "zh-TW", "voice": "gcloud.cmn-TW-Standard-A" }, { "name": "English", "code": "en-US", "voice": "elevenlabs.rachel" } ] } } ``` ### Configure per-language ElevenLabs parameters Configure different stability and similarity values for each language using `languages[].params`: #### YAML ```yaml ai: languages: - name: English code: en-US voice: elevenlabs.josh params: stability: 0.6 similarity: 0.8 - name: Spanish code: es voice: elevenlabs.maria params: stability: 0.4 similarity: 0.9 ``` #### JSON ```json { "ai": { "languages": [ { "name": "English", "code": "en-US", "voice": "elevenlabs.josh", "params": { "stability": 0.6, "similarity": 0.8 } }, { "name": "Spanish", "code": "es", "voice": "elevenlabs.maria", "params": { "stability": 0.4, "similarity": 0.9 } } ] } } ``` > Configure the spoken language of your AI Agent, as well as the TTS engine, voice, and fillers.