This story will show you the step by step instruction that you can take to build your first chatbot and incorporate it as a web part in SharePoint using SPFx.
1. Create an echo bot and start echo bot
You can follow the official Microsoft guide on creating a chatbot with Microsoft Bot Framework v4 here
Create an echo bot using the following commands
mkdir TutorialBot
cd TutorialBot
npm install -g npm
npm install -g yo generator-botbuilder
yo botbuilder
Choose the following options when prompted:
- Enter a name for your bot. (tutorial-chat-bot)
- Enter a description. (Demonstrate the core capabilities of the Microsoft Bot Framework)
- Choose the language for your bot. (JavaScript)
- Choose the template to use. (Echo Bot — https://aka.ms/generator-botbuilder-templates)
Start the echo bot locally by running the following:
cd tutorial-chat-bot
npm start
2. Test your bot on Bot Framework Emulator
- Start the Bot Framework Emulator. You can download them here: Bot Framework Emulator for Mac or Bot Framework Emulator for Windows
- Click on Create a new bot configuration, enter
Tutorial Bot
andhttp://localhost:3978/api/messages
for Bot name and Endpoint URL respectively. - Click on Save and connect
- Send a message to your bot and it will echo back the same message.
3. Upload Bot to Azure App Service
Connect to Azure and set your subscription using the command below:
az login
az account set --subscription "<azure-subscription>"
Create an App Registration on your Azure AD with a name and a password. The password must be at least 16 characters long, contain at least 1 upper or lower case alphabetical character, and contain at least 1 special character. Replace <botname>
and <16characterpassword>
with your own bot name and password respectively.
az ad app create --display-name "<botname>" --password "<16characterpassword>" --available-to-other-tenants
Copy the appId
that is generated from the output.
Create a new resource group together with a new app service and app service plan. Replace <app-id-from-previous-step>
with the value from the previous step. Change all the other relevant fields with your own values. Use az account list-locations
if you are not sure of the exact location name to use. cd
to the project root folder and run the command below. This command will take a few minutes to complete.
az deployment create --template-file "<path-to-template-with-new-rg.json" --location <region-location-name> --parameters appId="<app-id-from-previous-step>" appSecret="<password-from-previous-step>" botId="<id or bot-app-service-name>" botSku=F0 newAppServicePlanName="<new-service-plan-name>" newWebAppName="<bot-app-service-name>" groupName="<new-group-name>" groupLocation="<region-location-name>" newAppServicePlanLocation="<region-location-name>" --name "<bot-app-service-name>"
Prepare your bot to upload to App Service using the command below. This creates a web.config
file.
az bot prepare-deploy --code-dir "." --lang Javascript
Zip up all your files. This is a little tricky, make sure not to zip the parent folder, but to go into the root folder and select all the files and select Compress all files. You can rename the zip folder to code.zip
which will be used in the next step.
Upload your code to the newly created app service with the command below. This step may take a few minutes. Replace <resource-group-name>
and <app-service-name>
with your previously entered resource group name and app service name respectively.
az webapp deployment source config-zip --resource-group "<resource-group-name>" --name "<app-service-name>" --src "code.zip"
Test your bot on Bot Channels Registration. Open Azure portal and click into the resource group that we just created. Click on Test in Web Chat to test. The expected behavior should be the same as when we are testing on the Bot Framework Emulator.
4. Create Direct Line connection for the Bot Channels Registration
Click on Channels and then click on the Direct Line icon to create a Direct Line channel for your bot.
Click on Show and copy the Direct Line secret to a notepad. We will use this secret later in your SPFx web part.
5. Create SPFx Custom Web Part and Modify the Code
You can follow the official Microsoft guide on creating a SPFx web part here. You may also need to look at this guide to set up your environment for SPFx if you have not already done so.
Create a new web part project with the command below:
yo @microsoft/sharepoint
When prompted:
- Type in your preferred web part name as your solution name, and then select Enter.
- Select SharePoint Online only (latest), and select Enter.
- Select Use the current folder for where to place the files.
- Select N to allow the solution to be deployed to all sites immediately.
- Select N on the question if the solution contains unique permissions.
- Select WebPart as the client-side component type to be created.
The next set of prompts ask for specific information about your web part:
- Type in your preferred web part name as your web part name, and then select Enter.
- Type in your preferred description as your web part description, and then select Enter.
- Select React as the framework you would like to use, and then select Enter.
Install the following modules for your bot:
npm install --save botframework-webchat
npm install --save botframework-directlinejs
Head over to the web part component Props file and add in the context.
import { IWebPartContext } from '@microsoft/sp-webpart-base';export interface ITutorialWebPartProps {
description: string;
context: IWebPartContext;
}
Head over to the web part file and add the context in the render method.
export default class TutorialWebPartWebPart extends BaseClientSideWebPart <ITutorialWebPartWebPartProps> { public render(): void {
const element: React.ReactElement<ITutorialWebPartProps> = React.createElement(
TutorialWebPart,
{
description: this.properties.description,
context: this.context
}
); ReactDom.render(element, this.domElement);
}
Head over to the web part component file and paste the following code. Replace <DIRECT LINE SECRET>
with the secret that you copied from before. Rename the class name to your own web part class.
import * as React from 'react';
import styles from './TutorialWebPart.module.scss';
import { ITutorialWebPartProps } from './ITutorialWebPartProps';
import ReactWebChat from 'botframework-webchat';
import { DirectLine } from 'botframework-directlinejs';export interface IBotFrameworkChatv4State {
directLine: any;
}export default class TutorialWebPart extends React.Component<ITutorialWebPartProps, IBotFrameworkChatv4State> {
constructor(props) {
super(props);
this.state = {
directLine: new DirectLine({
secret: "<DIRECT LINE SECRET>"
}),
};
}
public render(): React.ReactElement<ITutorialWebPartProps> {
return (
<div style={{ height: 700 }}>
<ReactWebChat directLine={this.state.directLine} />
</div>
);
}
}
6. Test on SharePoint WorkBench
Run gulp serve
and you should be able to test your chatbot as a web part. The expected behavior should be the same as that of the Bot Framework Emulator earlier.
Follow the official documentation from Microsoft to deploy your chatbot web part to your SharePoint site.
This is a very basic echo bot, but we can add in more functionality and make it more intelligent and Azure has this QnA Maker feature in its Cognitive Services offering that we can make use of. Hope this post helped!