ConversationBot class

  • Reference
Package:
@microsoft/teamsfx

Provide utilities for bot conversation, including:

  • handle command and response.
  • send notification to varies targets (e.g., member, group, channel).

Example

For command and response, you can register your commands through the constructor, or use the registerCommand and registerCommands API to add commands later.

import { BotBuilderCloudAdapter } from "@microsoft/teamsfx";
import ConversationBot = BotBuilderCloudAdapter.ConversationBot;

// register through constructor
const conversationBot = new ConversationBot({
  command: {
    enabled: true,
    commands: [ new HelloWorldCommandHandler() ],
  },
});

// register through `register*` API
conversationBot.command.registerCommand(new HelpCommandHandler());

For notification, you can enable notification at initialization, then send notifications at any time.

import { BotBuilderCloudAdapter } from "@microsoft/teamsfx";
import ConversationBot = BotBuilderCloudAdapter.ConversationBot;

// enable through constructor
const conversationBot = new ConversationBot({
  notification: {
    enabled: true,
  },
});

// get all bot installations and send message
for (const target of await conversationBot.notification.installations()) {
  await target.sendMessage("Hello Notification");
}

// alternative - send message to all members
for (const target of await conversationBot.notification.installations()) {
  for (const member of await target.members()) {
    await member.sendMessage("Hello Notification");
  }
}

Remarks

Set adapter in ConversationOptions to use your own bot adapter.

For command and response, ensure each command should ONLY be registered with the command once, otherwise it'll cause unexpected behavior if you register the same command more than once.

For notification, set notification.storage in ConversationOptions to use your own storage implementation.

Constructors

ConversationBot(ConversationOptions_2)

Create new instance of the ConversationBot.

Properties

adapter

The bot adapter.
cardAction

The action handler used for adaptive card universal actions.
command

The entrypoint of command and response.
notification

The entrypoint of notification.

Methods

requestHandler(Request<Record<string, unknown>, Record<string, undefined | string | string[]>>, Response, (context: TurnContext) => Promise<any>)

The request handler to integrate with web request.

Example

For example, to use with Restify:

// The default/empty behavior
server.use(restify.plugins.bodyParser());
server.post("api/messages", conversationBot.requestHandler);

// Or, add your own logic
server.use(restify.plugins.bodyParser());
server.post("api/messages", async (req, res) => {
  await conversationBot.requestHandler(req, res, async (context) => {
    // your-own-context-logic
  });
});

Constructor Details

ConversationBot(ConversationOptions_2)

Create new instance of the ConversationBot.

new ConversationBot(options: ConversationOptions_2)

Parameters

options
ConversationOptions

The initialize options.

Remarks

It's recommended to create your own adapter and storage for production environment instead of the default one.

Property Details

adapter

The bot adapter.

adapter: CloudAdapter

Property Value

CloudAdapter

cardAction

The action handler used for adaptive card universal actions.

cardAction?: CardActionBot_2

Property Value

CardActionBot

command

The entrypoint of command and response.

command?: CommandBot_2

Property Value

CommandBot

notification

The entrypoint of notification.

notification?: NotificationBot_2

Property Value

NotificationBot

Method Details

requestHandler(Request<Record<string, unknown>, Record<string, undefined | string | string[]>>, Response, (context: TurnContext) => Promise<any>)

The request handler to integrate with web request.

Example

For example, to use with Restify:

// The default/empty behavior
server.use(restify.plugins.bodyParser());
server.post("api/messages", conversationBot.requestHandler);

// Or, add your own logic
server.use(restify.plugins.bodyParser());
server.post("api/messages", async (req, res) => {
  await conversationBot.requestHandler(req, res, async (context) => {
    // your-own-context-logic
  });
});

function requestHandler(req: Request<Record<string, unknown>, Record<string, undefined | string | string[]>>, res: Response, logic?: (context: TurnContext) => Promise<any>): Promise<void>

Parameters

req

Request<Record<string, unknown>, Record<string, undefined | string | string[]>>

An incoming HTTP Request.

res

Response

The corresponding HTTP Response.

logic

(context: TurnContext) => Promise<any>

The additional function to handle bot context.

Returns

Promise<void>