play@v3

Play a text-to-speech prompt (tts) or an audio file of your library (audioFile). Replaces say@v2 and play@v2.


Version	`play@v3`
Runs in	`inbound-call` and your own branches
Alias	`say@v3` is the same action, with the same parameters

Parameters

Name	Type	Required	Default	Description
`tts`	object			Text-to-speech prompt: text (1 to 1024 characters), with an optional voice or language (exclusive). Without them, the defaults of the branch or of the scenario apply. text-to-speech prompt: `text`, and `voice` or `language`
`audioFile`	object			An audio file of your library, by its SID (REST API v2 identifier). audio file of your library: `sid`
`stopOnTalk`	object			Stop the playback when the caller talks (speech-to-text, billed)
`stopOnTalk.enabled`	boolean	yes	`false`	accepts `${{ }}`
`stopOnTalk.minWords`	integer		`3`	1..10 · accepts `${{ }}`
`stopOnDTMF`	boolean		`false`	accepts `${{ }}`

Every parameter that accepts ${{ }} can be computed from an expression.

How it works

play@v3 replaces say@v2 (text-to-speech) and play@v2 (audio file): one action, two sources. Set exactly one of tts / audioFile.

say@v3 is an alias of play@v3 (same parameters, same result); prefer play@v3.

Examples

Text-to-speech

- action: play@v3
  params:
    tts:
      text: Hello world!

Language is auto-detected based on the caller number

You can force a language, or a specific voice (exclusive):

- action: play@v3
  params:
    tts:
      text: Bonjour le monde!
      language: fr-FR

Audio file of your library, by its SID (8 lowercase alphanumeric characters, shown in Media > Audio Files and returned by the REST API v2, see: https://docs.callr.com/reference/audiofilesget)

- action: play@v3
  params:
    audioFile:
      sid: 'fdsanjkf' # quote it: an all-digit SID would be read as a number

stopOnTalk stops the playback when the caller says at least <minWords> words (speech detection, billed like say@v2); stopOnDTMF stops it on a key press.

- action: play@v3
  params:
    tts:
      text: Hello! Are you saying something when I talk to you?
    stopOnTalk:
      enabled: true
    stopOnDTMF: true
  result: $played

Full example with defaults

- action: play@v3
  params:
    tts: # or audioFile: { sid: 'fdsanjkf' }
      text: Hello! Are you saying something while I am talking to you?
      # voice: en-US-AvaMultilingual # or language: en-US (not both)
    stopOnTalk:
      enabled: false
      minWords: 3 # (1..10)
    stopOnDTMF: false
  result: $played

Result

Set result: $myVariable to keep it. Result of say@v2, say@v3 and play@v3

Field	Type	Description
`ok`	boolean	`true` when the prompt was played, to the end or until interrupted
`timeout`	boolean	`true` when the prompt did not finish in time
`error`	string	Only present on error: `hangup` when the caller hung up, `canceled`, or the error message
`stoppedOnTalk`	boolean	`true` when the caller's speech stopped the prompt (`stopOnTalk`)
`recognized`	string	Text said by the caller when `stoppedOnTalk` is `true`, empty otherwise
`stoppedOnDTMF`	boolean	`true` when a key pressed by the caller stopped the prompt (`stopOnDTMF`)
`dtmf`	string	Key pressed (`0`-`9`, `*`, `#`) when `stoppedOnDTMF` is `true`, empty otherwise

{
  "ok": true,
  "timeout": false,
  "stoppedOnTalk": false,
  "recognized": "",
  "stoppedOnDTMF": true,
  "dtmf": "1"
}

Older versions

Older versions keep working in existing scenarios. Use the version above in new scenarios.

play@v2: Play an audio file (API v2 audio file SID)
play@v1: Play uploaded media file
say@v2: Say something with Text-to-Speech
say@v1: Use say@v2 instead say@v1 is deprecated, use say@v3