--- title: "Speak text" method: POST path: "/calls/{call_control_id}/actions/speak" tags: ["Call Commands"] --- # Speak text `POST /calls/{call_control_id}/actions/speak` Convert text to speech and play it back on the call. If multiple speak text commands are issued consecutively, the audio files will be placed in a queue awaiting playback. **Expected Webhooks:** - `call.speak.started` - `call.speak.ended` ## Path parameters - `call_control_id` string, required ## Request body - SpeakRequest - `payload` string, required — The text or SSML to be converted into speech. There is a 3,000 character limit. - `payload_type` 'text' | 'ssml' — The type of the provided payload. The payload can either be plain text, or Speech Synthesis Markup Language (SSML). - `service_level` 'basic' | 'premium' — This parameter impacts speech quality, language options and payload types. When using `basic`, only the `en-US` language and payload type `text` are allowed. - `stop` string — When specified, it stops the current audio being played. Specify `current` to stop the current audio being played, and to play the next file in the queue. Specify `all` to stop the current audio file being played and to also clear all audio files from the queue. - `voice` string, required — Specifies the voice used in speech synthesis. - Define voices using the format `..`. Specifying only the provider will give default values for voice_id and model_id. **Supported Providers:** - **AWS:** Use `AWS.Polly.` (e.g., `AWS.Polly.Joanna`). For neural voices, which provide more realistic, human-like speech, append `-Neural` to the `VoiceId` (e.g., `AWS.Polly.Joanna-Neural`). Check the [available voices](https://docs.aws.amazon.com/polly/latest/dg/available-voices.html) for compatibility. - **Azure:** Use `Azure.` (e.g., `Azure.en-CA-ClaraNeural`, `Azure.en-US-BrianMultilingualNeural`, `Azure.en-US-Ava:DragonHDLatestNeural`). For a complete list of voices, go to [Azure Voice Gallery](https://speech.microsoft.com/portal/voicegallery). Use `voice_settings` to configure custom deployments, regions, or API keys. - **ElevenLabs:** Use `ElevenLabs..` (e.g., `ElevenLabs.eleven_multilingual_v2.21m00Tcm4TlvDq8ikWAM`). The `ModelId` part is optional. To use ElevenLabs, you must provide your ElevenLabs API key as an integration identifier secret in `"voice_settings": {"api_key_ref": ""}`. See [integration secrets documentation](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) for details. Check [available voices](https://elevenlabs.io/docs/api-reference/get-voices). - **Telnyx:** Use `Telnyx..` (e.g., `Telnyx.KokoroTTS.af`). Use `voice_settings` to configure voice_speed and other synthesis parameters. - **Minimax:** Use `Minimax..` (e.g., `Minimax.speech-02-hd.Wise_Woman`). Supported models: `speech-02-turbo`, `speech-02-hd`, `speech-2.6-turbo`, `speech-2.8-turbo`. Use `voice_settings` to configure speed, volume, pitch, and language_boost. - **Rime:** Use `Rime..` (e.g., `Rime.Arcana.cove`). Supported model_ids: `Arcana`, `Mist`, `ArcanaV3`, `Coda`. Use `voice_settings` to configure voice_speed. - **Resemble:** Use `Resemble.Turbo.` (e.g., `Resemble.Turbo.my_voice`). Only `Turbo` model is supported. Use `voice_settings` to configure precision, sample_rate, and format. - **Inworld:** Use `Inworld..` (e.g., `Inworld.Mini.Loretta`, `Inworld.Max.Oliver`, `Inworld.TTS2.Loretta`). Supported models: `Mini`, `Max`, `TTS2`. Use `voice_settings` to configure `delivery_mode` (`STABLE`, `BALANCED`, `CREATIVE`), supported by `TTS2` only. - **xAI:** Use `xAI.` (e.g., `xAI.eve`). Available voices: `eve`, `ara`, `rex`, `sal`, `leo`. For service_level basic, you may define the gender of the speaker (male or female). - `voice_settings` union — The settings associated with the voice selected - ElevenLabsVoiceSettings - `type` 'elevenlabs', required — Voice settings provider type - `api_key_ref` string — The `identifier` for an integration secret [/v2/integration_secrets](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) that refers to your ElevenLabs API key. Warning: Free plans are unlikely to work with this integration. - TelnyxVoiceSettings - `type` 'telnyx', required — Voice settings provider type - `voice_speed` number, float — The voice speed to be used for the voice. The voice speed must be between 0.1 and 2.0. Default value is 1.0. - AWSVoiceSettings - `type` 'aws', required — Voice settings provider type - MinimaxVoiceSettings - `type` 'minimax', required — Voice settings provider type - `speed` number, float — Speech speed multiplier. Default is 1.0. - `vol` number, float — Speech volume multiplier. Default is 1.0. - `pitch` integer — Voice pitch adjustment. Default is 0. - `language_boost` 'null' | 'auto' | 'Chinese' | 'Chinese,Yue' | 'English' | 'Arabic' | 'Russian' | 'Spanish' | 'French' | 'Portuguese' | 'German' | 'Turkish' | 'Dutch' | 'Ukrainian' | 'Vietnamese' | 'Indonesian' | 'Japanese' | 'Italian' | 'Korean' | 'Thai' | 'Polish' | 'Romanian' | 'Greek' | 'Czech' | 'Finnish' | 'Hindi' | 'Bulgarian' | 'Danish' | 'Hebrew' | 'Malay' | 'Persian' | 'Slovak' | 'Swedish' | 'Croatian' | 'Filipino' | 'Hungarian' | 'Norwegian' | 'Slovenian' | 'Catalan' | 'Nynorsk' | 'Tamil' | 'Afrikaans', nullable — Enhances recognition for specific languages and dialects during MiniMax TTS synthesis. Default is null (no boost). Set to 'auto' for automatic language detection. - AzureVoiceSettings - `type` 'azure', required — Voice settings provider type - `api_key_ref` string — The `identifier` for an integration secret that refers to your Azure Speech API key. - `region` string — The Azure region for the Speech service (e.g., `eastus`, `westeurope`). Required when using a custom API key. - `deployment_id` string — The deployment ID for a custom Azure neural voice. - `effect` 'eq_car' | 'eq_telecomhp8k' — Audio effect to apply. - `gender` 'Male' | 'Female' — Voice gender filter. - RimeVoiceSettings - `type` 'rime', required — Voice settings provider type - `voice_speed` number, float — Speech speed multiplier. Default is 1.0. - ResembleVoiceSettings - `type` 'resemble', required — Voice settings provider type - `precision` 'PCM_16' | 'PCM_24' | 'PCM_32' | 'MULAW' — Audio precision format. - `sample_rate` '8000' | '16000' | '22050' | '32000' | '44100' | '48000' — Audio sample rate in Hz. - `format` 'wav' | 'mp3' — Output audio format. - InworldVoiceSettings - `type` 'inworld', required — Voice settings provider type - `delivery_mode` 'STABLE' | 'BALANCED' | 'CREATIVE' — Controls the expressiveness and consistency of the Inworld `TTS2` model's speech synthesis. `STABLE` favors consistent, predictable output, `CREATIVE` allows more expressive variation, and `BALANCED` sits in between. Optional and only supported by `TTS2`; when omitted, the provider default applies. - XAIVoiceSettings - `type` 'xai', required — Voice settings provider type - `language` string — Language code, or `auto` to detect automatically. - `language` 'arb' | 'cmn-CN' | 'cy-GB' | 'da-DK' | 'de-DE' | 'en-AU' | 'en-GB' | 'en-GB-WLS' | 'en-IN' | 'en-US' | 'es-ES' | 'es-MX' | 'es-US' | 'fr-CA' | 'fr-FR' | 'hi-IN' | 'is-IS' | 'it-IT' | 'ja-JP' | 'ko-KR' | 'nb-NO' | 'nl-NL' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sv-SE' | 'tr-TR' — The language you want spoken. This parameter is ignored when a `Polly.*` voice is specified. - `client_state` string — Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string. - `command_id` string — Use this field to avoid duplicate commands. Telnyx will ignore any command with the same `command_id` for the same `call_control_id`. - `loop` union - string - integer - `target_legs` 'self' | 'opposite' | 'both' — Specifies which legs of the call should receive the spoken audio. ## Response `200` Successful response upon making a call control command. - object - `data` CallControlCommandResult - `result` string ## Other responses - `422` — Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values, call state errors, conference errors, queue errors, recording/transcription errors, and business logic violations. - `default` — Unexpected error --- [API](https://skmtc.net/team-telnyx/apis/telnyx-api.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api/versions/e32d46c5945b/schema)