Prompts

Collecting Input

Bot Builder comes with a number of built-in prompts that can be used to collect input from a user.

Prompt Type Description
Prompts.choice Asks the user to choose from a list of choices.
Prompts.digits Asks the user to enter a sequence of digits.
Prompts.confirm Asks the user to confirm an action.
Prompts.record Asks the record a message.
Prompts.action Sends a raw action to the calling service and lets the bot manually process its outcome.

These built-in prompts are implemented as a Dialog so they’ll return the users response through a call to session.endDialogWithresult(). Any DialogHandler can receive the result of a dialog but waterfalls tend to be the simplest way to handle a prompt result.

Prompts return to the caller an IPromptResult. The users response will be contained in the results.response field and may be null should the user fail to input a proper response.

Prompts.choice()

The Prompts.choice() method asks the user to pick an option from a list. The users response will be returned as an IPromptChoiceResult. The list of choices is passed to the prompt as an array of IRecognitionChoice objects.

You can configure the prompt to use speech recognition to recognize the callers choice:

calling.Prompts.choice(session, "Which department? support, billing, or claims?", [
    { name: 'support', speechVariation: ['support', 'customer service'] },
    { name: 'billing', speechVariation: ['billing'] },
    { name: 'claims', speechVariation: ['claims'] }
]);

Or DTMF input using Skypes diling pad:

calling.Prompts.choice(session, "Which department? Press 1 for support, 2 for billing, or 3 for claims", [
    { name: 'support', dtmfVariation: '1' },
    { name: 'billing', dtmfVariation: '2' },
    { name: 'claims', dtmfVariation: '3' }
]);

Or both speech recognition and DTMF:

bot.dialog('/departmentMenu', [
    function (session) {
        calling.Prompts.choice(session, "Which department? Press 1 for support, 2 for billing, 3 for claims, or star to return to previous menu.", [
            { name: 'support', dtmfVariation: '1', speechVariation: ['support', 'customer service'] },
            { name: 'billing', dtmfVariation: '2', speechVariation: ['billing'] },
            { name: 'claims', dtmfVariation: '3', speechVariation: ['claims'] },
            { name: '(back)', dtmfVariation: '*', speechVariation: ['back', 'previous'] }
        ]);
    },
    function (session, results) {
        if (results.response !== '(back)') {
            session.beginDialog('/' + results.response.entity + 'Menu');
        } else {
            session.endDialog();
        }
    },
    function (session) {
        // Loop menu
        session.replaceDialog('/departmentMenu');
    }
]);

The users choice is returned as an IFindMatchResult similar to chat bots and the choices name will be assigned to the response.entity property.

Prompts.digits()

The Prompts.digits() method asks the user to enter a sequence of digits followed by an optional stop tone. The users response will be returned as an IPromptDigitsResult.

calling.Prompts.digits(session, "Please enter your account number followed by pound.", 10, { stopTones: ['#'] });

Prompts.confirm()

The Prompts.confirm() method asks the user to confirm some action. This prompt builds on the choices prompt by calling it with a standard set of yes & no choices. The user can reply by saying a range of responses or they can press 1 for yes or 2 for no. The users response will be returned as an IPromptConfirmResult.

calling.Prompts.confirm(session, "Would you like to end the call?");

Prompts.record()

The Prompts.record() method asks the user to record a message. This prompt builds on the choices prompt by calling it with a standard set of yes & no choices. The recorded message will be returned as an IPromptRecordResult and the recorded audio will be available off that object as a {Buffer}.

calling.Prompts.record(session, "Please leave a message after the beep.");

Prompts.action()

The Prompts.action() method lets you send the calling service a raw action object. The outcome will be returned as an IPromptActionResult for manual processing by your bot.

In general, you shouldn’t ever need to call this prompt but one scenario where you might is if you wanted to send a playPrompt action that plays a file to the user and you’d like to keep the call active so you can take another action once that completes. The normal session.send() method you’d use to play a file will automatically end the call if that playPrompt action isn’t followed by a recognize or record action so this gives you a way of dynamically chaining play prompts together. You might do this if you want to play the user hold music or silence while you periodically check for some long running operation to complete.