Build a MS Teams Bot with RASA Open Source

The possibility to build and add your own apps is turning Microsoft Teams into a central hub for employee productivity in a unified suite of tools. Observing the rise of virtual assistants to boost employee productivity, I was wondering how the Rasa Open Source Framework could be leveraged to create a smart Assistant based connecting with Microsoft Teams.

Although Rasa officially supports the Microsoft Bot Framework which allows you create a Bot in your Microsoft Teams organization, I was not able to find any documentation in the web on how to properly connect Rasa to Microsoft Teams and use buttons or other rich responses with a Teams Chatbot. Hence, this article is intended to shed light on a quick setup for creating an MS Teams chatbot with Rasa Open Source.

This article will guide you to your own Microsoft Teams chatbot in 5 steps:

  1. Setup a Microsoft Teams Developer Sandbox
  2. Prepare a Rasa Open Source test environment on your local machine
  3. Setup a Microsoft Bot Channels Registration
  4. Add rich responses to your chatbot using Rasa custom actions
  5. Final test in Microsoft Teams

Please Note: The approach described in this post ist intended to give you a high-level understanding of how Rasa Open Source can be leveraged to integrate with Microsoft Teams. Hence, the approach targets on setting up a simple development environment with no focus on security or resilience. If you want to setup a production-grade Rasa deployment, please refer to the official sources. The code shown in this article is also only used to give a basic understanding of the underlying principles and is held as simple as possible, and not intended to provide best practices in Rasa or Python development.

1. Setup a Microsoft Teams Developer Sandbox

In order to be able to register your Teams you need to have admin permissions on your Microsoft Teams organization. As for most of the readers this will usually not be the case, we will need to create a free sandbox using the Microsoft 365 Developer program first to have our own Microsoft Teams enabled organization. This will allow us to have our own Microsoft Teams organization with access to the Admin center and registering our own Teams applications.

To do this, simply sign up with the Microsoft 365 Developer program and follow the steps of the signup process. You will be provisioned with a renewable, 90 day Microsoft E5 Developer license that contains all you need to follow this tutorial.

2. Prepare a Rasa Open Source test environment on your local machine

Rasa Open Source is a python-based chatbot framework that is recognized as a „Cool Vendor in Conversational AI“ by Gartner. In order to set it up, we will need:

  • Python 3.6 or 3.7
  • ideally a virtual environment
  • Rasa Open Source
  • ngrok (to make your local machine accessible for MS Teams)

For the python environment we will use miniconda in this tutorial, but you can also go for a default python environment and venv to setup your virtual environment. I first create a project folder and open the Anaconda prompt which has been installed with the miniconda default installation. In the promot we cd into my project folder and create a new conda environment with Python 3.7 which I name „rasa-teams“:

cd teams-tutorial
conda create -n rasa-teams python=3.7

When the environment has been created, we activate it and install the Rasa Open Sourceusing pip as described in the Rasa documentation:

conda activate rasa-teams
pip3 install rasa

Once installed, we create a new rasa sample project:

rasa init

When you are asked to train the initial model, confirm with „y“ for yes. Afterwards you can confirm with yes again and directly speak to the newly created example bot. Both activities can also be performed afterwars using the „rasa train“ and „rasa shell“ commands from your commandline within your project directory (see Rasa Open Source documentation)

Talking to the example bot that has been created by rasa init

As a next step, we will make the bot accessible via web. In order to do so, we need to install ngrok and create a free account.

the necessary steps and installers are provided in the dashboard after creating a free ngrok account

We download the executable and extract it into a directory of our choice (step 1) and connect it to our account using the „ngrok authtoken“ command (step 2).

3. Setup a Microsoft Bot Channels Registration

Before we continue to work with our Rasa bot, we need to register a Microsoft Bot Channel. In order to have a bot channel registered, you need to have an account with Microsoft Azure. If you do not yet have one, you may be eligible to sign up for a free account on Microsoft Azure.

The bot channel registration can be strated either by searching for „Bot Channels Registration“ in Azure Portal or by directly openin the Bot Channels Registration.

Select your bot handle (technical name), resource group (or create one), location, pricing tier (free F0 tier shall be enough for us). We can setup the messaging endpoint later and do not desperately need Application Insights (which causes additional costs) for our setup. Nevertheless, Application Insights may give valuable insights in a more productive deployment. The last step remains at „Auto create App ID and password“.

Microsoft Bot Channels Registration

After clicking on create, your bot channels registration is being created and you will be forwarded to a deployment overview page. If you can’t see it, click on „Deployment succeeded“ in your notifications on the top right in your Azure Portal page.

Deployment notification in Azure Portal

Before you go to your new resource, download the deployment details.

the deployment details contain the app id and secret

The deployment.json in the downloaded archive contains an „appId“ and „appSecret“.

Back in our project folder, we open the file credentials.yml and add the following three lines containing our „appId“ and „appSecret“ from the deployment details of our bot channel registration below the line defining the Rasa REST API channel. Afterwards save the credentials.yml file.

# This file contains the credentials for the voice & chat platforms
# which your bot is using.
# https://rasa.com/docs/rasa/messaging-and-voice-channels

rest:
#  # you don't need to provide anything here - this channel doesn't
#  # require any credentials

botframework:
  app_id: "<your appId>"
  app_password: "<your appSecret>"

#facebook:
#  verify: "<verify>"
#  secret: "<your secret>"
#  page-access-token: "<your page access token>"

Now you can start your Rasa server:

rasa run

Open a second terminal and cd into your ngrok directory and start ngrok with a binding on port 5005 on your local machine:

ngrok http 5005

ngrok will now provide you with a http and https-url that are pointing to your rasa server. We will need the https-url to connect Microsoft Bot Framework with our Rasa server.

Now go back to Azure portal, open the resource page of your bot channel registration and navigate to „Settings > Configuration“. As messaging endpoint, enter your individual ngrok URL followed by „/webhooks/botframework/webhook“.

Connecting your local Rasa server to Azure by setting up the messaging endpoint

Click on „Apply“ to confirm your changes and navigate to „Settings > Test in Web Chat“. You should now be able to chat with your bot. If not, have a look at the logs in your ngrok channel. In case you find a 404 Not Found Error, you may have an issue with your credentials.yml or your Rasa server was running before you made the changes to the credentials.yml and has not been restarted after your changes.

Testing the integration in Web Chat

Next go to „Settings > Channels“ and add a „Teams Channel“.

Choose „Microsoft Teams Commercial“ on the Messaging Tab
You don’t need to enable Calling

After saving and accepting the Microsoft Channel Publication Terms and Microsoft Privacy Statements, we go back to „Settings > Channels“. Below our channels list we click on „Get bot embed codes“ and extract the link to our bot channel from the href-tag in the html code provided.

The bot embed code provides us a link to our teams bot

When we open the link with the Teams Web-App or Desktop-App in our previously generated Microsoft 365 Developer Account organization, we should see a Teams chat with our bot and be able to talk to our local Rasa deployment.

After accessing our bot embed link, we are able to chat to our locally deployed bot

If you just need some basic chat capability in Teams, you can stop here and explore the Rasa framework or further configuration options of the bot channels registration (such as your bot’s name or logo).

When getting more hands-on with your teams bot, you will realize that normal chat messages and images will work, but buttons might not work out of the box. In order to get this solved, we need to setup Rasa Action Server and write a custom action that leverages Adaptive Cards to create rich responses in our MS Teams chatbot with Rasa Open Source.

4. Add rich responses to your chatbot using Rasa custom actions

In order to add rich responses for Microsoft Teams to our Rasa Open Source chatbot, we need provide a custom action that can create rich messages.

First, we open our project directory and create a new file „cards.py“ in the „actions“-folder:

from typing import Dict

class TeamsCards:
    """class to provide cards for MS Teams Channel"""
    def card(self, text) -> Dict:
        card = {
                    "attachments": [
                        {
                        "contentType": "application/vnd.microsoft.card.adaptive",
                        "content": {
                                "type": "AdaptiveCard",
                                "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                                "version": "1.2",
                                "body": [
                                    {
                                        "type": "TextBlock",
                                        "text": text,
                                        "wrap": "true"
                                    }
                                ]
                        }
                        }
                    ]
                    }
        return card

    def button(self, title, response)  -> Dict:
        button = {
                    "type": "Action.Submit",
                    "title": title,
                    "data": {
                        "msteams": {
                            "type": "imBack",
                            "value": response
                        }
                    }
                }
        return button

The class in cards.py allows us to create a simple rich message with a flexible number of buttons attached to it. If a button is clicked, a button-specific message is returned as a response to the bot.

Next, we register a custom action „action_continue“ that will generate a rich message that asks if you want to continue and adds two buttons yes and no. The action will be defined in „actions.py“ which can be found in our project’s action folder. The file contains some commented code which we adapt like below and save:

# This is a simple example for a custom action which utters "Hello World!"

from typing import Any, Text, Dict, List

from rasa_sdk import Action, Tracker
from rasa_sdk.executor import CollectingDispatcher

# import our cards
from actions.cards import TeamsCards

cards = TeamsCards()

class ActionContinue(Action):

    def name(self) -> Text:
        return "action_continue" # We rename the action name to action_continue

    def run(self, dispatcher: CollectingDispatcher,
            tracker: Tracker,
            domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:

        # Let's create a card with two buttons
        card = cards.card("Do you want to continue?")
        card["attachments"][0]["content"]["actions"] = [cards.button("Yes", "yes"), cards.button("No", "no")]

        # We provide "json_message" in utter_message() to allow adding custom json code
        dispatcher.utter_message(json_message=card)
        
        return []

In order to make our custom action accessible from a story, we need to register it in our domain model. In the root folder of our project, open „domain.yml“ and insert the following lines to the file (e.g. before session_config:):

actions:
- action_continue

We now adapt the happy path story from „stories.yml“ in the „data“-folder:

- story: happy path
  steps:
  - intent: greet
  - action: utter_greet
  - intent: mood_great
  - action: utter_happy
  - action: action_continue

To allow communication between the Rasa server and Rasa action server, we open endpoints.yml in the project’s root folder and uncomment the following two lines:

action_endpoint:
  url: "http://localhost:5055/webhook"

Now we can activate rasa action server by opening a new Anaconda Prompt, cd into our project folder, activate the conda environment we created in the beginning of the tutorial and start rasa action server:

conda activate rasa-teams
rasa run actions
Rasa action server indicates it is ready and our custom action is available

Finally, we stop our rasa server (using STRG + C) in our other Anaconda Prompt and restart it after re-training the model with „rasa train“:

rasa train
rasa run

We should now have three command line windows: one for rasa server, one for rasa action server, and one for our ngrok tunnel.

5. Final test in Microsoft Teams

Now we can chat with our bot again in Teams. In a happy-path discussion we should get a rich card with our text and buttons we have defined before. Clicking on the buttons will insert the respective responses that have been defined in the custom action.

„happy-path“-discussion with rich response

How does it work?

Our custom action is attaching an adaptive card to the communication with Microsoft Bot Framework. The payload generated by our „TeamsCards“-Class looks like below:

Custom JSON Payload added to the communication with Microsoft Bot Framework

The value of the within the „content“-key in the message attachment can be rendered with the Adaptive Cards Designer which also allows to generate previews of card payloads with an MS Teams design template.

Preview of our card payload in the Adaptive Cards Designer

More details on supported types of cards and their elements can be found in the Microsoft Teams Developer Platform Documentation.

Conclusion

Rasa Open Source allows the creation of Microsoft Teams Bots with rich experiences. There is a lot of information available on the web that helps to understand how Rasa and Teams are working. This article may be a first step to fill the gap on how to connect Rasa and Microsoft Teams. Though this article aims to provide a sufficient understanding on creating rich responses in Microsoft Teams, there are still many functionalities to be explored such as responses to card actions / forms or filesharing between Rasa bots and MS Teams….

I hope this article could help to get a first kickstart into integrating Teams and Rasa.