Events and triggers in adaptive dialogs
APPLIES TO: SDK v4
Adaptive dialogs introduce a new event based approach to model conversations. Any subsystem in your bot can emit events and all adaptive dialogs contain one or more event handlers called triggers that enable you to react to these events. Any time an event fires, the active adaptive dialog's triggers are evaluated and if any trigger matches the current event, the actions associated with that trigger execute. If an event is not handled in the active dialog, it will be passed up to its parent dialog to be evaluated. This process continues until it is either handled or reaches the bots root dialog. If no event handler (trigger) is found, the event will be ignored and no action will be taken.
Anatomy of a trigger
A trigger is made up of a condition and one or more actions. Bot Framework SDK offers several triggers, each with a set of predefined conditions that examine either the eventName or eventValue. You can add additional conditions to a trigger, giving you additional control when the trigger executes.
The Bot Framework SDK provides various pre-defined triggers designed to handle common event types. For example the
OnIntent trigger fires anytime the recognizer detects an intent. If you are using a LUIS recognizer it will also return a prediction score that measures the degree of confidence LUIS has for its prediction results. In order to increase the reliability and accuracy of your bot, you may only want to execute the
OnIntent trigger if the confidence rating is 80% or higher. You can accomplish this by adding a condition. Triggers all contain an optional
Condition property that when defined, must evaluate to true in order for the trigger to execute. The
Condition property is a string, but must contain a valid adaptive expression to work. The above examples
Condition property would look something like:
Condition = "#<IntentName>.Score >= 0.8". Adaptive expressions enable sophisticated conditions that can handle virtually any scenario that you might have.
All triggers also contain a list of Actions. Actions represent what your bot does in response to a trigger. This is the heart of the trigger. You can learn more about actions and what built in actions are provided in the Bot Framework SDK in the article Actions in adaptive dialogs.
Triggers enable you to catch and respond to events. The broadest trigger from which all other triggers are derived is the
OnCondition trigger that allows you to catch and attach a list of actions to execute when a specific event is emitted by any of the bots subsystems.
Triggers are listed in the following sections, categorized and grouped by trigger type.
Each table in the following sections list all of the triggers supported by adaptive dialogs that are currently in the SDK as well as the events they are based on.
OnCondition trigger is the base trigger that all triggers derive from. When defining triggers in an adaptive dialog they are defined as a list of
For more information and an example, see the Base trigger section in the Adaptive dialogs prebuilt triggers article.
Recognizer event triggers
Recognizers extract meaningful pieces of information from a user's input in the form of intents and entities and when they do, they emit events. For example the
recognizedIntent event fires when the recognizer picks up an intent (or extracts entities) from a given user utterance. You handle this events using the
The following list shows some of the recognizer event triggers available in the Bot Framework SDK:
- Choose Intent. The
OnChooseIntenttrigger executes when there is ambiguity between intents from multiple recognizers in a CrossTrainedRecognizerSet.
- Intent recognized. The
OnIntenttrigger executes when the specified intent is recognized.
- QnA Match. The
OnQnAMatchtrigger executes when the QnAMakerRecognizer has returned a
- No intent was recognized. The
OnUnknownIntenttrigger executes when user input is unrecognized or no match is found in any of the
OnIntenttriggers. You can also use this as your first trigger in your root dialog in place of the
OnBeginDialogto preform any needed tasks when the dialog first starts.
For detailed information and examples, see the Recognizer event triggers section in the Adaptive dialogs prebuilt triggers article.
Dialog event triggers
Dialog triggers handle dialog specific events that are related to the "lifecycle" of the dialog. There are currently 6 dialog triggers in the Bot Framework SDK and they all derive from the
These aren't like normal interruption event handlers where the a child's actions will continue running after the handlers actions complete. For all of the events below the bot will be running a new set of actions and will end the turn once those actions have finished.
For the dialog trigger to:
- Take action immediately when the dialog starts, even before the recognizer is called, use the
- Prevent a dialog from being canceled when any of its child dialogs execute a
CancelAllDialogsaction, use the
- Take action when all actions and ambiguity events have been processed, use the
- Handle an error condition, use the
For detailed information and examples, see the Dialog events section in the Adaptive dialogs prebuilt triggers article.
Activity event triggers
Activity triggers let you associate actions to any incoming activity from the client such as when a new user joins and the bot begins a new conversation. Additional information on activities can be found in Bot Framework Activity schema.
All activity events have a base event of
ActivityReceived and are further refined by their activity type. The Base class that all activity triggers derive from is
- Conversation update. Use this to handle events fired when a user begins a new conversation with the bot.
- Conversation ended. Actions to perform on receipt of an activity with type
- Event received. Actions to perform on receipt of an activity with type
- Handover to human. Actions to perform on receipt of an activity with type
- Conversation invoked. Actions to perform on receipt of an activity with type
- User is typing. Actions to perform on receipt of an activity with type
For detailed information and examples, see the Activity event triggers section in the Adaptive dialogs prebuilt triggers article.
Message event triggers
Message event triggers allow you to react to any message event such as when a message is updated (
MessageUpdate) or deleted (
MessageDeletion) or when someone reacts (
MessageReaction) to a message (for example, some of the common message reactions include a Like, Heart, Laugh, Surprised, Sad and Angry reactions).
Message events are a type of activity event and, as such, all message events have a base event of
ActivityReceived and are further refined by activity type. The Base class that all message triggers derive from is
- Message received. Actions to perform on receipt of an activity with type
- Message deleted. Actions to perform on receipt of an activity with type
- Message reaction. Actions to perform on receipt of an activity with type
- Message updated. Actions to perform on receipt of an activity with type
For detailed information and examples, see the Message event triggers section in the Adaptive dialogs prebuilt triggers article.
Custom event trigger
You can emit your own events by adding the EmitEvent action to any trigger, then you can handle that custom event in any trigger in any dialog in your bot by defining a custom event trigger. A custom event trigger is the
OnDialogEvent trigger that in effect becomes a custom trigger when you set the
Event property to the same value as the EmitEvent's
You can allow other dialogs in your bot to handle your custom event by setting the EmitEvent's
BubbleEvent property to true.
For more information and an example, see the [Custom events][custom-events] section in the Adaptive dialogs prebuilt triggers article.
For detailed information and an example, see the [Custom event triggers][custom-event-triggers] section in the Adaptive dialogs prebuilt triggers article.