Skip to main content
POST
/
calls
/
{call_control_id}
/
actions
/
speak
JavaScript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: 'My API Key',
});

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

console.log(response.data);
{
  "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-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"

​
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

  • ElevenLabs Voice Settings
  • Telnyx Voice Settings
  • AWS Voice Settings
​
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"

Response

Successful response upon making a call control command.

​
data
Call Control Command Result · object
Example:
{ "result": "ok" }