Class BotApplication

constructor

• new BotApplication(options?: BotApplicationOptions): BotApplication

  Create a new BotApplication.

  Options fall back to environment variables (CLIENT_ID, CLIENT_SECRET, TENANT_ID) when not provided explicitly.

  Parameters

  • options: BotApplicationOptions = {}

    Bot credentials and configuration. Defaults to env vars.

  Returns BotApplication

Static Readonlyversion

Readonlyoptions

ReadonlyconversationClient

OptionalonActivity

on

• on(type: string, handler: CoreActivityHandler): this

  Register a handler for a given activity type.

  Only one handler per type is supported; registering the same type twice replaces the previous handler.

  Parameters

  • type: string

    CoreActivity type string (e.g. "message", "conversationUpdate").

  • handler: CoreActivityHandler

    Async function called with the turn context.

  Returns this

  this for method chaining.

use

• use(middleware: TurnMiddleware): this

  Add a middleware to the turn processing pipeline.

  Middleware runs in registration order before the activity handler.

  Parameters

  • middleware: TurnMiddleware

    Middleware function to add. See TurnMiddleware.

  Returns this

  this for method chaining.

onInvoke

• onInvoke(name: string, handler: InvokeActivityHandler): this

  Register a handler for an invoke activity by its activity.name sub-type.

  The handler must return an InvokeResponse — the status and body are written directly to the HTTP response for invoke activities.

  Only one handler per name is supported; registering the same name twice replaces the previous handler.

  Parameters

  • name: string

    The invoke name (e.g. "adaptiveCard/action", "task/fetch").

  • handler: InvokeActivityHandler

    Async function that returns an InvokeResponse.

  Returns this

  this for method chaining.

processAsync

• processAsync(req: IncomingMessage, res: ServerResponse): Promise<void>

  Process an incoming HTTP request (Express / Node.js http.Server).

  Reads the request body, validates the activity, runs the middleware pipeline, and writes a 200 {} response. For invoke activities, writes the InvokeResponse returned by the registered handler instead. Writes 413 for oversized bodies and 500 on unhandled errors.

  Parameters

  • req: IncomingMessage

    Node.js incoming HTTP request.

  • res: ServerResponse

    Node.js server response to write the result to.

  Returns Promise<void>

  Throws

  Never — errors are caught and written to res as HTTP status codes.

processBody

• processBody(body: string): Promise<InvokeResponse | undefined>

  Process a raw JSON request body without touching the HTTP layer.

  Use this with frameworks that manage their own response lifecycle (e.g. Hono), where writing to ServerResponse directly would cause issues.

  For invoke activities, the returned InvokeResponse must be written to the HTTP response by the caller.

  Parameters

  • body: string

    Raw JSON string from the HTTP request body.

  Returns Promise<InvokeResponse | undefined>

  The InvokeResponse for invoke activities, or undefined for all other activity types.

  Throws

  If the body is not valid JSON or fails activity validation.

  Throws

  If the activity's serviceUrl is not on the allowlist.

  Throws

  If an activity handler throws during processing.

sendActivityAsync

• sendActivityAsync(
      serviceUrl: string,
      conversationId: string,
      activity: Partial<CoreActivity>,
  ): Promise<ResourceResponse | undefined>

  Proactively send an activity to a conversation.

  Parameters

  • serviceUrl: string

    Bot Service service URL.

  • conversationId: string

    Target conversation ID.

  • activity: Partial<CoreActivity>

    CoreActivity payload to send.

  Returns Promise<ResourceResponse | undefined>

  The ResourceResponse containing the new activity ID, or undefined.