ActivityHandler class

Reference

Package:: botbuilder-core

Event-emitting activity handler for bots. Extends ActivityHandlerBase.

Extends: ActivityHandlerBase

Remarks

This provides an extensible class for handling incoming activities in an event-driven way. You can register an arbitrary set of handlers for each event type.

To register a handler for an event, use the corresponding on event method. If multiple handlers are registered for an event, they are run in the order in which they were registered.

This object emits a series of events as it processes an incoming activity. A handler can stop the propagation of the event by not calling the continuation function.

Event type	Description
Turn	Emitted first for every activity.
Type-specific	Emitted for the specific activity type, before emitting an event for any sub-type.
Sub-type	Emitted for certain specialized events, based on activity content.
Dialog	Emitted as the final activity processing event.

For example:

const bot = new ActivityHandler();

server.post('/api/messages', (req, res) => {
    adapter.processActivity(req, res, async (context) => {
        // Route to bot's activity logic.
        await bot.run(context);
    });
});

bot.onTurn(async (context, next) => {
        // Handle a "turn" event.
        await context.sendActivity(`${ context.activity.type } activity received.`);
        // Continue with further processing.
        await next();
    })
    .onMessage(async (context, next) => {
        // Handle a message activity.
        await context.sendActivity(`Echo: ${ context.activity.text }`);
        // Continue with further processing.
        await next();
    });

See also

The Bot Framework Activity schema

Methods

onCommand(BotHandler)	Registers an activity event handler for the command activity.
onCommandResult(BotHandler)	Registers an activity event handler for the CommandResult activity.
onConversationUpdate(BotHandler)	Registers an activity event handler for the conversation update event, emitted for every incoming conversation update activity.
onDialog(BotHandler)	Registers an activity event handler for the dialog event, emitted as the last event for an incoming activity.
onEndOfConversation(BotHandler)	Registers an activity event handler for the end of conversation activity.
onEvent(BotHandler)	Registers an activity event handler for the event event, emitted for every incoming event activity.
onInstallationUpdate(BotHandler)	Registers an activity event handler for the installationupdate activity.
onInstallationUpdateAdd(BotHandler)	Registers an activity event handler for the installationupdate add activity.
onInstallationUpdateRemove(BotHandler)	Registers an activity event handler for the installationupdate remove activity.
onMembersAdded(BotHandler)	Registers an activity event handler for the members added event, emitted for any incoming conversation update activity that includes members added to the conversation.
onMembersRemoved(BotHandler)	Registers an activity event handler for the members removed event, emitted for any incoming conversation update activity that includes members removed from the conversation.
onMessage(BotHandler)	Registers an activity event handler for the message event, emitted for every incoming message activity.
onMessageReaction(BotHandler)	Registers an activity event handler for the message reaction event, emitted for every incoming message reaction activity.
onReactionsAdded(BotHandler)	Registers an activity event handler for the reactions added event, emitted for any incoming message reaction activity that describes reactions added to a message.
onReactionsRemoved(BotHandler)	Registers an activity event handler for the reactions removed event, emitted for any incoming message reaction activity that describes reactions removed from a message.
onTokenResponseEvent(BotHandler)	Registers an activity event handler for the tokens-response event, emitted for any incoming `tokens/response` event activity. These are generated as part of the OAuth authentication flow.
onTurn(BotHandler)	Registers an activity event handler for the turn event, emitted for every incoming activity, regardless of type.
onTyping(BotHandler)	Registers an activity event handler for the typing activity.
onUnrecognizedActivityType(BotHandler)	Registers an activity event handler for the unrecognized activity type event, emitted for an incoming activity with a type for which the ActivityHandler doesn't provide an event handler.
run(TurnContext)	Called to initiate the event emission process.

Method Details

onCommand(BotHandler)

Registers an activity event handler for the command activity.

function onCommand(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

To handle a Command event, use the onCommand type-specific event handler.

onCommandResult(BotHandler)

Registers an activity event handler for the CommandResult activity.

function onCommandResult(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

To handle a CommandResult event, use the onCommandResult type-specific event handler.

onConversationUpdate(BotHandler)

Registers an activity event handler for the conversation update event, emitted for every incoming conversation update activity.

function onConversationUpdate(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

Conversation update activities describe a changes to a conversation's metadata, such as title, participants, or other channel-specific information.

To handle when members are added to or removed from the conversation, use the onMembersAdded and onMembersRemoved sub-type event handlers.

onDialog(BotHandler)

Registers an activity event handler for the dialog event, emitted as the last event for an incoming activity.

function onDialog(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

onEndOfConversation(BotHandler)

Registers an activity event handler for the end of conversation activity.

function onEndOfConversation(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

This activity is typically send from a Skill to a Skill caller indicating the end of that particular child conversation.

To handle an End of Conversation, use the onEndOfConversation type-specific event handler.

onEvent(BotHandler)

Registers an activity event handler for the event event, emitted for every incoming event activity.

function onEvent(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

Event activities communicate programmatic information from a client or channel to a bot. The meaning of an event activity is defined by the activity's name property, which is meaningful within the scope of a channel. Event activities are designed to carry both interactive information (such as button clicks) and non-interactive information (such as a notification of a client automatically updating an embedded speech model).

To handle a tokens/response event event, use the onTokenResponseEvent sub-type event handler. To handle other named events, add logic to this handler.

onInstallationUpdate(BotHandler)

Registers an activity event handler for the installationupdate activity.

function onInstallationUpdate(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

To handle a InstallationUpdate event, use the onInstallationUpdate type-specific event handler.

onInstallationUpdateAdd(BotHandler)

Registers an activity event handler for the installationupdate add activity.

function onInstallationUpdateAdd(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object. To handle a InstallationUpdateAdd event, use the onInstallationUpdateAdd type-specific event handler.

onInstallationUpdateRemove(BotHandler)

Registers an activity event handler for the installationupdate remove activity.

function onInstallationUpdateRemove(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

To handle a InstallationUpdateRemove event, use the onInstallationUpdateRemove type-specific event handler.

onMembersAdded(BotHandler)

Registers an activity event handler for the members added event, emitted for any incoming conversation update activity that includes members added to the conversation.

function onMembersAdded(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

The activity's membersAdded property contains the members added to the conversation, which can include the bot.

To handle conversation update events in general, use the onConversationUpdate type-specific event handler.

onMembersRemoved(BotHandler)

Registers an activity event handler for the members removed event, emitted for any incoming conversation update activity that includes members removed from the conversation.

function onMembersRemoved(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

The activity's membersRemoved property contains the members removed from the conversation, which can include the bot.

To handle conversation update events in general, use the onConversationUpdate type-specific event handler.

onMessage(BotHandler)

Registers an activity event handler for the message event, emitted for every incoming message activity.

function onMessage(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

Message activities represent content intended to be shown within a conversational interface and can contain text, speech, interactive cards, and binary or unknown attachments. Not all message activities contain text, the activity's text property can be null or undefined.

onMessageReaction(BotHandler)

Registers an activity event handler for the message reaction event, emitted for every incoming message reaction activity.

function onMessageReaction(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

Message reaction activities represent a social interaction on an existing message activity within a conversation. The original activity is referred to by the message reaction activity's replyToId property. The from property represents the source of the reaction, such as the user that reacted to the message.

To handle when reactions are added to or removed from messages in the conversation, use the onReactionsAdded and onReactionsRemoved sub-type event handlers.

onReactionsAdded(BotHandler)

Registers an activity event handler for the reactions added event, emitted for any incoming message reaction activity that describes reactions added to a message.

function onReactionsAdded(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

The activity's reactionsAdded property includes one or more reactions that were added.

To handle message reaction events in general, use the onMessageReaction type-specific event handler.

onReactionsRemoved(BotHandler)

Registers an activity event handler for the reactions removed event, emitted for any incoming message reaction activity that describes reactions removed from a message.

function onReactionsRemoved(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

The activity's reactionsRemoved property includes one or more reactions that were removed.

To handle message reaction events in general, use the onMessageReaction type-specific event handler.

onTokenResponseEvent(BotHandler)

Registers an activity event handler for the tokens-response event, emitted for any incoming tokens/response event activity. These are generated as part of the OAuth authentication flow.

function onTokenResponseEvent(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

The activity's value property contains the user token.

If your bot handles authentication using an OAuthPrompt within a dialog, then the dialog will need to receive this activity to complete the authentication flow.

To handle other named events and event events in general, use the onEvent type-specific event handler.

onTurn(BotHandler)

Registers an activity event handler for the turn event, emitted for every incoming activity, regardless of type.

function onTurn(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

onTyping(BotHandler)

Registers an activity event handler for the typing activity.

function onTyping(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

To handle a Typing event, use the onTyping type-specific event handler.

onUnrecognizedActivityType(BotHandler)

Registers an activity event handler for the unrecognized activity type event, emitted for an incoming activity with a type for which the ActivityHandler doesn't provide an event handler.

function onUnrecognizedActivityType(handler: BotHandler): this

Parameters

handler: BotHandler

The event handler.

Returns

this

A reference to the ActivityHandler object.

Remarks

The ActivityHandler does not define events for all activity types defined in the Bot Framework Activity schema. In addition, channels and custom adapters can create Activities with types not in the schema. When the activity handler receives such an event, it emits an unrecognized activity type event.

The activity's type property contains the activity type.

run(TurnContext)

Called to initiate the event emission process.

function run(context: TurnContext): Promise<void>

Parameters

context: TurnContext

The context object for the current turn.

Returns

Promise<void>

Remarks

Typically, you would provide this method as the function handler that the adapter calls to perform the bot's logic after the received activity has been pre-processed by the adapter and routed through any middleware.

For example:

 server.post('/api/messages', (req, res) => {
     adapter.processActivity(req, res, async (context) => {
         // Route to bot's activity logic.
         await bot.run(context);
     });
});

See also

BotFrameworkAdapter.processActivity