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

Request

Path Parameters

call_control_id stringrequired

Unique identifier and token for controlling the call

application/json

Body

required

Speak request

payload stringrequired

The text or SSML to be converted into speech. There is a 3,000 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 or the specific Amazon Polly voice to be used in the form of Polly.<voice>, e.g. Polly.Brian. All standard Amazon Polly voices are supported.

language string

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

Responses

200: Successful response upon making a call control command.

application/json

• Schema
• Example (from schema)

Schema

data

object

result string

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

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Callbacks

Loading...