Blog

SharePoint Framework (SPFx): Microsoft BOT framework integration

By Pallav Mathur on 11/18/19

Download / Source code

SPFX web part : https://github.com/get2pallav/BT/tree/develop

BOT Code : https://github.com/get2pallav/BOT_FM

Introduction

The Microsoft Bot Framework provides just what we need to build and connect intelligent bots that interact naturally wherever users are talking, from text/sms to Skype, Slack, Office 365 mail and other popular services. Within the Bot Framework, the Bot Connector service enables our bot to exchange messages with users on channels that are configured in the Bot Framework Portal and the Bot State service enables bot to store and retrieve state data that is related to the conversations that our bot conducts using the Bot Connector. 

Here we will explore how to include Microsoft BOT Framework and use its capabilities with SharePoint using SPFx webpart. This will be a simple BOT which will using SharePoint context to fetch user information and interact with the user in natural language.  

BOT Registration

The first step is to register BOT channel with Azure. After login onto Azure portal, create a new resource of type “BOT Channel Registration” and provide all default settings. Follow steps in "BOT Channel Registration" for channel registration.

For Back channel communication between SPFx web part and BOT we will use "Direct Line". Follow the specific link on how to “Connect a Bot to Direct Line

  • App ID: Application ID
  • App secret: Application secret
  • Direct Line secret: Used by SPFX web part to communicate with BOT

SPFx Implementation

Setup SPFx environment for development, this web part will user current user's context to perform SharePoint search. 

Include "context" in BOT component properties

SharePoint BOT integration

 

Also include following npm libraries to use Bot framework webchat and sp-pnp-js

SharePoint NPM libraries

More details on botframework-webchat can be found here.

BOT component code will be as follows

 

SharePoint BOT component code

 

Above code with registering using Direct Line to communicate with BOT and pass user basic information using “postActivity” for initial Greeting message. It also subscribes for activities raised by BOT. If activity raised by BOT is of type event and of name “search”, we will perform sp-pnp-js search to get results. These results will be then passed as a simple array to BOT which will present in Hero element format.

Setup BOT using Node.js 

Follow steps to “Create a bot with the Bot Builder SDK for Node.js

”. Also install ngrok.exe
which will be used to expose localhost URL for Azure. 
For more information on how to expose localhost URL to Azure BOT registration, check this link.

BOT Implementation 

Our conversation will use BOT's dialog and define conversation steps in waterfall structure. More on BOT dialog/message/activities/Back channel can be found here.
One important concept to understand here is "session address”, it determines where to send back the reply from BOT. In our example, we are using two separate ways of communication:

  • Session direct message which will prompt the user on Chat window
  • Back channel communication with SPFx web part using events

For a direct messages on Chat window, we keep the address information in “baseAddress” variable which will get populated in starting of a new conversation.

SharePoint BOT Integration

BOT code

SharePoint BOT Code
SharePoint BOT Code Integration

There are three dialog sections in the above code.

Entry dialog for BOT is "mainMenu" dialog which will welcome user and 'Search a Document' options. Currently, for demo purpose it has only one option, on selection of "Search a Document" - it will launch "document" dialog. "Document" dialog will fire an event to SPFx web part which will run the search query in user's context and return results to BOT in a simple array object.

BOT is also listening for any message which matches 'showresults'. As, after the search, SPFx will return results with a message text as 'showresults' and this BOT will display those results in Hero element.

Check the video for overall functionality.