recognize@v3

Recognize voice - Speech-to-Text.


Version	`recognize@v3`
Runs in	`inbound-call` and your own branches

Parameters

Name	Type	Default	Description
`language`	`af-ZA`, `am-ET`, `ar-AE`… (140 values)		Speech-to-text language (the prompt language is tts.language or tts.voice). See Voices & Audio accepts `${{ }}`
`timeout`	number	`10`	1..60 · accepts `${{ }}`
`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`
`hints`	array of string		1..10 items
`stopOnDTMF`	boolean	`false`	accepts `${{ }}`

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

Examples

Same as recognize@v2, with the same prompt parameters as play@v3

tts (text-to-speech) or audioFile (audio file of your library). Set at most one of them: without any, the action only listens. The prompt is interrupted by the first final recognition result, or by a key press with stopOnDTMF. The timeout covers the prompt and the listening: use a timeout longer than your audio file.

- label: ask
  action: recognize@v3
  params:
    tts:
      text: Are you looking for a house, a car or a parking lot?
    hints:
      - A house
      - A car
      - A parking lot
  result: $type

With an audio file of your library (SID: REST API v2 identifier, see https://docs.callr.com/reference/audiofilesget)

- action: recognize@v3
  params:
    audioFile:
      sid: 'fdsanjkf'
    hints: [support, commercial]
    language: fr-FR
  result: $department

Full example with defaults

- action: recognize@v3
  params:
    tts: # or audioFile: { sid: 'fdsanjkf' }, or none
      text: How can I help you? # (1..1024 characters)
      # voice: en-US-AvaMultilingual # or language: en-US (default: the language below)
    # language: en-US # stt language (default: the scenario defaults)
    timeout: 10
    stopOnDTMF: false
    hints: [support, sales] # helps the recognition (none by default)

Using the result

- if: '!$type.ok'
  then:
    - action: play@v3
      params:
        tts:
          text: Sorry, I did not get that
    - goto:
        label: ask

- action: play@v3
  params:
    tts:
      text: You said ${{ $type.lexical }}!

Result

Set result: $myVariable to keep it. Result of recognize@v2 and recognize@v3 (speech-to-text)

Field	Type	Description
`ok`	boolean	`true` when speech was recognized (or when a key stopped the recognition)
`timeout`	boolean	`true` when nothing was recognized in time
`error`	string	Only present on error: `hangup` when the caller hung up, `canceled`, or the error message
`text`	string	Recognized text, formatted with punctuation
`lexical`	string	Recognized text, as words (no punctuation, numbers spelled out)
`itn`	string	Inverse Text Normalization (ITN), numbers as digits
`maskedITN`	string	ITN with profanity masked
`confidence`	number	Confidence of the recognition (0 to 1)
`offset`	number	Start of the recognized speech, in seconds
`duration`	number	Duration of the recognized speech, in seconds
`words`	array or null	Recognized words, `null` when nothing was recognized
`stoppedOnDTMF`	boolean	`true` when a key pressed by the caller stopped the recognition (`stopOnDTMF`)
`dtmf`	string	Key pressed when `stoppedOnDTMF` is `true`, empty otherwise

{
  "ok": true,
  "timeout": false,
  "text": "A house.",
  "lexical": "a house",
  "itn": "a house",
  "maskedITN": "a house",
  "confidence": 0.9,
  "offset": 2.08,
  "duration": 0.6,
  "words": [
    {
      "word": "a",
      "offset": 2.08,
      "duration": 0.2,
      "confidence": 0.88
    },
    {
      "word": "house",
      "offset": 2.4,
      "duration": 0.4,
      "confidence": 0.92
    }
  ],
  "stoppedOnDTMF": false,
  "dtmf": ""
}

Older versions

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

recognize@v2: Recognize voice - Speech-to-Text
recognize@v1: Use recognize@v2 instead recognize@v1 is deprecated, use recognize@v3