Skip to main content

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:

  • Speak started
  • Speak ended

Request ​

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

    payload stringrequired

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

    payload_type string

    Possible values: [text, ssml]

    Default value: text

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

    service_level string

    Possible values: [basic, premium]

    Default value: 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 stringrequired

    Possible values: [male, female]

    The gender of the voice used to speak back the text.

    language stringrequired

    Possible values: [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.

    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 commands with the same "command_id".

Responses ​

200: Successful response

Schema

    result stringrequired

422: Error response

Schema

    code stringrequired
    title stringrequired
    detail stringrequired

Request samples

curl -L 'https://api.telnyx.com/calls/:call_control_id/actions/speak' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "payload": "Say this on the call",
  "payload_type": "ssml",
  "service_level": "premium",
  "stop": "current",
  "voice": "female",
  "language": "en-US",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}'

Response samples

{
  "result": "ok"
}