Say

Sends text-to-speech (TTS) to an active call. You can send plain text, and on supported platforms provide advanced options such as voice name, loop count, queueing, level, and SSML usage.

Signature

// Callback versions
fun say(
  callId: String,
  text: String,
  callback: (Exception?) -> Unit
)

fun say(
  callId: String,
  text: String,
  level: Int,
  loop: Int,
  queue: Boolean,
  voiceName: String,
  ssml: Boolean,
  callback: (Exception?) -> Unit
)

// Suspend versions
suspend fun say(
  callId: String,
  text: String
)

suspend fun say(
  callId: String,
  text: String,
  level: Int,
  loop: Int,
  queue: Boolean,
  voiceName: String,
  ssml: Boolean
)

Parameters

Parameter	Type	Required	Description
callId	string	Yes	Identifier of the active call
text	string	Yes	Plain text or SSML payload to synthesize
params	CallSayParams	No	Optional advanced TTS options (Web overload)

CallSayParams

On Web, the overloaded say(callId, params) form accepts a CallSayParams object. Android and iOS expose these as individual parameters on the say method.

Option	Type	Required	Description
text	string	Yes	Plain text or SSML payload (max 1500 characters)
level	number	No	Audio level for playback (range: -1 to 1, default: 0)
loop	integer	No	Number of times to repeat (must be a whole number >= 0; 0 = play once)
queue	boolean	No	Whether to queue with other media operations (default: true)
voiceName	string	No	Voice preset name (e.g. "Amy", "Brian", "Kimberly")
ssml	boolean	No	Indicates whether text is SSML (default: false)

Return Type

Returns void (or Promise<void> for Web).

Usage Example

 // Callback
 client.say("callId", "hello World") {
     it?.let { err ->
         // Handle Error sending Say
         println("Error sending Say: $err")
     }
 }

 // Coroutine
 try {
     client.say("callId", "hello")
 } catch (e: Error) {
     // Handle Error in sending DTMF
 }

Errors

Error Type	Error Code	Description
INTERNAL_ERROR	voice:error:no_call_found	No active call found for provided callId
INTERNAL_ERROR	Media/validation errors	Invalid TTS payload or media-layer failure
NETWORK_ERROR	internal:error:serviceNotAvailable	Service/network issue during TTS request
UNKNOWN_ERROR	N/A	Unexpected failure

For complete error reference and handling guidelines, see Error Reference.

Notes

• text must not exceed 1500 characters (SSML markup counts toward the limit)
• Use SSML for richer speech output where supported (pauses, emphasis, pronunciation)
• loop: 0 plays the message once (the default); loop: 3 plays it 3 additional times (4 total)
• When queue is false, the TTS interrupts any currently playing audio
• If voiceName is omitted, the platform default voice is used
• Defaults are applied by platform when advanced options are omitted

Related Actions

• sendDTMF - Send DTMF digits to an active call