/teams-ai-chat-bot

An AI Chat Bot for Microsoft Teams that invokes various backing AI services

Primary LanguageTypeScript

Overview of the Command bot template

This template showcases an app that responds to chat commands by displaying UI using an Adaptive Card. This enables your users to type in simple messages in Teams and your application can provide an appropriate response based on the contents of the message.

The app template is built using the TeamsFx SDK, which provides a simple set of functions over the Microsoft Bot Framework to implement this scenario.

Get Started with the Command bot

Prerequisites

To run the command bot template in your local dev machine, you will need:

Note

Your app can be installed into a team, or a group chat, or as personal app. See Installation and Uninstallation.

  1. First, select the Teams Toolkit icon on the left in the VS Code toolbar.
  2. In the Account section, sign in with your Microsoft 365 account if you haven't already.
  3. Press F5 to start debugging which launches your app in Teams using a web browser. Select Debug (Edge) or Debug (Chrome).
  4. When Teams launches in the browser, select the Add button in the dialog to install your app to Teams.
  5. Type or select helloWorld in the chat to send it to your bot - this is the default command provided by the template.

The bot will respond to the helloWorld command with an Adaptive Card:

Command and Response in Teams

What's included in the template

Folder Contents
.fx Project level settings, configurations, and environment information
.vscode VSCode files for local debug
bot The source code for the command and response Teams application
templates Templates for the Teams application manifest and for provisioning Azure resources

The following files can be customized and demonstrate an example implementation to get you started.

File Contents
src/index.ts Application entry point and restify handlers for command and response
src/adaptiveCards/helloworldCommand.json A generated Adaptive Card that is sent to Teams
src/helloworldCommandHandler.ts The business logic to handle a command
src/cardModels.ts The default Adaptive Card data model

Extend the command bot template with more commands and responses

Follow the steps below to add more commands and responses to extend the command bot:

  1. Step 1: Add a command definition in manifest
  2. Step 2: Respond with an Adaptive Card
  3. Step 3: Handle the command
  4. Step 4: Register the new command

Step 1: Add a command definition in manifest

You can edit the manifest template file templates\appPackage\manifest.template.json to include definitions of a doSomething command with its title and description in the commands array:

"commandLists": [
  {
    "commands": [
        {
            "title": "helloWorld",
            "description": "A helloworld command to send a welcome message"
        },
        {
            "title": "doSomething",
            "description": "A sample do something command"
        }
    ]
  }
]

Step 2: Respond with an Adaptive Card

To respond with an Adaptive Card, define your card in its JSON format. Create a new file src/adaptiveCards/doSomethingCommandResponse.json:

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "size": "Medium",
            "weight": "Bolder",
            "text": "Your doSomething Command is added!"
        },
        {
            "type": "TextBlock",
            "text": "Congratulations! Your hello world bot now includes a new DoSomething Command",
            "wrap": true
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.4"
}

You can use the Adaptive Card Designer to help visually design your Adaptive Card UI.

Please note:

  • Respond with an Adaptive Card is optional, you can simply respond with plain texts.
  • If you'd like to send adaptive card with dynamic data, please refer to this document.

Step 3: Handle the command

The TeamsFx SDK provides a convenient class, TeamsFxBotCommandHandler, to handle when an command is triggered from Teams conversation message. Create a new file, bot/src/doSomethingCommandHandler.ts:

import { Activity, CardFactory, MessageFactory, TurnContext } from "botbuilder";
import { CommandMessage, TeamsFxBotCommandHandler, TriggerPatterns, MessageBuilder, } from "@microsoft/teamsfx";
import doSomethingCard  from "./adaptiveCards/doSomethingCommandResponse.json";
import { AdaptiveCards } from "@microsoft/adaptivecards-tools";
import { CardData } from "./cardModels";

export class DoSomethingCommandHandler implements TeamsFxBotCommandHandler {
    triggerPatterns: TriggerPatterns = "doSomething";

    async handleCommandReceived(
        context: TurnContext,
        message: CommandMessage
    ): Promise<string | Partial<Activity>> {
        // verify the command arguments which are received from the client if needed.
        console.log(`Bot received message: ${message.text}`);

        const cardData: CardData = {
          title: "doSomething command is added",
          body: "Congratulations! You have responded to doSomething command",
        };

        const cardJson = AdaptiveCards.declare(doSomethingCard).render(cardData);
        return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
    }    
}

You can customize what the command does here, including calling an API, process data, etc.

Step 4: Register the new command

Each new command needs to be configured in the ConversationBot, which powers the conversational flow of the command bot template. Navigate to the bot/src/internal/initialize.ts file and update the commands array of the command property:

import { HelloWorldCommandHandler } from "../helloworldCommandHandler";
import { DoSomethingCommandHandler } from "../doSomethingCommandHandler";
import { ConversationBot } from "@microsoft/teamsfx";

const commandBot = new ConversationBot({
    //...
    command: {
        enabled: true,
        commands: [ 
            new HelloWorldCommandHandler(), 
            new DoSomethingCommandHandler() ],
    },
});

Congratulations, you've just created your own command! To learn more about the command bot template, visit the documentation on GitHub. You can find more scenarios like:

Extend command bot with other bot scenarios

Command bot is compatible with other bot scenarios like notification bot and workflow bot.

Add notifications to your command bot

The notification feature adds the ability for your application to send Adaptive Cards in response to external events. Follow the steps here to add the notification feature to your command bot. Refer the notification document for more information.

Add workflow to your command bot

Adaptive cards can be updated on user action to allow user progress through a series of cards that require user input. Developers can define actions and use a bot to return an Adaptive Cards in response to user action. This can be chained into sequential workflows. Follow the steps here to add workflow feature to your command bot. Refer the workflow document for more information.

Additional information and references