Working with Teams in the Microsoft Graph

It’s not surprising that Teams has become one of the fastest growing applications in Microsoft 365. Lockdowns and work-from-home policies during the current pandemic have pushed collaboration tools such as Teams to the fore, making them the replacement for all the interactions in the modern office. Apps are now where people go to work, to chat, and to share information about tasks and projects, escalating from chat, to voice calls, to video meetings as necessary.

Teams is more than a conferencing and collaboration space. Like much of the Office suite, it’s part of the Microsoft Graph, a set of APIs that gives access to individual and company data stored in the Microsoft 365 cloud. The Microsoft Graph is more than a storage layer, it’s a way to interact directly with the Office application suite and build new applications that can use the Microsoft 365 platform.

Using the Microsoft Graph to automate Teams

Using the Microsoft Graph, we can write code that interacts directly with Teams, programmatically creating collaboration spaces and injecting content where necessary. That approach lets us do things such as linking Teams into IT management tools, automatically generating a virtual team in response to an incident, populating it with the appropriate content from systems management tools, and closing the team and archiving any chat spaces or shared content when the incident ends.

Automating Teams like this is more than creating bots. It builds on existing workflows by providing a place to capture content and information that might otherwise be lost in person-to-person chats. We often lose potentially vital information in informal communication channels, where it’s forgotten before writing post-action reports and post-mortem analysis. Automating interactions can help ensure that remote workers know that a task is waiting for them and allows you to track that tasks are being completed.

Working with the Teams Graph APIs

Using the Graph to create a Team is easy enough, using the Microsoft 365 create_group operation. The Microsoft 365 Graph APIs for Teams are all RESTful, and you can interact with them using SDKs or via your own HTTP interactions. Creating a new group requires a single POST operation, setting the group name, whether it’s public or private, and whether it’s available in Outlook mail, along with configuring descriptions and nicknames.

Members need to be added by their Graph ID. It requires a separate query to get those IDs before you construct the REST POST that creates the team. As part of the query, you also need to define at least two team members as owners, with admin rights for the team. You can only add up to 20 members when creating a group; any additional members will need to be added using the add_member API, with at least a one-second delay between each addition.

The API call returns the group ID, which is needed for any graph interactions with the group. Once you have a group in place, which can take some time, you can quickly convert that group into a team using a single POST action, calling a Graph API to manage the conversion. Again you’re presented with an ID, this time for your new team. Once you’ve finished using a temporary team, your Teams admin can remove it manually or using the Graph APIs.

Using Graph Explorer to design queries

It’s worth using Microsoft’s Graph Explorer service to test out your REST queries before you implement them. Graph Explorer is a useful tool that works with the current release API and any beta APIs that you’re considering using. It shows both the structure of a call and any responses generated by the API. By default, the Graph Explorer works against a sample tenant, though you can log in and use it against your own Microsoft Graph data.

The Microsoft Graph API covers a lot more than Teams, so your code can work with SharePoint to update libraries, manage e-mail, and work with files in OneDrive. For example, a support app that automatically creates a response team can alert team members by e-mail, stand up a SharePoint instance for creating any documentation that’s needed, place logs and other important files in OneDrive, and then attach them all to tabs in Teams, ready for use.

Manage with the Graph, interact with webhooks

Microsoft recommends mixing Graph calls with Teams webhooks for your applications. The Graph API is best for handling low-level graph objects, such as users and groups. Once you have those in place, you can then use the API to query your Teams instance for content. Interactions with a team through chat and through adaptive cards are best carried via webhooks, using asynchronous calls in your applications. As Teams interactions are based on events and messages, the combination of programmatic team management through Teams’ Graph API and webhook-based events should give you the flexibility to build, run, and use dynamic teams as and when needed.

Teams’ Graph integration is two-way; apps built to run inside Teams can work with Graph APIs, triggering actions in other Office applications or even out into line-of-business platforms such as Microsoft’s Dynamics 365 and the Common Data Service. Work doesn’t have to be big, complex tasks that require reams of documents or all-hands meetings, with much of what we do in the office (no matter our roles) broken down into small interactions making up what’s now known as microwork.

Microwork is one of the sweet spots for applications such as Teams, and integrating with the Microsoft Graph opens up using it as an endpoint for a wide selection of different applications, especially when tasks are surfaced as Adaptive Cards inside user’s notifications. There’s no need for an application to expose itself in Teams directly, so users aren’t flipped between user experiences. With changed work environments causing significant stress, keeping cognitive overload to a minimum is important, and surfacing tasks and information inside the familiar Teams environment alongside social interactions is a plus.

You’re not limited to using low-level code with Teams. At Build 2020 Microsoft announced that it would extend its Power Automate integrations to Teams, giving you a low-code route to adding Teams as an endpoint to business process automation. With Teams offering both structured and ad-hoc collaboration, it needs a way to deliver apps that support both ways of working: a model that works well with centralized Microsoft Graph-based applications and team and workgroup automation from the Power Platform.