# Prompt API

[`/call/prompt`](/specs/#/call/prompt) allows to ask for user input in a convenient way. It supports the same parameters as [`/call/say`](/specs/#/call/say), with two additional ones:

- `timeout`: Wait time in milliseconds before the prompt times out. The timeout starts when the synthesized text has finished playing. User input (transcription results or DTMF) restarts the timeout.
- `type`: What kind of prompt to start.

When the prompt finishes, the result is provided via the [`/answer`](/specs/?urls.primaryName=Bot%20API%20(Client)#/bot/answer) endpoint.

## Prompt Types

Currently, two prompt types are supported: `MultipleChoice` and `Number`.

While a prompt is active, no `type = DTMF` events are sent to the Bot API's [`/message`](/specs/?urls.primaryName=Bot%20API%20(Client)#/bot/message) endpoint. `type = SPEECH` events still make it to the bot as long as they don't match one of the `MultipleChoice` prompt choices. Since `Number` prompts don't accept voice input, they don't block any speech events.

### Multiple Choice

Require the user to answer a multiple-choice question. The possible choices can be defined dynamically, and each choice can be triggered by multiple synonyms (including DTMF input).

```json
{
  "dialogId": "09e59647-5c77-4c02-a1c5-7fb2b47060f1",
  "text": "Do you agree to the terms and conditions?",
  "language": "en-US",
  "timeout": 5000,
  "type": {
    "name": "MultipleChoice",
    "choices": {
      "yes": [
        "yes",
        "yeah",
        "affirmative",
        "DTMF_1"
      ],
      "no": [
        "no",
        "never",
        "negative",
        "DTMF_0"
      ]
    }
  }
}
```

Synonyms must be non-ambiguous, i.e. a particular synonym may only be used in one choice.

### Number

Require the user to enter a sequence of digits. Input is terminated once one of the `submitSignals` has been detected or the `maxDigits` limit has been reached.

- `submitInputs`: The input that terminates the prompt (`DTMF_#` or `DTMF_*`).
- `maxDigits`: The maximum amount of digits the number can have. If this property is set, input terminates once the limit has been reached.

Here's an example request:

```json
{
  "dialogId": "09e59647-5c77-4c02-a1c5-7fb2b47060f1",
  "text": "Please enter your PIN.",
  "language": "en-US",
  "bargeIn": false,
  "timeout": 5000,
  "type": {
    "name": "Number",
    "submitInputs": [
      "DTMF_#"
    ],
    "maxDigits": 4
  }
}
```

## Answer Types

The types of answers that can be received via the Bot API's [`/answer`](/specs/?urls.primaryName=Bot%20API%20(Client)#/bot/answer) endpoint.

### Multiple Choice

This answer type is provided when the user has successfully answered a `MultipleChoice` prompt within the given `timeout`. It contains:

- the `id` of the choice (the name of the key in the `choices` object)
- the concrete `synonym` that was used to trigger the choice

```json
{
  "dialogId": "09e59647-5c77-4c02-a1c5-7fb2b47060f1",
  "timestamp": 1593767944607,
  "confidence": 83,
  "language": "en-US",
  "callback": "https://callback.com/restbot",
  "type": {
    "name": "MultipleChoice",
    "id": "no",
    "synonym": "never"
  }
}
```

### Number

This answer type is provided when the user has successfully answered a `Number` prompt within the given `timeout`, such as:

```json
{
  "dialogId": "09e59647-5c77-4c02-a1c5-7fb2b47060f1",
  "timestamp": 1593767944607,
  "confidence": 100,
  "language": "en-US",
  "callback": "https://callback.com/restbot",
  "type": {
    "name": "Number",
    "value": "8645"
  }
}
```

### Timeout

This answer type is provided whenever a prompt times out, regardless of the prompt's `type`. It has no additional data:

```json
{
  "dialogId": "09e59647-5c77-4c02-a1c5-7fb2b47060f1",
  "timestamp": 1593767944607,
  "confidence": 100,
  "language": "en-US",
  "callback": "https://callback.com/restbot",
  "type": {
    "name": "Timeout"
  }
}
```

## Dialog API

Like any other interaction, prompts and answers appear as entries in the [Dialog API](/specs/?urls.primaryName=Dialog%20API). An example dialog that starts a number prompt and then drops the call might look like this:

```json
{
  "dialogId": "09e59647-5c77-4c02-a1c5-7fb2b47060f1",
  "callId": null,
  "data": [
    {
      "type": "Start",
      "timestamp": 1593767937348
    },
    {
      "type": "Prompt",
      "timestamp": 1593767937909,
      "promptType": {
        "name": "Number",
        "submitInputs": [
          "DTMF_#"
        ],
        "maxDigits": 4
      }
    },
    {
      "type": "Synthesis",
      "timestamp": 1593767938202,
      "text": "Please enter your PIN"
    },
    {
      "type": "Answer",
      "timestamp": 1593767944607,
      "answerType": {
        "name": "Number",
        "value": "5841"
      }
    },
    {
      "type": "End",
      "timestamp": 1593767944890,
      "reason": "botTerminated"
    }
  ]
}
```

Some things worth noting:

- While a prompt is active, DTMF input is "consumed", meaning that there won't be any `/message` with `"type": "DTMF"`.
- The prompt's `text` shows up as a separate `Synthesis` entry after the `Prompt`.