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.

Prerequisites

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.

Trigger types

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.

Base trigger

The 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 OnCondition objects.

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 OnIntent trigger.

The following list shows some of the recognizer event triggers available in the Bot Framework SDK:

  • Choose Intent. The OnChooseIntent trigger executes when there is ambiguity between intents from multiple recognizers in a CrossTrainedRecognizerSet.
  • Intent recognized. The OnIntent trigger executes when the specified intent is recognized.
  • QnA Match. The OnQnAMatch trigger executes when the QnAMakerRecognizer has returned a QnAMatch intent.
  • No intent was recognized. The OnUnknownIntent trigger executes when user input is unrecognized or no match is found in any of the OnIntent triggers. You can also use this as your first trigger in your root dialog in place of the OnBeginDialog to 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 OnDialogEvent class.

Tip

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 OnBeginDialog trigger.
  • Prevent a dialog from being canceled when any of its child dialogs execute a CancelAllDialogs action, use the OnCancelDialog trigger.
  • Take action when all actions and ambiguity events have been processed, use the OnEndOfActions trigger.
  • Handle an error condition, use the OnError trigger.

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 OnActivity.

  • 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 EndOfConversation.
  • Event received. Actions to perform on receipt of an activity with type Event.
  • Handover to human. Actions to perform on receipt of an activity with type HandOff.
  • Conversation invoked. Actions to perform on receipt of an activity with type Invoke.
  • User is typing. Actions to perform on receipt of an activity with type Typing.

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 OnActivity.

  • Message received. Actions to perform on receipt of an activity with type MessageReceived.
  • Message deleted. Actions to perform on receipt of an activity with type MessageDelete.
  • Message reaction. Actions to perform on receipt of an activity with type MessageReaction.
  • Message updated. Actions to perform on receipt of an activity with type MessageUpdate.

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 EventName property.

Tip

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.

Additional Information