Callr Actions: one way to play and prompt audio (tts / audioFile), with new action versions

Callr Actions used to reference audio in six different ways: what for say@v2, a numeric id for play@v1, a sid for play@v2 and gather@v3, a prompt: { what } object for gather, recognize and amd, a nested action for the ring of dial@v1, and a numeric playId for the waiting sound of bridge@v2, fetch@v2 and openai@v2.

Eight new action versions (plus say@v3, an alias of play@v3) use the same two parameters everywhere:

tts: { text, voice | language } plays a text-to-speech prompt (text is 1 to 1024 characters, voice and language are exclusive).
audioFile: { sid } plays an audio file of your library, by its SID (8 lowercase alphanumeric characters, quote it in YAML, see the Audio Files API).

When an action has one prompt, tts or audioFile sit directly under params. When it has several prompts, or a secondary one, they sit under the key of their role (conference.welcome, dial.ring, feedback). Set one of them, never both. Both are objects: tts: "hello" is refused, and so are tts and audioFile together.

# 1. play@v3 plays text-to-speech or an audio file (it replaces say@v2 and play@v2)
- action: play@v3
  params:
    tts:
      text: Bonjour, comment puis-je vous aider ?
      language: fr-FR
    stopOnTalk:
      enabled: true
    stopOnDTMF: true
  result: $played

- action: play@v3
  params:
    audioFile:
      sid: 'fdsanjkf'

# 2. gather@v4 and recognize@v3 prompt with either source
- action: gather@v4
  params:
    maxDigits: 4
    timeout: 30
    audioFile:
      sid: 'fdsanjkf'
  result: $digits

- action: recognize@v3
  params:
    tts:
      text: Are you looking for sales or support?
    hints: [sales, support]
  result: $intent

# 3. dial@v2: callerId replaces cli, ring is an audio file of your library
- action: dial@v2
  params:
    callerId: clone # clone | restricted | '+33199000000'
    ring:
      audioFile:
        sid: 'fdsanjkf'
    targets:
      - number: '+33199004242'
        timeout: 30
  result: $dial

# 4. fetch@v3 and openai@v3: feedback replaces audio
- action: fetch@v3
  params:
    url: https://api.example.com/json/
    feedback:
      enabled: true
      audioFile:
        sid: 'fdsanjkf'
  result: $response

say@v3 is an alias of play@v3: same parameters, same result. Prefer play@v3, which is the name used in the documentation, the templates and the examples.

New versions and what changes

Action	Replaces	What changes
`play@v3` (alias `say@v3`)	`say@v2`, `play@v2` (and `play@v1`)	`what` becomes `tts: { text }`, `sid` becomes `audioFile: { sid }`, and exactly one of them is required. The result is the `say@v2` result for both sources: `{ ok, stoppedOnTalk, stoppedOnDTMF, recognized, dtmf }`. `stopOnTalk` and `stopOnDTMF` work with both sources.
`gather@v4`	`gather@v3`	`prompt: { what, voice, language }` becomes `tts: { text, voice, language }`, `sid` becomes `audioFile: { sid }`. At most one of them: without any, the gather is silent.
`recognize@v3`	`recognize@v2`	`prompt: { what, voice, language }` becomes `tts: { text, voice, language }`. New: `audioFile: { sid }` as a prompt.
`amd@v3`	`amd@v2`	`prompt: { what, voice, language }` becomes `tts: { text, voice, language }`. New: `audioFile: { sid }` as a prompt.
`dial@v2` (and `dialOffline@v2`)	`dial@v1`	`cli` becomes `callerId`: `CLONE` becomes `clone` (default), `BLOCKED` becomes `restricted` (hidden caller ID, the REST API v2 word), and a phone number in E.164 format is still accepted. `ring: { action: play@v1, params: { id } }` becomes `ring: { audioFile: { sid } }`. The result is unchanged: `{ ok, status, callid, cdr, hangup }`.
`bridge@v3`	`bridge@v2` (and `bridge@v1`)	`audio: { playId }` becomes `feedback: { audioFile: { sid } }`. By default `feedback` is `{ enabled: true, sound: beep }`, as `bridge@v2`. `bridge@v1` plays no sound: to keep a silent bridge with `bridge@v3`, set `feedback: { enabled: false }`.
`fetch@v3`	`fetch@v2`	`audio: { playId }` becomes `feedback: { audioFile: { sid } }`. By default `feedback` is `{ enabled: false, sound: heartbeat }`.
`openai@v3`	`openai@v2`	`audio: { playId }` becomes `feedback: { audioFile: { sid } }`. By default `feedback` is `{ enabled: false, sound: heartbeat }`.

feedback is { enabled, delay, sound | audioFile }: delay is 0 to 60 seconds, sound is beep, loading or heartbeat. Set at most one of sound and audioFile. The delay of bridge@v3 is accepted and has no effect.
The audio of [email protected] and feedback is played by the telephony platform: audioFile or sound only, no tts.
conference@v1 uses the same parameters (tts, audioFile), see the conference@v1 entry.
In the Console, the SID shown next to each audio file is the one to use with audioFile: { sid }.

Fixes in dial@v1 and dial@v2

The API no longer checks the caller ID against the approved caller IDs, only that it is a well formed number in E.164 format. It used to be checked against the system account, not yours. The call platform applies the caller ID rules when the call is placed.
An explicit cli: CLONE is accepted (it used to end the scenario with an error).
The ring of a previous dial is no longer replayed by the next dial that has no ring.

Old versions remain valid. say@v2, play@v1, play@v2, gather@v3, recognize@v2, amd@v2, dial@v1, bridge@v1, bridge@v2, fetch@v2 and openai@v2 keep working exactly as before and are not deprecated. The templates of the Console and the examples of the documentation use the new versions.

See the Callr Actions reference.