Skip to main content
Get startedGuidesTechnical Reference

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 prompt parameters are set.

prompt
objectrequired

An object that accepts the prompt parameters.

prompt Parameters​

prompt.play
string | string[]required

Either a playable sound or an array of playable sounds

prompt.volume
number
Default: 0

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

prompt.say_voice
string
Default: Polly.Salli

Voice to use with say: for text to speech

prompt.say_language
string
Default: en-US

Language to use with say: for text to speech

prompt.say_gender
string
Default: female

Gender to use with say: for text to speech

prompt.max_digits
integer
Default: 1

Number of digits to collect

prompt.terminators
string

Digits that terminate digit collection

prompt.digit_timeout
number
Default: 5.0 seconds

Time in seconds to wait for next digit

prompt.initial_timeout
number
Default: 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.status_url
string

HTTP or HTTPS URL to deliver prompt status events.

note

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​

  1. 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

  2. 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

  3. 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 params. For the list of useable voices and languages, refer to the supported voices and languages section below.

  4. 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.ringAvailable 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.

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​

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​

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​

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​

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.