Speak text

POST

/calls/{call_control_id}/actions/speak

Call Commands

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 (see callback schema below):

call.speak.started

call.speak.ended

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/calls//actions/speak' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
    "language": "arb",
    "payload": "Say this on the call",
    "payload_type": "text",
    "service_level": "basic",
    "stop": "current",
    "voice": "female"
}'

Response Example

200 - Example 1

{
    "data": {
        "result": "ok"
    }
}

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

call_control_id

string

required

Unique identifier and token for controlling the call

Body Params application/json

client_state

string

optional

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example:

aGF2ZSBhIG5pY2UgZGF5ID1d

command_id

string

optional

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Example:

891510ac-f3e4-11e8-af5b-de00688a4901

language

enum<string>

optional

The language you want spoken. This parameter is ignored when a Polly.* voice is specified.

Allowed values:

arbcmn-CNcy-GBda-DKde-DEen-AUen-GBen-GB-WLSen-INen-USes-ESes-MXes-USfr-CAfr-FRhi-INis-ISit-ITja-JPko-KRnb-NOnl-NLpl-PLpt-BRpt-PTro-ROru-RUsv-SEtr-TR

Example:

en-US

payload

string

required

The text or SSML to be converted into speech. There is a 3,000 character limit.

Example:

Say this on the call

payload_type

enum<string>

optional

The type of the provided payload. The payload can either be plain text, or Speech Synthesis Markup Language (SSML).

Allowed values:

textssml

Default:

text

Example:

ssml

service_level

enum<string>

optional

This parameter impacts speech quality, language options and payload types. When using basic, only the en-US language and payload type text are allowed.

Allowed values:

basicpremium

Default:

premium

Example:

premium

stop

string

optional

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.

Example:

current

voice

string

required

Specifies the voice used in speech synthesis.

Define voices using the format <Provider>.<Model>.<VoiceId>. Specifying only the provider will give default values for voice_id and model_id.

Supported Providers:

AWS: Use AWS.Polly.<VoiceId> (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 for compatibility.
Azure: Use `Azure.. (e.g. Azure.en-CA-ClaraNeural, Azure.en-CA-LiamNeural, Azure.en-US-BrianMultilingualNeural, Azure.en-US-Ava:DragonHDLatestNeural. For a complete list of voices, go to Azure Voice Gallery.)
ElevenLabs: Use ElevenLabs.<ModelId>.<VoiceId> (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": "<secret_identifier>"}. See integration secrets documentation for details. Check available voices.
Telnyx: Use Telnyx.<model_id>.<voice_id>

For service_level basic, you may define the gender of the speaker (male or female).

Example:

Telnyx.KokoroTTS.af

voice_settings

optional

The settings associated with the voice selected

One of

ElevenLabs Voice Settings

api_key_ref

string

optional

The identifier for an integration secret /v2/integration_secrets that refers to your ElevenLabs API key. Warning: Free plans are unlikely to work with this integration.

Example:

my_elevenlabs_api_key

Examples

Responses

🟢200OK

application/json

Successful response upon making a call control command.

Body

data

object (Call Control Command Result)

optional

Example:

{"result":"ok"}

result

string

optional

Example:

🔴500Server Error

Modified at 2025-06-16 19:14:41

SIPREC stop

Streaming start