Teams monitor

A simple command line application that connects to the local Teams API and forwards the meeting status to any endpoint (you manage).

Sending the status from your Teams client to any website is a matter of three steps:

Install the tool dotnet tool install --global SvRooij.TeamsMonitor
Run the tool teams-monitor --webhook {url-here}
Join a test meeting to trigger the pairing process

This app needs either .NET6 or .NET8 installed on your machine.

Library available

There also is a library available, if you want to use this in your own application.

What does Teams Monitor do?

It connects to Teams and allows you to send the realtime data from your Teams client to any server (flowchart only displays at github).

flowchart LR
    T[Teams Client]-->|Websocket| M[Teams monitor]
    M-->|HTTP/HTTPS POST| W[Any url]

If you run this tool with a webhook specified, the webhook will receive a HTTP POST message with the following JSON payload:

{
  "meetingUpdate": {
    "meetingState": {
      "isMuted": false,
      "isVideoOn": false,
      "isHandRaised": false,
      "isInMeeting": false,
      "isRecordingOn": false,
      "isBackgroundBlurred": false,
      "isSharing": false,
      "hasUnreadMessages": false
    },
    "meetingPermissions": {
      "canToggleMute": false,
      "canToggleVideo": false,
      "canToggleHand": false,
      "canToggleBlur": false,
      "canLeave": false,
      "canReact": false,
      "canToggleShareTray": false,
      "canToggleChat": false,
      "canStopSharing": false,
      "canPair": false
    }
  }
}

Meeting light for your home office

I've been working from home a lot lately, and I always wanted to control the light in the hallway to turn another color when I'm in a meeting. I was doing this with a button on my desk and forgot to switch it approximately fifty percent of the time.

I'm a big fan of Home Assistant, it helps me automate everything around that house. So let's configure home assistant to change the color of the lights in the hallway

Home assistant - Step 1

Create a toggle helper for the user you want to monitor. These are hidden under Settings -> Devices & Services -> Helpers, pick a name that makes sense like {name} Meeting.

Create toggle

Home assistant - Step 2

Create a new blank automation and use the webhook trigger. Settings -> Automations & Scenes -> Create Automation.

Add a Webhook trigger. This wil generate a new webhook url that looks like https://{your-ha-domain}/api/webhook/{some-complicated-string} and this should be kept secret!

Add an action, pick the If-Then and add a template condition. The template should be {{trigger.json.meetingState.isInMeeting}} with the brackets!

In the then section you should add a Call Service action that calls input_boolean: Turn On and be sure to select your helper from step 1

Press the Add else link and add a Call Service action that does the reverse input_boolean: Turn Off.

Create automation

Home assistant - Step 3

Copy the webhook url from the automation you just created and use that to start the Teams Monitor

teams-monitor --webhook {webhook-url}

If you want to make it easier on yourself, you can also save the webhook in the environment settings

TEAMS_WEBHOOK Url copied from Home Assistant.

Home assistant - Step 4

You now have a toggle helper that changes automatically when you're in a meeting. You can create an addition automation that does something when the toggle changes state. By connecting the automation to the toggle and not to the webhook, you can also manually trigger the same actions.

Create automation change lights

Teams has a local api?

Yes, it does! If you never heard of it, that might be right because it was released February 1st 2023. Once you enable it, ~~you get a local api token.~~ Teams opens up a local websocket server that you can connect to using your client of choice.

ws://localhost:8124?token=61e9d3d4-dbd6-425d-b80f-8110f48f769c&protocol-version=2.0.0&manufacturer=YourManufacturer&device=YourDevice&app=YourApp&app-version=2.0.26

At first you have limited access, and once the user goes into a meeting you'll see a message like:

{
  "meetingUpdate": {
    "meetingPermissions": {
      "canToggleMute": true,
      "canToggleVideo": true,
      "canToggleHand": true,
      "canToggleBlur": false,
      "canLeave": true,
      "canReact": true,
      "canToggleShareTray": true,
      "canToggleChat": true,
      "canStopSharing": false,
      "canPair": true
    }
  }
}

If canPair is true, it means the user is in a meeting and you can send any available command to trigger the pairing message in Teams and your app will get a new token for the next connection. If seeing if the user is an a meeting is enough for your use case, you can skip the pairing process and just use canPair as an indication whether the user is in a meeting.

Messages send by Teams

Currently it seems there are several messages that you might receive:

Meeting update

After pairing, you will get messages like these:

{
  "meetingUpdate": {
    "meetingState": {
      "isMuted": false,
      "isVideoOn": false,
      "isHandRaised": false,
      "isInMeeting": false,
      "isRecordingOn": false,
      "isBackgroundBlurred": false,
      "isSharing": false,
      "hasUnreadMessages": false
    },
    "meetingPermissions": {
      "canToggleMute": false,
      "canToggleVideo": false,
      "canToggleHand": false,
      "canToggleBlur": false,
      "canLeave": false,
      "canReact": false,
      "canToggleShareTray": false,
      "canToggleChat": false,
      "canStopSharing": false,
      "canPair": false
    }
  }
}

Service response

Pairing failed

{"requestId":1,"response":"Pairing response resulted in no action"}

Your service request complete successfully

{"requestId":2,"response":"Success"}

Token update

{"tokenRefresh":"61e9d3d4-dbd6-425d-b80f-8110f48f769c"}

Commands available

You can send several commands to the websocket server, but they will only be accepted if you completed the pairing process.

Each command has a requestId that you can use to match the response to the request. It seems to be an incrementing number, but I'm not sure if you can re-used them on the same connection.

{ "action":"some-action","parameters":{},"requestId":1 }

Send a reaction

You can send several reactions to teams. The once tested: like, love, applause, wow, laugh

{
  "action": "send-reaction",
  "parameters": {
    "type": "like"
  },
  "requestId": 1
}

Toggle background blur

{"action":"toggle-background-blur","parameters":{},"requestId":1}

Toggle Video

{"action":"toggle-video","parameters":{},"requestId":1}

Toggle Mute

{"action":"toggle-mute","parameters":{},"requestId":1}

Toggle Hand

{"action":"toggle-hand","parameters":{},"requestId":1}

Leave call

{"action":"leave-call","parameters":{},"requestId":2}

Socials

If you like my Teams Monitor, please give me a shout out on any of these platforms.

svrooij / teams-monitor

readme