Introduction

In the previous article "creating-an-interactive-chatbot-with-ms-teams-and-the-xqi-engine/" we played around with chatbots. A fun and often useful feature with a lot of possibilities. But when you use a bot, the user in Ms Teams must always initiate the conversation. It lead us to wonder about bots informing Teams users about "events" that happen in a company (you can imagine anything here for which you would generate notifications with emails, SMS, WhatsApp or any other channel you have available). We also wondered how it would be more user friendly if the the user did not have to install the app first & start a conversation in order to receive notifications, but, that all of this would be handled automatically by our engine.

We based our solution on this (very recent) article from Tom Morgan: https://blog.thoughtstuff.co.uk/2020/07/its-now-mu.... In a nutshell: using new access rights, you can automatically install an Teams App and start a conversation with the user.

We thought of a simple but useful usecase to try this out. Many companies have server infrastructure. And this infrastructure is often monitored by sensor data. In our example, the temperature in a datacenter is monitored. The value is stored in a time series database (TSDB). The XQi Engine acts as an alarming tool. The datacenter temperature is polled from the TSDB and when a threshold is met, a user in Teams is notified of this event. The user does not need to interact with the app or bot before being able to receive messages from it.

Configuring the XQi Engine

We require 2 clients for MS Graph:

• Microsoft Bot API: just like in the previous article, a connection to the Bot API is required
• Ms Graph Beta: the new permissions & methods used to proactively install apps & initiate conversations are part of the MS Graph Beta API.

In our example we are making use of InfluxDB to store the sensor data for the simple reason it's easy to setup (there is a docker image), it's easy to insert data & you can query it via a http client. In the engine configuration, we simply need to add an httpClient & a timer that triggers it:

We have handled timers & httpclients many times before. So we are not going to dive deeper into this again in this article.

Pushing an app to an Ms Teams User

In our setup, the XQi Engine is constantly monitoring the stored temperature. When the threshold is met, one or multiple Teams users must be notified. These users could be stored in a SQL Database or in a MongoDB document store (there are many options in the XQi Engine to store data), but this is not within the scope of this article. So for the sake of the example, we have only one Teams user id and it is "hard coded" in the script.

We must first check if the user already has the app installed. We can use the Ms Graph Beta API for this:

This API call is documented here: https://docs.microsoft.com/en-us/graph/api/user-list-teamsappinstallation?view=graph-rest-beta&tabs=http

According to this, the response should contain something like this:

The teamsAppId is known when the app is made available in Ms Teams, so it is something we can use to filter through the response (the displayName field could be used as well, but might be subject to change). So this will determine if the app is installed for this user.

When the app is not installed yet, we can use the beta API again to publish it to this user. Documentation for the API call can be found here: https://docs.microsoft.com/en-us/graph/api/user-add-teamsappinstallation?view=graph-rest-beta&tabs=http

When the MS Graph Beta API returns the result & the callback method is triggered from the engine, we can check the Response Status Code:

If the status code is 201 (created), the app was installed.

Initiating the Conversation in Ms Teams

When an App is installed for the first time, Teams immediately initiates a first conversation automatically. As we know from the chatbot with Teams article, this triggers a webhook with an Activity object. This time, the type of the Activity is set to "conversationUpdate". If we have the httpServer endpoint (triggered by the webhook) setup correctly, we will receive this Activity and we can use this event (and the fields inside) to send an initial message to the user in Ms Teams:

We have received all necessary info to post notifications to the user. We also need this information later if we want to send follow up notifications. So it's best to store this information in localStorage (or a connected database or file or…).

It is also important to note that the conversationUpdate message is only sent the very first time an App is installed. If, for instance, the user has decided to uninstall the App from his/her Ms Teams instance, the conversation is not deleted & will be reused when the app is re-installed. The conversationUpdate Activity message will not be triggered again! It is therefore vital to keep track of the user id & conversation information. As far as we could test it, there seems to be no way (yet) to retrieve it afterwards.

Once everything is in place, the XQi Engine is able to send messages to an Teams user for any event that is reported to the engine. In our example, we start receiving temperature notifications: