{"id":25764654,"url":"https://github.com/lafe/teams2mqtt","last_synced_at":"2025-11-21T16:04:16.921Z","repository":{"id":206250005,"uuid":"614489330","full_name":"lafe/Teams2Mqtt","owner":"lafe","description":"Windows Service that publishes the Teams state to Home Assistant using MQTT","archived":false,"fork":false,"pushed_at":"2023-12-28T07:35:24.000Z","size":190,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-26T21:19:59.463Z","etag":null,"topics":["home-assistant","mqtt","net-core","teams","windows","windows-service"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lafe.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-15T17:29:03.000Z","updated_at":"2024-04-23T17:27:29.000Z","dependencies_parsed_at":"2023-11-12T17:39:54.025Z","dependency_job_id":"46dc4705-2837-4c5e-be23-c9665013f887","html_url":"https://github.com/lafe/Teams2Mqtt","commit_stats":null,"previous_names":["lafe/teams2mqtt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lafe/Teams2Mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafe%2FTeams2Mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafe%2FTeams2Mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafe%2FTeams2Mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafe%2FTeams2Mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lafe","download_url":"https://codeload.github.com/lafe/Teams2Mqtt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafe%2FTeams2Mqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285645303,"owners_count":27207370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-21T02:00:06.175Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-assistant","mqtt","net-core","teams","windows","windows-service"],"created_at":"2025-02-26T21:19:39.044Z","updated_at":"2025-11-21T16:04:16.892Z","avatar_url":"https://github.com/lafe.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Teams2Mqtt\n\nThis repository contains a Windows service that can send the current state of a Teams meeting through MQTT to Home Assistant. At the moment, the following Team meeting states are supported and converted to sensors:\n\n- is muted\n- is camera on\n- is hand raised\n- is in meeting\n- is recording on\n- is background blurred\n\nThe service uses the \"third-party devices\" API of Teams. This API uses a web socket connection and is also used by the Stream Deck integration. For further details about connecting third party services and devices see [the Teams support page](https://support.microsoft.com/en-us/office/connect-third-party-devices-to-teams-aabca9f2-47bb-407f-9f9b-81a104a883d6).\n\n- [Installation](#installation)\n- [Deinstallation](#deinstallation)\n- [Configuration](#configuration)\n  - [Logging](#logging)\n  - [configuration](#configuration-1)\n    - [Teams API Key](#teams-api-key)\n  - [mqtt](#mqtt)\n  - [sensorLocalizations](#sensorlocalizations)\n- [Troubleshooting](#troubleshooting)\n  - [Service does not start](#service-does-not-start)\n- [Development](#development)\n  - [Versioning](#versioning)\n- [Acknolwedgements](#acknolwedgements)\n\n## Installation\n\nCurrently, there is no automatic setup for this service available, so it has to be setup manually (given the purpose, I am confident that the target audience is able to install the service).\n\nThe application is a Windows service, so only Windows is supported. It uses .NET 7, so the [.NET Runtime](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) must be available. To check if the correct version of .NET is installed, you can use the command `dotnet --list-runtimes` on the command line. This command shows all installed runtimes and should include an entry for \"`Microsoft.NETCore.App`\" with at least version 7.0.0.\n\nThere are two types of releases:\n\n- Multiple files: the application logic is placed in multiple files\n- Single file (**recommended**): the files of the \"multiple files\" release are packed into a single executable\n\nMicrosoft [recommends](https://docs.microsoft.com/en-us/dotnet/core/extensions/windows-service#publish-the-app) to use a self-contained executable for services, so it is recommended to use the \"Single file\" release.\n\nAfter the current release of the software has been downloaded, the following steps are necessary to install the service:\n\n- Extract the archive in a folder of your choice. It is recommended to place it in the \"Program Files\" directory.\n\n- Modify the configuration file of the service to fit your environment. Details about the configuration can be found in the [below](#configuration).\n\n- The Windows service itself is created/registered through the `sc` app that is available on Windows. The following command has to be changed for your environment and can be executed afterwards (requires Administrator permissions; PowerShell is recommended):\n\n   ```powershell\n   sc.exe create \"Teams2Mqtt\" binpath=\"\u003cPath To App\u003e\\Teams2Mqtt.exe\" start=\"delayed-auto\"\n   ```\n\n   This command creates a new service with the name \"Teams2Mqtt\" that runs the given executable. The application will be started automatically but waits until more critical services with start type \"Automatic\" are started. If you want to start it sooner, you can change the start type to \"`auto`\" if you want. A detailed documentation about the the `sc.exe create` command can be found at [Microsoft Learn](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create).\n\n- The service can log to the Windows Event Log. To enable this, a new category has to be created. This can be done using the following PowerShell command that has to be run with administrative permissions:\n\n   ```powershell\n   New-EventLog -LogName Teams2Mqtt -Source Teams2Mqtt\n   ```\n\n   Afterwards, a new log is created under \"Applications and Services Logs\". The log level can be configured    through the [application settings file](#configuration).\n\n- The service is not started automatically after creation but only after a reboot. If you want to skip the reboot and use the application immediately, you can use the following PowerShell command (requires Administrator permissions):\n\n   ```powershell\n   Start-Service Teams2Mqtt\n   ```\n\n## Deinstallation\n\nIf you want to uninstall the service, you can uninstall the service service in a similar way:\n\n- First you have to stop the service (PowerShell; requires Administrator permissions):\n\n   ```powershell\n   Stop-Service Teams2Mqtt\n   ```\n\n- Afterwards, you can remove the service with the familiar \"sc.exe\" tool (requires Administrator permissions):\n\n   ```powershell\n   sc.exe delete \"Teams2Mqtt\"\n   ```\n\n- If you created the Event Log category, you can delete it using the following PowerShell command (requires administrative permissions):\n\n   ```powershell\n   Remove-EventLog -LogName \"Teams2Mqtt\"\n   ```\n\nFurther details about installing a .NET application as a Windows service can be found in the [Microsoft documentation](https://docs.microsoft.com/en-us/dotnet/core/extensions/windows-service).\n\n## Configuration\n\nThe application is configured using the `appsettings.json` file. A JSON schema is available for the file, so it is recommended to use an editor that can leverage the schema information (e.g. [VS Code](https://code.visualstudio.com/)).\n\nThe source code contains the \"[appsettings.Example.json](Teams2Mqtt/appsettings.Example.json)\" and excludes the \"normal\" appsettings.json via the .gitignore file to prevent leaking of secrets. If you want to modify the code yourself, you can create a new appsettings.json and copy the content of the [appsettings.Example.json](Teams2Mqtt/appsettings.Example.json) to it so that you have a starting point. The compiled release version contains an \"appsettings.json\" that is based on the [appsettings.Example.json](Teams2Mqtt/appsettings.Example.json) file.\n\nThe individual sections of the configuration file are detailed in the following chapters.\n\n### Logging\n\nThe application uses the default [.NET logging infrastructure](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line) with built-in providers. When debugging or when running the application stand-alone, the most visible is the [Console Logger](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging-providers#console). The application also uses the [Windows EventLog](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging-providers#windows-eventlog).\n\n```JSON\n\"Logging\": {\n    \"LogLevel\": {\n        \"Default\": \"Information\",\n        \"Microsoft.Hosting.Lifetime\": \"Information\"\n    },\n    \"EventLog\": {\n        \"LogLevel\": {\n            \"Default\": \"Information\",\n            \"Microsoft.Hosting.Lifetime\": \"Information\"\n        }\n    }\n}\n```\n\nThe \"`Logging`\" section of the configuration file is the default configuration of the default .NET logging infrastructure. The `LogLevel` defines the default visibility of different logging levels. The first `LogLevel` in the example above is the logging level for the console output. Changes to the second `LogLevel` describes the logging levels that are logged for the Windows Event Log.\n\nValid values for the log level are (Descriptions taken from [Microsoft Learn](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#log-level)):\n\n| LogLevel    | Description                                                                                                                                                        |\n| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Trace       | Contain the most detailed messages. These messages may contain sensitive app data. These messages are disabled by default and should not be enabled in production. |\n| Debug       | For debugging and development. Use with caution in production due to the high volume.                                                                              |\n| Information | Tracks the general flow of the app. May have long-term value.                                                                                                      |\n| Warning     | For abnormal or unexpected events. Typically includes errors or conditions that don't cause the app to fail.                                                       |\n| Error       | For errors and exceptions that cannot be handled. These messages indicate a failure in the current operation or request, not an app-wide failure.                  |\n| Critical    | For failures that require immediate attention. Examples: data loss scenarios, out of disk space.                                                                   |\n| None        | Specifies that no messages should be written.                                                                                                                      |\n\nFurther information about the logging system can be found at \u003chttps://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line\u003e.\n\n### configuration\n\nThe `configuration` section contains general application settings that mostly deal with the Teams Connection:\n\n| Property                 |          | Description                                                                                                                                                                    |\n| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `teamsApiKey`            | Required | The API Key that authenticates access to the Teams Web Socket. See [below](#teams-api-key) on how to retrieve the key.                                                         |\n| `teamsWebSocketAddress`  | Optional | The address of the Teams Web Socket endpoint. This is normally \"127.0.0.1\" or \"localhost\". The default value is \"`localhost`\".                                                 |\n| `teamsWebSocketPort`     | Optional | The port of the Teams Web Socket endpoint. The default value is `8124`.                                                                                                        |\n| `teamsReconnectInterval` | Optional | The interval in seconds to wait before trying to reconnect to the Teams Web Socket endpoint if the connection was closed (or Teams is not running). The default value is `10`. |\n\n#### Teams API Key\n\nTo access Teams through the Teams2Mqtt service, Teams must allow connections of third-party apps.\n\n![Location of the \"Manage API\" button in the Teams settings](documentation/assets/ManageAPIButtonLocation.png)\n\nTo allow this functionality, you have to open the Teams Settings and navigate to the Privacy tab (1). Afterwards, you have to scroll down to the \"Third-party app API\" section of the privacy tab. In this section, you have to click the \"Manage API\" button (2).\n\n![Location of the API key](documentation/assets/ApiTokenLocation.png)\n\nIn the following screen, you have to make sure that the \"Enable API\" toggle is set to active (3). Afterwards, you can copy the \"API token\" from this screen (4).\n\nThis API token allows third party apps, like Teams2Mqtt or the Teams integration for the Elgato Stream Deck, access to some functionality of Teams. The [Teams support page](https://support.microsoft.com/en-us/office/connect-third-party-devices-to-teams-aabca9f2-47bb-407f-9f9b-81a104a883d6) also has a manual on how to manage this setting.\n\n### mqtt\n\nThe `mqtt` section of the `appsettings.json` configures the connection to the MQTT broker as well as some Home Assitant specific configuration settings:\n\n| Property                          |          | Description                                                                                                                                                                                                      |\n| --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `server`                          | Required | The address of the MQTT broker                                                                                                                                                                                   |\n| `port`                            | Required | The port of the MQTT broker                                                                                                                                                                                      |\n| `username`                        | Optional | The username that is used to authenticate with the MQTT broker. This setting is only needed if authentication is enabled for the MQTT broker.                                                                    |\n| `password`                        | Optional | The password that is used to authenticate with the MQTT broker. This setting is only needed if authentication is enabled for the MQTT broker.                                                                    |\n| `mqttLoggingEnabled`              | Optional | If enabled, the MQTTnet client will also output log messages.                                                                                                                                                    |\n| `homeAssistantAutodiscoveryTopic` | Optional | The prefix of the topic to use for MQTT auto discovery by Home Assistant. The default value is \"`homeassistant`\". See \u003chttps://www.home-assistant.io/integrations/mqtt/#mqtt-discovery\u003e for further information. |\n| `removeDevicesOnShutdown`         | Optional | If enabled, the devices will be removed from Home Assistant when the service is stopped. Default value is `false`.                                                                                               |\n| `deviceSuggestedArea`             | Optional | The suggested area for the created device in Home Assistant. See \u003chttps://www.home-assistant.io/integrations/sensor.mqtt/#suggested_area\u003e for further details.                                                   |\n\n### sensorLocalizations\n\nThe service creates sensors in Home Assistant using [MQTT Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery). Part of the auto discovery messages are names for the sensors that should be created in Home Assistant. By default, the Teams2Mqtt service uses English names for the sensors, but it is possible to localize them on creation. This is done in the `sensorLocalizations` section. This is an array that contains localization objects consisting of a `sensorId` and a `sensorName`. The `sensorId` is unique and pre-defined (see table below) whereas the `sensorName` is the localized name of the sensor in your language. If a localization is missing, the default value (i.e. the English name) is used.\n\nThe following `sensorId`s are currently defined:\n\n| `sensorId`          | English name          |\n| ------------------- | --------------------- |\n| isMuted             | Is Muted              |\n| isCameraOn          | Is Camera On          |\n| isHandRaised        | Is Hand Raised        |\n| isInMeeting         | Is In Meeting         |\n| isRecordingOn       | Is Recording On       |\n| isBackgroundBlurred | Is Background Blurred |\n\nA German translation could be as follows:\n\n```JSON\n\"sensorLocalizations\": [\n   {\n     \"sensorId\": \"isMuted\",\n     \"sensorName\": \"Stummgeschaltet\"\n   },\n   {\n     \"sensorId\": \"isCameraOn\",\n     \"sensorName\": \"Kamera eingschaltet\"\n   },\n   {\n     \"sensorId\": \"isHandRaised\",\n     \"sensorName\": \"Hand gehoben\"\n   },\n   {\n     \"sensorId\": \"isInMeeting\",\n     \"sensorName\": \"In Besprechung\"\n   },\n   {\n     \"sensorId\": \"isRecordingOn\",\n     \"sensorName\": \"Aufnahme läuft\"\n   },\n   {\n     \"sensorId\": \"isBackgroundBlurred\",\n     \"sensorName\": \"Hintergrund unscharf\"\n   }\n]\n```\n\n## Troubleshooting\n\n### Service does not start\n\n- Check if the appsettings.json is present and formatted correctly.\n- Check if the Event Log contains messages. If the dedicated event log does not contain any messages, the general Windows Application Event Log (Event Viewer -\u003e Windows Logs -\u003e Application) might contain information.\n\n## Development\n\n### Versioning\n\nThe project uses [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) for generating the version numbers.\n\n## Acknolwedgements\n\nThis project is built on the research of other members of the community that were kind enough share it:\n\n- [Teams Client Api Sample](https://github.com/GrillPhil/TeamsClientApiSample/) by [Philipp Bauknecht](https://github.com/GrillPhil)\n- [Teams Monitor](https://github.com/svrooij/teams-monitor) by [Stephan van Rooij](https://github.com/svrooij)\n- [Description of the Microsoft Teams WebSocket API](https://lostdomain.notion.site/Microsoft-Teams-WebSocket-API-5c042838bc3e4731bdfe679e864ab52a)\n- [Teams 3rd Party Client-API](https://www.msxfaq.de/teams/apps/teams_3rd_party_client_api.htm) article (in German) by [Frank Carius](https://www.msxfaq.de/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flafe%2Fteams2mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flafe%2Fteams2mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flafe%2Fteams2mqtt/lists"}