Home>
Software Development>
Understanding Message Flow in Microsoft Teams Bot Development.

Understanding Message Flow in Microsoft Teams Bot Development.

Published April 1, 2024 in Software Development

In this post, I share my knowledge and experience in developing a bot application for Teams using the Microsoft Teams Bot Framework. I will outline the key components involved in developing a bot application and explain how communication securely flows between an end user and the bot.

First, let’s explore the key components involved in developing a Teams bot application.

Key Components of Bot Application Development

Bot: A bot is an application that enables users to interact and chat, often using natural language. In its more primitive form, a bot can simply respond to specific commands entered by the user. The bot, a web application, receives user inputs through Teams. For example, in an app I’m developing, the bot is an ASP.NET Core application hosted on Azure App Service. However, you can develop the app in your preferred language, including Python, Java, or JavaScript. Keep in mind that Microsoft provides SDKs for selected languages only, including C# and JavaScript. Although there was an SDK for Java, it has been discontinued.

Channel: A channel is a mechanism through which messages are sent and received. The Microsoft Bot Framework supports various channels, including Microsoft Teams, Facebook, Skype, and Outlook, among others.

Bot Connector Service: The Bot Connector Service acts as an intermediary, facilitating message exchange between a bot and a channel. One key function it performs is authorization, ensuring that the channel has the necessary permissions to communicate with the service. This involves validating the request’s access token. If the request is valid, the Bot Connector Service forwards the message to the bot; otherwise, it returns a 403 unauthorized error code to the channel. For example, when attempting to send a message from Microsoft Teams to my bot application, I encountered 403 error messages without any indication of the error or the request reaching the application. This occurred because the Bot Connector Service intercepted and blocked the request due to a permissions issue.

Another critical role of the Bot Connector Service is message transformation. Since Microsoft Bot Framework supports various channels, it ensures that outgoing messages from the bot align with the receiving channel’s schema, and incoming messages to the bot conform to the Bot Framework Activity schema. This normalization process guarantees seamless communication across different platforms.

Microsoft Bot Framework: The Microsoft Bot Framework is an umbrella term that encompasses multiple services and SDKs. For instance, Microsoft offers SDKs for various programming languages, including JavaScript, Java, and C#.

Developing a Teams bot requires you to register an application in Microsoft Entra ID to obtain a client ID and secret. These credentials allow the bot to authenticate its identity when sending requests to Teams.

In addition to app registration, you must create an Azure Bot resource and link it with your app registration. This resource serves as an abstraction layer, enabling you to register and configure your bot within the Microsoft Bot Framework. Through the Azure Bot resource, you can specify a URL for Teams or other channels to communicate with your bot. Furthermore, the Azure Bot resource offers an interface for setting up OAuth authentication, which is necessary for user authentication and access token acquisition.

Having explored the components and services involved in bot development, let’s now examine how messages flow between an end user and a bot, and vice versa.

Understanding the Message Flow: From End User to Bot and Back

When a user sends a message to the bot through the Microsoft Teams channel, Teams does not directly forward the message to the bot. Instead, it communicates with the Bot Connector Service. This service performs necessary message transformations to ensure compatibility with the Microsoft Bot Framework schema and validates that Teams has the appropriate permissions to access the bot before forwarding the message. Before Teams can relay a message from the bot to a user, it must authenticate and obtain a token to call the Bot Connector Service. This service then validates the token and forwards the message accordingly. The process is mirrored when the bot initiates a message to a user, requiring a token to communicate with the Bot Connector Service, which validates the token and forwards the message to Teams. The Bot Connector Service is important for managing authentication, ensuring both Teams and the bot have the necessary permissions to communicate. It also handles message transformations, ensuring that messages sent to Teams are in the correct format and that incoming messages to the bot conform to the Bot Framework Schema.

The diagrams below depict my understanding of how the messages flow securely between the end user, Teams, and a bot. In the diagrams, the bot named EMI is an ASP.NET core web API application.