Events and triggers in adaptive dialogs

APPLIES TO: SDK v4

For an introduction to this topic, see the Triggers concept article in the Composer documentation.

Recognizer event triggers

Note

Azure AI QnA Maker will be retired on 31 March 2025. Beginning 1 October 2022, you won't be able to create new QnA Maker resources or knowledge bases. A newer version of the question and answering capability is now available as part of Azure AI Language.

Custom question answering, a feature of Azure AI Language, is the updated version of the QnA Maker service. For more information about question-and-answer support in the Bot Framework SDK, see Natural language understanding.

Event cause	Trigger name	Base event	Description
Choose Intent	OnChooseIntent	ChooseIntent	This trigger is run when ambiguity has been detected between intents from multiple recognizers in a CrossTrainedRecognizerSet.
Intent recognized	OnIntent	RecognizedIntent	Actions to perform when specified intent is recognized.
QnAMatch intent	OnQnAMatch	RecognizedIntent	This trigger is run when the QnAMakerRecognizer has returned a QnAMatch intent. The entity @answer will have the QnAMaker answer.
Unknown intent recognized	OnUnknownIntent	UnknownIntent	Actions to perform 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 perform any needed tasks when the dialog first starts.

The OnIntent trigger lets you handle the recognizedIntent event. The recognizedIntent event is raised by a recognizer. Except for the QnA Maker recognizer, all of the Bot Framework SDK built-in recognizers emit this event when they successfully identify a user input so that your bot can respond appropriately.

Use the OnUnknownIntent trigger to catch and respond when a recognizedIntent event isn't caught and handled by any of the other triggers. This means that any unhandled intent (including "none") can cause it to trigger, but only if there aren't any currently executing actions for the dialog. Use the OnUnknownIntent trigger to catch and respond when a "none" intent occurs. Using the OnIntent trigger to handle a "none" intent can produce unexpected results.

Dialog event triggers

Dialog triggers handle dialog specific events that are related to the lifecycle of the dialog. There are currently six 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 child's actions will continue running after the handler's actions complete. For all of the events below, the bot will run a new set of actions and will end the turn once those actions have finished.

Trigger name	Base event	Description
OnBeginDialog	BeginDialog	Actions to perform when this dialog begins. For use with child dialogs only, not to be used in your root dialog, In root dialogs, use OnUnknownIntent to perform dialog initialization activities.
OnCancelDialog	CancelDialog	This event allows you to prevent the current dialog from being canceled due to a child dialog executing a CancelAllDialogs action.
OnEndOfActions	EndOfActions	This event occurs once all actions and ambiguity events have been processed.
OnError	Error	Actions to perform when an Error dialog event occurs. This event is similar to OnCancelDialog in that you're preventing the adaptive dialog that contains this trigger from ending, in this case due to an error in a child dialog.
OnRepromptDialog	RepromptDialog	Actions to perform when RepromptDialog event occurs.
OnDialog	DialogEvents.VersionChanged

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.

Event cause	ActivityType	Trigger name	Description
Greeting	ConversationUpdate	OnConversationUpdateActivity	Actions to perform on receipt of a conversationUpdate activity, when the bot or a user joins or leaves a conversation.
Conversation ended	EndOfConversation	OnEndOfConversationActivity	Actions to perform on receipt of an endOfConversation activity.
Event received	Event	OnEventActivity	Actions to perform on receipt of an event activity.
Handover to human	Handoff	OnHandoffActivity	Actions to perform on receipt of a handOff activity.
Conversation invoked	Invoke	OnInvokeActivity	Actions to perform on receipt of an invoke activity.
User is typing	Typing	OnTypingActivity	Actions to perform on receipt of a typing activity.

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.

Event cause	ActivityType	Trigger name	Description
Message received	Message	OnMessageActivity	Actions to perform on receipt of an activity with type MessageReceived.
Message deleted	MessageDeletion	OnMessageDeleteActivity	Actions to perform on receipt of an activity with type MessageDelete.
Message reaction	MessageReaction	OnMessageReactionActivity	Actions to perform on receipt of an activity with type MessageReaction.
Message updated	MessageUpdate	OnMessageUpdateActivity	Actions to perform on receipt of an activity with type MessageUpdate.

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.

Event cause	Trigger name	Base class	Description
Custom event	OnDialogEvent	OnCondition	Actions to perform when a custom event is detected. Use Emit a custom event action to raise a custom event.