Similar to what we did here earlier with the novomind Messaging API and WhatsApp (check out https://xqting.wordpress.com/2020/07/29/integrating-the-novomind-messaging-api-with-xqi-engine-to-enable-whatsapp-communication/), we are now going to make a similar integration using Microsoft Teams.
With Teams we can create a chatbot by routing all incoming messages from users to a webhook. Using the XQi Engine & the HttpServer module, we can receive those messages (in fact, in an Teams context this is called an Activity). Using the Microsoft Bot Framework REST API (https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0), we can send an automated reply back to the user in Teams.
Creating a bot is already handled at length on the Microsoft site (for instance: https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams), so it will not be handled here. Another article on registering the engine for MS Graph is on this blog as well: https://xqting.wordpress.com/2020/06/24/registering-the-xqi-engine-in-microsoft-365-to-use-ms-graph-api/.
Configuring the HttpServer to receive messages from Teams
Our bot in Teams is using a webhook to route Activities to (like messages from users), so the first step is to receive those Activities. For this, we need to configure an HTTP Endpoint in the XQi Engine:
The webhook in the Bot config needs to be set to https://%5Bserver%5D/httpserver/teams/chat/bot. All Activities will be posted to this endpoint; there is only one endpoint. Let’s start with sending a message from Teams to the Chatbot & inspecting the content of the Activity:
The Activity is contained in the request body:
(some fields are removed for obvious reasons)
The type of the Activity is ‘message’. We can see the text, who is the sender, who is the receiver and what conversation it was posted in. All these properties we need to know to send a proper response.
Replying to a message in Teams
To formulate a proper reply to the Teams user, we’re going to make use of the Wolfram API again (like in the WhatsApp article). This API is already handled in there, so we wont do that again here.
We use the reply from the Wolfram API as text in the new Teams Activity of type ‘message’. But before we do that, we need to configure the MS Graph module in the XQi Engine:
Notice the base url is set to the value of the serviceUrl field of the initial incoming message. This represents the endpoint to reply to. The authorization server needs to be set to the Bot Framework OAuth token endpoint & the scope needs to be adjusted accordingly. Otherwise access to the API will be denied.
According to the Microsoft Bot Framework API documentation. The correct endpoint to use to send a message is v3/conversations/[conversationId]/activities. The conversationId can be taken from the original incoming message. Other fields that can be recuperated from our reply message are:
- recipient, to be used in the from field
After constructing the new Activity (representing a new message in an Teams Conversation), we use the msGraph module to post it.
A conversation with a Bot in Ms Teams may look like this:
The bot is replying to the human input with results from the Wolfram API.