***

id: d2f38fd7-8352-4aaf-9e45-0119cbbce60a
title: prompt
slug: /reference/prompt
description: Play a prompt and wait for input.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

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](#properties) are set.

## **Properties**

<ParamField path="prompt" type="object" required={true} toc={true}>
  An object that accepts the following properties.
</ParamField>

<Indent>
  <ParamField path="prompt.play" type="string | string[]" required={true} toc={true}>
    Either a [playable sound](#playable-sounds) or an array of [playable sounds](#playable-sounds)
  </ParamField>

  <ParamField path="prompt.volume" type="number" default="0" toc={true}>
    Volume gain to apply to played URLs. Allowed values from `-40.0` to `40.0`.
  </ParamField>

  <ParamField path="prompt.say_voice" type="string" default="Polly.Salli" toc={true}>
    Voice to use with `say:` for text to speech
  </ParamField>

  <ParamField path="prompt.say_language" type="string" default="en-US" toc={true}>
    Language to use with `say:` for text to speech
  </ParamField>

  <ParamField path="prompt.say_gender" type="string" default="female" toc={true}>
    Gender to use with `say:` for text to speech
  </ParamField>

  <ParamField path="prompt.max_digits" type="integer" default="1" toc={true}>
    Number of digits to collect
  </ParamField>

  <ParamField path="prompt.terminators" type="string" toc={true}>
    Digits that terminate digit collection
  </ParamField>

  <ParamField path="prompt.digit_timeout" type="number" default="5.0 seconds" toc={true}>
    Time in seconds to wait for next digit
  </ParamField>

  <ParamField path="prompt.initial_timeout" type="number" default="5.0 seconds" toc={true}>
    Time in seconds to wait for start of input
  </ParamField>

  <ParamField path="prompt.speech_timeout" type="number" toc={true}>
    Max time in seconds to wait for speech result
  </ParamField>

  <ParamField path="prompt.speech_end_timeout" type="number" toc={true}>
    Time in seconds to wait for end of speech utterance
  </ParamField>

  <ParamField path="prompt.speech_language" type="string" toc={true}>
    Language to detect speech in
  </ParamField>

  <ParamField path="prompt.speech_hints" type="string[]" toc={true}>
    Expected words to match
  </ParamField>

  <ParamField path="prompt.speech_engine" type="string" toc={true}>
    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).
  </ParamField>

  <ParamField path="prompt.status_url" type="string" toc={true}>
    HTTP or HTTPS URL to deliver prompt status events. Learn more about [status callbacks][statuscallbacks].
  </ParamField>
</Indent>

<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`).
</Note>

## 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](#supported-ring-tones) 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](#properties). For the list of useable voices and languages,
refer to the [supported voices and languages](#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](/docs/platform/voice/tts).

### 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:

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.collect` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing prompt-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.control_id" type="string" toc={true}>
    The control ID for this prompt operation.
  </ParamField>

  <ParamField path="params.result" type="object" toc={true}>
    The collection result details.
  </ParamField>

  <Indent>
    <ParamField path="result.type" type="string" toc={true}>
      The type of input collected. **Valid values:** `digit`, `speech`, `no_input`, `no_match`, `start_of_input`, `finished`, `error`.
    </ParamField>

    <ParamField path="result.params.digits" type="string" toc={true}>
      The DTMF digits collected (when `type` is `digit`).
    </ParamField>

    <ParamField path="result.params.terminator" type="string" toc={true}>
      The terminator digit that ended collection (when `type` is `digit`).
    </ParamField>

    <ParamField path="result.params.text" type="string" toc={true}>
      The recognized speech text (when `type` is `speech`).
    </ParamField>

    <ParamField path="result.params.confidence" type="number" toc={true}>
      The speech recognition confidence score (when `type` is `speech`).
    </ParamField>
  </Indent>

  <ParamField path="params.final" type="boolean" toc={true}>
    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.
  </ParamField>

  <ParamField path="params.state" type="string" toc={true}>
    The current collection state. Only present when continuous collect is enabled. **Valid values:** `collecting`, `finished`, `error`.
  </ParamField>
</Indent>

### Raw JSON example

**Digit input:**

```json
{
  "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:**

```json
{
  "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](/docs/swml/reference/play) 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

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    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'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "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"
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Using terminators

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    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}'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "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}"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Play prompt and wait for digit or speech

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    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'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "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"
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

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

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - prompt:
            play: 'https://example.com/menu.wav'
        - transfer:
            dest: 'https://example.com/post_next_menu'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "prompt": {
              "play": "https://example.com/menu.wav"
            }
          },
          {
            "transfer": {
              "dest": "https://example.com/post_next_menu"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

In this case, the URL listed in transfer will be sent an HTTP POST request
with all the [out variables](#set-by-the-method) (like `prompt_value`) already set. For
more details on this behavior, refer to [`transfer`](/docs/swml/reference/transfer)
statement's documentation.