Prompt API

/call/prompt allows to ask for user input in a convenient way. It supports the same parameters as /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 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 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).

{
  "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:

{
  "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 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

{
  "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:

{
  "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:

{
  "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. An example dialog that starts a number prompt and then drops the call might look like this:

{
  "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.