Prompt

Play a prompt and wait for input. The input can be received either as digits from the keypad, or from speech, or both depending on what properties are set.

Properties

objectRequired

An object that accepts the following properties.

prompt.play

string | string[]Required

Either a playable sound or an array of playable sounds

prompt.volume

numberDefaults to 0

Volume gain to apply to played URLs. Allowed values from -40.0 to 40.0.

prompt.say_voice

stringDefaults to Polly.Salli

Voice to use with say: for text to speech

prompt.say_language

stringDefaults to en-US

Language to use with say: for text to speech

prompt.say_gender

stringDefaults to female

Gender to use with say: for text to speech

prompt.max_digits

integerDefaults to 1

Number of digits to collect

prompt.terminators

string

Digits that terminate digit collection

prompt.digit_timeout

numberDefaults to 5.0 seconds

Time in seconds to wait for next digit

prompt.initial_timeout

numberDefaults to 5.0 seconds

Time in seconds to wait for start of input

prompt.speech_timeout

number

Max time in seconds to wait for speech result

prompt.speech_end_timeout

number

Time in seconds to wait for end of speech utterance

prompt.speech_language

string

Language to detect speech in

prompt.speech_hints

string[]

Expected words to match

prompt.speech_engine

string

The engine selected for speech recognition. The engine must support the specified language. Valid values: Google, Google.V2, Deepgram. Default is not set (SignalWire picks the engine).

prompt.status_url

string

HTTP or HTTPS URL to deliver prompt status events. Learn more about status callbacks.

By default, only digit input via keypad is enabled. When at least one speech input based parameter is set (speech_timeout, speech_end_timeout, speech_language or speech_hints), speech input is enabled and digit input is disabled.

To enable speech and digit based input collection at once, set at least one speech input parameter and at least one digit input based parameter (max_digits, terminators, digit_timeout, and initial_timeout).

Playable sounds

Audio file from a URL

To play an audio file from the web, simply list that audio’s URL. Specified audio file should be accessible with an HTTP GET request. HTTP and HTTPS URLs are supported. Authentication can also be set in the url in the format of username:password@url.

Example: https://cdn.signalwire.com/swml/audio.mp3

Ring

To play the standard ringtone of a certain country, use ring:[duration:]<country code>.

The total duration can be specified in seconds as an optional second parameter. When left unspecified, it will ring just once. The country code must be specified. It has values like us for United States, it for Italy. For the list of available country codes, refer to the supported ringtones section below. For example:

ring:us - ring with the US ringtone once ring:3.2:uk - ring with the UK ringtone for 3.2 seconds

Speak using a TTS

To speak using a TTS, use say:<text to speak>. When using say, you can optionally set say_voice, say_language and say_gender in the play or prompt properties. For the list of useable voices and languages, refer to the supported voices and languages section below.

Silence

To be silent for a certain duration, use silence:<duration>. The duration is in seconds.

Variables

Read by the method:

say_voice: (in) - optional voice to use for text to speech.
say_language: (in) - optional language to use for text to speech.
say_gender: (in) - optional gender to use for text to speech.

Possible values for voice, language, and ringtone

Supported voices and languages

To learn more about the supported voices and languages, please visit the Supported Voices and Languages Documentation.

Supported ring tones

Parameter
`urls.ring`	Available values are the following ISO 3166-1 alpha-2 country codes: at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, us-old, tw, ve, za.

Set by the method

prompt_result: (out) - failed, no_input, match_speech, match_digits, or no_match.
prompt_value: (out) - the digits or utterance collected.
prompt_digit_terminator: (out) - digit terminator collected, if any.
prompt_speech_confidence: (out) - speech confidence measured, if any.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.collect for this method.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing prompt-specific parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.control_id

string

The control ID for this prompt operation.

params.result

object

The collection result details.

result.type

string

The type of input collected. Valid values:digit, speech, no_input, no_match, start_of_input, finished, error.

result.params.digits

string

The DTMF digits collected (when type is digit).

result.params.terminator

string

The terminator digit that ended collection (when type is digit).

result.params.text

string

The recognized speech text (when type is speech).

result.params.confidence

number

The speech recognition confidence score (when type is speech).

params.final

boolean

Whether this is the final result in a continuous collect session. Only present when partial_results is enabled. true indicates collection has ended; false indicates more results may follow.

params.state

string

The current collection state. Only present when continuous collect is enabled. Valid values:collecting, finished, error.

Raw JSON example

Digit input:

{
  "event_type": "calling.call.collect",
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": 1640000000.123,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "result": {
      "type": "digit",
      "params": {
        "digits": "1234",
        "terminator": "#"
      }
    }
  }
}

Speech input:

{
  "event_type": "calling.call.collect",
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": 1640000000.123,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "result": {
      "type": "speech",
      "params": {
        "text": "one",
        "confidence": 0.95
      }
    }
  }
}

Examples

The play method also has examples related to playing sounds from URLs. The interface for playing sounds for play and prompt is identical.

Play prompt and wait for digit press

YAMLJSON

version: 1.0.0
sections:
  main:
    - prompt:
        play: 'say:Input a number'
    - switch:
        variable: prompt_value
        default:
          - play:
              url: 'say:You didn''t press one'
          - transfer:
              dest: main
        case:
          '1':
            - play:
                url: 'say:You pressed one'

Using terminators

YAMLJSON

version: 1.0.0
sections:
  main:
    - prompt:
        play: 'say:PIN number please'
        max_digits: 10
        terminators: '*#5'
    - play:
        url: 'say: ${prompt_value} was terminated by ${prompt_digit_terminator}'

Play prompt and wait for digit or speech

YAMLJSON

version: 1.0.0
sections:
  main:
    - prompt:
        play: 'https://example.com/press_or_say_one.wav'
        speech_language: en-US
        max_digits: 1
        speech_hints:
          - one
          - two
          - three
          - four
          - five
          - six
          - seven
          - eight
          - nine
    - switch:
        variable: prompt_value
        default:
          - play:
              url: 'https://example.com/bad_input.wav'
          - transfer:
              dest: main
        case:
          '1':
            - transfer:
                dest: 'https://example.com/sales.swml'
          one:
            - transfer:
                dest: 'https://example.com/sales.swml'

Play prompt and collect digits, then pass the data to an external action

YAMLJSON

version: 1.0.0
sections:
  main:
    - prompt:
        play: 'https://example.com/menu.wav'
    - transfer:
        dest: 'https://example.com/post_next_menu'

In this case, the URL listed in transfer will be sent an HTTP POST request with all the out variables (like prompt_value) already set. For more details on this behavior, refer to transfer statement’s documentation.

Properties ​

prompt ​

prompt.play ​

prompt.volume ​

prompt.say_voice ​

prompt.say_language ​

prompt.say_gender ​

prompt.max_digits ​

prompt.terminators ​

prompt.digit_timeout ​

prompt.initial_timeout ​

prompt.speech_timeout ​

prompt.speech_end_timeout ​

prompt.speech_language ​

prompt.speech_hints ​

prompt.speech_engine ​

prompt.status_url ​

Playable sounds ​

Variables ​

Possible values for voice, language, and ringtone ​

Supported voices and languages ​

Supported ring tones ​

Set by the method ​

StatusCallbacks ​

event_type ​

event_channel ​

timestamp ​

project_id ​

space_id ​

params ​

params.call_id ​

params.node_id ​

params.control_id ​

params.result ​

result.type ​

result.params.digits ​

result.params.terminator ​

result.params.text ​

result.params.confidence ​

params.final ​

params.state ​

Raw JSON example ​

Examples ​

Play prompt and wait for digit press ​

Using terminators ​

Play prompt and wait for digit or speech ​

Play prompt and collect digits, then pass the data to an external action ​

Properties

prompt

prompt.play

prompt.volume

prompt.say_voice

prompt.say_language

prompt.say_gender

prompt.max_digits

prompt.terminators

prompt.digit_timeout

prompt.initial_timeout

prompt.speech_timeout

prompt.speech_end_timeout

prompt.speech_language

prompt.speech_hints

prompt.speech_engine

prompt.status_url

Playable sounds

Variables

Possible values for voice, language, and ringtone

Supported voices and languages

Supported ring tones

Set by the method

StatusCallbacks

event_type

event_channel

timestamp

project_id

space_id

params

params.call_id

params.node_id

params.control_id

params.result

result.type

result.params.digits

result.params.terminator

result.params.text

result.params.confidence

params.final

params.state

Raw JSON example

Examples

Play prompt and wait for digit press

Using terminators

Play prompt and wait for digit or speech

Play prompt and collect digits, then pass the data to an external action