Speak text

POST

calls

{call_control_id}

actions

speak

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.speak('call_control_id', {
  payload: 'Say this on the call',
  voice: 'female',
});

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.calls.actions.speak(
    call_control_id="call_control_id",
    payload="Say this on the call",
    voice="female",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Calls.Actions.Speak(
		context.TODO(),
		"call_control_id",
		telnyx.CallActionSpeakParams{
			Payload: "Say this on the call",
			Voice:   "female",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.actions.ActionSpeakParams;
import com.telnyx.sdk.models.calls.actions.ActionSpeakResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ActionSpeakParams params = ActionSpeakParams.builder()
            .callControlId("call_control_id")
            .payload("Say this on the call")
            .voice("female")
            .build();
        ActionSpeakResponse response = client.calls().actions().speak(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->calls->actions->speak(
    'call_control_id',
    payload: 'Say this on the call',
    voice: 'female',
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    commandID: '891510ac-f3e4-11e8-af5b-de00688a4901',
    language: 'arb',
    loop: 'string',
    payloadType: 'text',
    serviceLevel: 'basic',
    stop: 'current',
    targetLegs: 'both',
    voiceSettings: [
      'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
    ],
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payload": "Say this on the call",
  "payload_type": "text",
  "service_level": "basic",
  "stop": "current",
  "voice": "female",
  "language": "arb",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
'

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

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

call_control_id

string

required

Unique identifier and token for controlling the call

Body

application/json

Speak request

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"

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.<VoiceId> (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. Use voice_settings to configure custom deployments, regions, or API keys.
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> (e.g., Telnyx.KokoroTTS.af). Use voice_settings to configure voice_speed and other synthesis parameters. Bayan provides Arabic (multiple dialects) and English voices (e.g., Telnyx.Bayan.Ahmed, Telnyx.Bayan.Amanda). Sukhan provides Urdu voices (e.g., Telnyx.Sukhan.urdu-professor); voice_speed is not supported.
Minimax: Use Minimax.<ModelId>.<VoiceId> (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.
Resemble: Use Resemble.<ModelId>.<VoiceId> (e.g., Resemble.Turbo.Aaron_en-US). Supported models: Pro, Turbo, Urdu. <VoiceId> is a stock voice name or the ID of a Resemble voice clone. Use voice_settings to configure precision, sample_rate, and format.
Inworld: Use Inworld.<ModelId>.<VoiceId> (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.
Fish Audio: Use FishAudio.<ModelId>.<VoiceId> (e.g., FishAudio.s2.1-pro.<reference_id>). Supported models: s2.1-pro, s2-pro, s1. VoiceId is a Fish Voice-Library reference ID.
Soniox: Use Soniox.<ModelId>.<VoiceId> (e.g., Soniox.tts-rt-v2.Emma). Supported model: tts-rt-v2. Browse the catalog via the Voices API. Every voice speaks all supported languages; set language to the two-letter ISO 639-1 code of the text, for example it. SSML is not supported. Use voice_settings to configure speed (0.7 to 1.3) and reduce_silence.
xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
Humain: Use Humain.<VoiceId> (e.g., Humain.sara-ar). Available voices: sara-en, abdulaziz-en, sara-ar, abdulaziz-ar, nourah-ar, abdullah-ar. Native Arabic (Saudi dialect) and English voices only — no ModelId segment.

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

Example:

"Telnyx.KokoroTTS.af"

payload_type

enum<string>

default:text

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

Available options:

text,

ssml

Example:

"ssml"

service_level

enum<string>

default: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.

Available options:

basic,

premium

Example:

"premium"

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.

Example:

"current"

voice_settings

ElevenLabs Voice Settings · object

The settings associated with the voice selected

Show child attributes

language

enum<string>

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

Available options:

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

Example:

"en-US"

client_state

string

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

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

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.

Example:

"891510ac-f3e4-11e8-af5b-de00688a4901"

loop

The number of times to play the audio file. Use infinity to loop indefinitely. Defaults to 1.

target_legs

enum<string>

default:self

Specifies which legs of the call should receive the spoken audio.

Available options:

self,

opposite,

both

Example:

"both"

Response

Successful response upon making a call control command.

data

Call Control Command Result · object

Show child attributes

Example:

{ "result": "ok" }

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.speak('call_control_id', {
  payload: 'Say this on the call',
  voice: 'female',
});

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.calls.actions.speak(
    call_control_id="call_control_id",
    payload="Say this on the call",
    voice="female",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Calls.Actions.Speak(
		context.TODO(),
		"call_control_id",
		telnyx.CallActionSpeakParams{
			Payload: "Say this on the call",
			Voice:   "female",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.calls.actions.ActionSpeakParams;
import com.telnyx.sdk.models.calls.actions.ActionSpeakResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ActionSpeakParams params = ActionSpeakParams.builder()
            .callControlId("call_control_id")
            .payload("Say this on the call")
            .voice("female")
            .build();
        ActionSpeakResponse response = client.calls().actions().speak(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->calls->actions->speak(
    'call_control_id',
    payload: 'Say this on the call',
    voice: 'female',
    clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d',
    commandID: '891510ac-f3e4-11e8-af5b-de00688a4901',
    language: 'arb',
    loop: 'string',
    payloadType: 'text',
    serviceLevel: 'basic',
    stop: 'current',
    targetLegs: 'both',
    voiceSettings: [
      'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key'
    ],
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payload": "Say this on the call",
  "payload_type": "text",
  "service_level": "basic",
  "stop": "current",
  "voice": "female",
  "language": "arb",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
'

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

Voice API Fundamentals

Voice Features

AI Capabilities

Tutorials

Regional & Restrictions

API Reference

For AI Agents

Authorizations

Path Parameters

Body

Response