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

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

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:

Raw JSON example

Digit input:

1
{
2
  "event_type": "calling.call.collect",
3
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4
  "timestamp": 1640000000.123,
5
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7
  "params": {
8
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11
    "result": {
12
      "type": "digit",
13
      "params": {
14
        "digits": "1234",
15
        "terminator": "#"
16
      }
17
    }
18
  }
19
}

Speech input:

1
{
2
  "event_type": "calling.call.collect",
3
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4
  "timestamp": 1640000000.123,
5
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7
  "params": {
8
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11
    "result": {
12
      "type": "speech",
13
      "params": {
14
        "text": "one",
15
        "confidence": 0.95
16
      }
17
    }
18
  }
19
}

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

1
version: 1.0.0
2
sections:
3
  main:
4
    - prompt:
5
        play: 'say:Input a number'
6
    - switch:
7
        variable: prompt_value
8
        default:
9
          - play:
10
              url: 'say:You didn''t press one'
11
          - transfer:
12
              dest: main
13
        case:
14
          '1':
15
            - play:
16
                url: 'say:You pressed one'

Using terminators

1
version: 1.0.0
2
sections:
3
  main:
4
    - prompt:
5
        play: 'say:PIN number please'
6
        max_digits: 10
7
        terminators: '*#5'
8
    - play:
9
        url: 'say: ${prompt_value} was terminated by ${prompt_digit_terminator}'

Play prompt and wait for digit or speech

1
version: 1.0.0
2
sections:
3
  main:
4
    - prompt:
5
        play: 'https://example.com/press_or_say_one.wav'
6
        speech_language: en-US
7
        max_digits: 1
8
        speech_hints:
9
          - one
10
          - two
11
          - three
12
          - four
13
          - five
14
          - six
15
          - seven
16
          - eight
17
          - nine
18
    - switch:
19
        variable: prompt_value
20
        default:
21
          - play:
22
              url: 'https://example.com/bad_input.wav'
23
          - transfer:
24
              dest: main
25
        case:
26
          '1':
27
            - transfer:
28
                dest: 'https://example.com/sales.swml'
29
          one:
30
            - transfer:
31
                dest: 'https://example.com/sales.swml'

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

1
version: 1.0.0
2
sections:
3
  main:
4
    - prompt:
5
        play: 'https://example.com/menu.wav'
6
    - transfer:
7
        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.