Share via

AppRoute interface

Package:
@microsoft/agents-hosting

Represents a route configuration for handling bot activities within an application.

Remarks

An AppRoute defines how incoming activities are matched and processed by combining a selector function that determines when the route should be activated with a handler function that processes the matched activities. Example

const echoRoute: AppRoute<MyTurnState> = {
  selector: (activity) => activity.type === 'message',
  handler: async (context, state) => {
    await context.sendActivity(`You said: ${context.activity.text}`);
  }
};

Properties

authHandlers

Optional list of authorization handlers that this route requires.

Example

authHandlers: ['oauth', 'admin-only']
handler

The handler function that processes the activity if the selector matches.
isInvokeRoute

Indicates whether this route is an invoke route.
rank

Optional rank of the route, used to determine the order in which routes are evaluated. 0 - number.MAX_VALUE. Ranks of the same value are evaluated in order of addition.
selector

The selector function used to determine if this route should handle the current activity.

Property Details

authHandlers

Optional list of authorization handlers that this route requires.

Example

authHandlers: ['oauth', 'admin-only']

authHandlers?: string[]

Property Value

string[]

Remarks

If provided, the route will check for these authorization handlers before processing the activity. Each string in the array should correspond to a registered authorization handler name. All specified handlers must pass authorization checks before the route handler is invoked.

handler

The handler function that processes the activity if the selector matches.

handler: RouteHandler<TState>

Property Value

RouteHandler<TState>

Remarks

This function contains the core logic for handling the matched activity. It receives the turn context and state, allowing it to process the activity and respond appropriately. The handler can be asynchronous and should return a promise that resolves when processing is complete.

isInvokeRoute

Indicates whether this route is an invoke route.

isInvokeRoute?: boolean

Property Value

boolean

Remarks

Invoke routes are used for specific types of activities, such as messaging extensions, adaptive card actions, or other invoke-based interactions. When set to true, this route will be processed differently than regular message routes, typically with special handling for invoke responses.

rank

Optional rank of the route, used to determine the order in which routes are evaluated. 0 - number.MAX_VALUE. Ranks of the same value are evaluated in order of addition.

rank?: number

Property Value

number

selector

The selector function used to determine if this route should handle the current activity.

selector: Selector

Property Value

Selector

Remarks

This function is called for each incoming activity to determine if the route's handler should be invoked. It receives the activity and returns a boolean indicating whether this route should process the activity.