Microsoft Teams integration

Microsoft Teams is a collaboration platform that integrates with Office 365.

There are two ways to build interactions between Microsoft Teams and Windmill: run code on Windmill by a Microsoft Teams command or use the Microsoft Teams API directly from Windmill. In this guide, we'll cover both approaches.

Action on Windmill from MicrosoftTeams

The goal here is to be able to invoke a Windmill Script from Microsoft Teams, by using /windmill command.

First, you need to be a workspace admin. Then you should go to

Workspace Settings Page

and select the "Slack / Teams" tab. On there, click "Connect to Microsoft Teams".

Self-hosted

The Microsoft Teams integration is done through OAuth. On self-hosted instances, integrating an OAuth API will require Setup OAuth and SSO.

Note that you can connect multiple Windmill workspaces to the same Teams bot. Only one Windmill workspace can accept the /windmill commands from a given Teams "Team".

Using commands on Teams

Once you connected your workspace to a Teams Team, you can either select an existing script or flow to handle the /windmill command, or create a new one by clicking the "Create a script to handle teams command" button.

You will be navigated to the Script editor. Give your script a name (e.g. teams_command_handler), a short summary (e.g. "Teams command handler"). You'll get to this template:

import * as wmill from "windmill-client"

export async function main(
  activity_id: string,
  command: string,
  from_name: string,
  team_id: string,
  teams_message: any
) {
  // Your business logic
  const res = "task completed successfully!"

  // (optional) Send update to Teams channel about completion of job
  await wmill.TeamsService.sendMessageToConversation(
    {
      requestBody: {
        conversation_id: activity_id,
        success: true,
        text: `Hi, ${from_name}, command: ${command} ran successfully with the following result: ${res}`
      }
    }
  )
}

After the Script is deployed, navigate back to the

Teams settings

Choose the "Script" option for adding a command handler and select your newly created Script.

Congratulations! You've just created a Teams command handler. Now you can use the /windmill command in your Teams workspace to trigger the Script.

In addition to activity_id, the script/flow can use the following parameters, simply by having them as inputs with the proper name:

# the ID of the activity in the Teams conversation
activity_id 

# the command that was triggered
command 

# the name of the user who triggered the command
from_name 

# Microsoft Teams Team ID
team_id 

# the original payload from the Teams backend
teams_message 

You won't be able to have Teams interact with your resources and variables before adding them to the teams group that was automatically created by Windmill after you set up your Teams workspace on Windmill.

How to let Teams use your resources and variables:

To give the permission, go to "Resources" (and "Variables") menu, click on Share, Group and pick teams.

One simplier way to handle permissions is to host resources and variables on a folder that is part of the group teams.

Handle multiple commands

You can extend your workspace script to handle complex commands coming from Teams messages. This article shows how to manage multiple commands & human-in-the-loop steps for a slackbot using branches, a text parser and approval steps and can be easily adapted to Teams.

Tutotial - Handler of multiple Slack commands

Create a flow with a parser & branches that will handle multiple Slack commands.

Monitor who ran the command

You can see who ran the /windmill command by going to the

Runs page

on Windmill. The runs will be permissioned through the g/teams global group.

One of the parameters passed to the script is the "from_name" parameter, which is the name of the user who triggered the command. To process further teams specific details from the command, you can use the "teams_message" parameter.

## Example of teams_message payload
{
  "id": "1739549535827",
  "from": {
    "id": "29:152-adq1512TRGdQmxTqdgnfTA",
    "name": "Alexander Petric"
  },
  "text": "<at>WindmillHelperBot</at>. /windmill echo Hello World!",
  "type": "message",
  "locale": "en-US",
  "entities": [
    {
      "text": "<at>WindmillHelperBot</at>",
      "type": "mention",
      "mentioned": {
        "id": "28:0eba9472-83d1-429e-ba2c-1c2993dda84d",
        "name": "WindmillHelperBot"
      }
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "country": "US",
      "platform": "Mac",
      "timezone": "America/New_York"
    }
  ],
  "recipient": {
    "id": "28:0eba9472-83d1-429e-ba2c-1c2993dda84d",
    "name": "WindmillHelperBot"
  },
  "timestamp": "2025-02-14T16:12:15.857639Z",
  "serviceUrl": "https://smba.trafficmanager.net/amer/508f04d5-b0de-4661-b035-b90bb6911ce7/",
  "attachments": [
    {
      "content": "<p><span itemtype=\"http://schema.skype.com/Mention\" itemscope=\"\" itemid=\"0\">WindmillHelperBot</span>. /windmill echo Hello World!</p>"
    }
  ],
  "channelData": {
    "team": {
      "id": "19:[email protected]"
    },
    "tenant": {
      "id": "508f04d5-b0de-4661-b035-b90bb6911ce7"
    },
    "channel": {
      "id": "19:[email protected]"
    },
    "teamsTeamId": "19:[email protected]"
  },
  "conversation": {
    "id": "19:[email protected];messageid=1737565847488"
  }
}

Error handlers

Microsoft Teams is an efficient way to be notified of errors on a Windmill run, whole workspace or instance. Windmill provides an integration for error / success / recovery handling on Microsoft Teams.

More details on Error handling page.