Recognize user intent from message content

Note

This topic applies to SDK v3 release. You can find the documentation for the latest version of the SDK v4 here.

When your bot receives a message from a user, your bot can use a recognizer to examine the message and determine intent. The intent provides a mapping from messages to dialogs to invoke. This article explains how to recognize intent using regular expressions or by inspecting the content of a message. For example, a bot can use regular expressions to check if a message contains the word "help" and invoke a help dialog. A bot can also check the properties of the user message, for example, to see if the user sent an image instead of text and invoke an image processing dialog.

Note

For information on recognizing intent using LUIS, see Recognize intents and entities with LUIS

Use the built-in regular expression recognizer

Use RegExpRecognizer to detect the user's intent using a regular expression. You can pass multiple expressions to the recognizer to support multiple languages.

Tip

See Support localization for more information on localizing your bot.

The following code creates a regular expression recognizer named CancelIntent and adds it to your bot. The recognizer in this example provides regular expressions for both the en_us and ja_jp locales.

bot.recognizer(new builder.RegExpRecognizer( "CancelIntent", { en_us: /^(cancel|nevermind)/i, ja_jp: /^(キャンセル)/ }));

Once the recognizer is added to your bot, attach a triggerAction to the dialog that you want the bot to invoke when the recognizer detects the intent. Use the matches option to specify the intent name, as shown in the following code:

bot.dialog('CancelDialog', function (session) {
    session.endConversation("Ok, I'm canceling your order.");
}).triggerAction({ matches: 'CancelIntent' });

Intent recognizers are global, which means that the recognizer will run for every message received from the user. If a recognizer detects an intent that is bound to a dialog using a triggerAction, it can trigger interruption of the currently active dialog. Allowing and handling interruptions is a flexible design that accounts for what users really do.

Tip

To learn how a triggerAction works with dialogs, see Managing conversation flow. To learn more about the various actions you can associate with a recognized intent, Handle user actions.

Register a custom intent recognizer

You can also implement a custom recognizer. This example adds a simple recognizer that looks for the user to say 'help' or 'goodbye' but you could easily add a recognizer that does more complex processing, such as one that recognizes when the user sends an image.

var builder = require('../../core/');

// Create bot and default message handler
var connector = new builder.ConsoleConnector().listen();
var bot = new builder.UniversalBot(connector, function (session) {
    session.send("You said: '%s'. Try asking for 'help' or say 'goodbye' to quit", session.message.text);
});


// Install a custom recognizer to look for user saying 'help' or 'goodbye'.
bot.recognizer({
  recognize: function (context, done) {
  var intent = { score: 0.0 };

        if (context.message.text) {
            switch (context.message.text.toLowerCase()) {
                case 'help':
                    intent = { score: 1.0, intent: 'Help' };
                    break;
                case 'goodbye':
                    intent = { score: 1.0, intent: 'Goodbye' };
                    break;
            }
        }
        done(null, intent);
    }
});

Once you've registered a recognizer, you can associate the recognizer with an action using a matches clause.

// Add a help dialog with a trigger action that is bound to the 'Help' intent
bot.dialog('helpDialog', function (session) {
    session.endDialog("This bot will echo back anything you say. Say 'goodbye' to quit.");
}).triggerAction({ matches: 'Help' });


// Add a global endConversation() action that is bound to the 'Goodbye' intent
bot.endConversationAction('goodbyeAction', "Ok... See you later.", { matches: 'Goodbye' });

Disambiguate between multiple intents

Your bot can register more than one recognizer. Notice that the custom recognizer example involves assigning a numerical score to each intent. This is done since your bot may have more than one recognizer, and the Bot Builder SDK provides built-in logic to disambiguate between intents returned by multiple recognizers. The score assigned to an intent is typically between 0.0 and 1.0, but a custom recognizer may define an intent greater than 1.1 to ensure that that intent will always be chosen by the Bot Builder SDK's disambiguation logic.

By default, recognizers run in parallel, but you can set recognizeOrder in IIntentRecognizerSetOptions so the process quits as soon as your bot finds one that gives a score of 1.0.

The Bot Builder SDK includes a sample that demonstrates how to provide custom disambiguation logic in your bot by implementing IDisambiguateRouteHandler.

Next steps

The logic for using regular expressions and inspecting message contents can become complex, especially if your bot's conversational flow is open-ended. To help your bot handle a wider variety of textual and spoken input from users, you can use an intent recognition service like LUIS to add natural language understanding to your bot.