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. Each entry can also be a SWML variable that resolves to a playable sound. Unlike the play method, prompt.play doesn’t accept an object.

prompt.volume

numberDefaults to 0

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

prompt.say_voice

string

Voice to use with say: for text to speech. When not set, the say_voice variable is used if it is set; otherwise, a voice is selected based on the language and gender. A voice name can’t contain whitespace, double quotes, backticks, or any of the characters ,{}()[]<>=/;!@#$%^&*+|~?.

prompt.say_language

stringDefaults to en-US

Language to use with say: for text to speech, as a language tag such as en-US. When not set, the say_language variable is used if it is set, otherwise en-US.

prompt.say_gender

stringDefaults to female

Gender to use with say: for text to speech. Valid values: male, female. When not set, the say_gender variable is used if it is set, otherwise female.

prompt.max_digits

integerDefaults to 1

Number of digits to collect. Must be at least 1. Values above 100 are capped at 100.

prompt.terminators

string

Digits that terminate digit collection

prompt.digit_timeout

numberDefaults to 5.0 seconds

Time in seconds to wait for next digit. Must be at least 1.

prompt.initial_timeout

numberDefaults to 5.0 seconds

Time in seconds to wait for start of input. Must be at least 1. This sets the wait only; it doesn’t select digit or speech input.

prompt.speech_timeout

number

Max time in seconds to wait for speech result. Must be at least 1.

prompt.speech_end_timeout

number

Time in seconds to wait for end of speech utterance. Must be at least 1.

prompt.speech_language

string

Language to detect speech in, as a language tag such as en-US. Extension and private-use subtags aren’t accepted. A valid tag doesn’t guarantee that every speech engine supports the language.

prompt.speech_hints

string[]

Expected words or phrases to help speech recognition. Each hint must be a non-empty string and is sent as written; SWML variables inside hints aren’t expanded. Hints longer than 100 bytes or containing = are ignored, and hints after the first 5,000, or after 100,000 bytes in total, are dropped.

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, or a SWML variable that resolves to one. 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. Setting speech_engine alone doesn’t enable speech input.

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, or digit_timeout). initial_timeout doesn’t count as a digit input parameter.

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:]<ringtone>.

The total duration can be specified in seconds as an optional second parameter, and must be at least 1 second. When left unspecified, it will ring just once. The ringtone name must be specified. Most names are country identifiers, like us for United States or it for Italy. For the list of available ringtones, 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>. The text can’t be empty. 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, and must be at least 1 second.

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 two-letter country identifiers: at, au, be, bg, br, ca, ch, cl, cn, cy, cz, de, dk, dz, ee, eg, es, fi, fr, gr, hu, il, in, it, jp, ko, lt, mx, my, nl, no, nz, ph, pk, pl, pt, ro, rs, ru, sa, se, sg, th, tr, tw, uk, us, ve, za. The named tone bong is also available.

Set by the method

prompt_result: (out) - usually failed, no_input, match_speech, match_digits, or no_match. If speech recognition reports an error, it can instead hold that error value.
prompt_value: (out) - the digits collected, unchanged, or the recognized speech, normalized: converted to lowercase, with punctuation and other separators collapsed into single spaces and removed from the start and end. Apostrophes, hyphens, and non-ASCII characters are kept.
prompt_value_raw: (out) - the digits or recognized speech exactly as collected, before normalization. Cleared along with prompt_value when nothing is collected or the method fails.
prompt_digit_terminator: (out) - digit terminator collected, if any.
prompt_speech_confidence: (out) - speech confidence measured, if any.

StatusCallbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

A POST request will be sent to status_url with a JSON payload like the following. The prompt sends two kinds of events to the same URL: calling.call.collect with the input result, and calling.call.play as the prompt audio plays.

event_type

string

The type of event: calling.call.collect for the input result, or calling.call.play for prompt playback state.

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. Present on calling.call.collect events.

params.result.type

string

The type of result. Standard values are digit, speech, no_input, no_match, and error. If speech recognition reports an error, it can instead hold that error value.

params.result.params

object

The collected input. Present when type is digit or speech.

params.result.params.digits

string

The DTMF digits collected (when type is digit).

params.result.params.terminator

string

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

params.result.params.text

string

The recognized speech text, before the normalization applied to prompt_value (when type is speech).

params.result.params.confidence

number

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

params.state

string

On calling.call.play events, the playback state of the prompt audio. Valid values: playing, finished, error.

On calling.call.collect events, 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
      }
    }
  }
}

Prompt playback:

{
  "event_type": "calling.call.play",
  "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",
    "state": "finished"
  }
}

Error notifications

When the prompt request itself fails, status_url can also receive a separate event with event_type set to calling.error. Its params.error object carries the error code and message. Not every failure produces this event.

Examples

The play method also has examples related to playing sounds from URLs. Both methods use the same playable sound syntax, but prompt.play takes only a string or an array of strings, not a play object. Set volume, the say_* properties, and status_url directly on prompt; other play properties, such as loop, aren’t available.

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'

Set the voice and language

say_voice and say_language set the text-to-speech voice for the prompt. speech_language sets the language to recognize, so match it when the caller answers in the same language. To apply a voice to every prompt and play in the script, use set to set the say_voice and say_language variables instead.

version: 1.0.0
sections:
  main:
    - prompt:
        play: 'say:Para ventas, diga ventas o marque uno.'
        say_voice: gcloud.es-ES-Neural2-A
        say_language: es-ES
        speech_language: es-ES
        max_digits: 1
        speech_hints:
          - ventas
    - play:
        url: 'say:Recibimos ${prompt_value}'
        say_voice: gcloud.es-ES-Neural2-A
        say_language: es-ES

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.