Microsoft Teams App

The Rocket.Chat Microsoft Teams app embeds your self-hosted Rocket.Chat workspace as a personal tab inside the Microsoft Teams desktop client. This enables users to open rooms, send messages, search your workspace, and access core Rocket.Chat features directly from Teams without switching applications.

How it works

The app renders Rocket.Chat using an iframe embedded in Teams while Rocket.Chat continues to run independently. It does not:

Synchronize messages, users, or presence between Rocket.Chat and Teams.
Synchronize notifications between the two applications.
Provide Microsoft Teams single sign-on (SSO).

Your Teams and Rocket.Chat user accounts and sessions remain completely independent..

Set up the Microsoft Teams app

An administrator must configure the app before distributing it to users in your organization.

Prerequisites

Before you begin, make sure you have:

A self-managed Rocket.Chat workspace with administrator access.
Permission to upload custom apps to Microsoft Teams.
A HTTPS URL for your Rocket.Chat workspace, such as https://chat.example.com.

Step 1: Allow Rocket.Chat to be embedded in Teams

By default, Rocket.Chat prevents its interface from being embedded in external sites. To allow Teams to display your workspace, disable the iframe restriction:

Sign in to your Rocket.Chat workspace as an administrator.
Go to Manage > Workspace > Settings > General.
Disable Restrict access inside any Iframe.
Click Save Changes.

This removes the X-Frame-Options restriction that prevents Teams from displaying your workspace.

Restrict iframe access to Microsoft Teams
Disabling Restrict access inside any Iframe globally allows other sites to embed your workspace. For production environments, configure your reverse proxy to allow iframe embedding only from Microsoft Teams.
For example, with NGINX, configure the Content-Security-Policy header to allow the Teams domains:
server {
    ...
    location / {
        proxy_pass http://rocketchat_backend;

        # Belt-and-braces: strip any X-Frame-Options coming from the app
        proxy_hide_header X-Frame-Options;
        proxy_hide_header Content-Security-Policy;

        # Allow framing ONLY by Teams (classic + new Teams hosts) and ourselves
        add_header Content-Security-Policy "frame-ancestors 'self' https://teams.microsoft.com https://*.teams.microsoft.com https://teams.cloud.microsoft https://*.cloud.microsoft" always;
    }
}
If your reverse proxy already manages a Content-Security-Policy header, merge the frame-ancestors directive into your existing policy instead of replacing the entire header.

Step 2: Configure the Microsoft Teams app

Rocket.Chat provides an app package in the Rocket.Chat Teams app repository.

Choose the configuration method that matches your organization.

Single fixed workspace: With this option, the Teams app opens a specific Rocket.Chat workspace every time it is launched. Recommended for organizations with one Rocket.Chat workspace.
Dynamic workspace selection : Use this option if you want users to enter their workspace URL upon first launch. Recommended for organizations with multiple Rocket.Chat workspaces.

Single fixed workspace

Dynamic workspace selection

If you have Git installed, clone the repository:
```
git clone https://github.com/RocketChat/rc-msteams-app.git
cd rc-msteams-app
```
If you do not have Git installed, download the repository as a ZIP file from the GitHub repository and extract it.
Open the package directory. It contains the files required to package the Teams app:
```
package/
├── manifest.json
├── color.png
└── outline.png
```
The manifest.json file defines how Microsoft Teams identifies and loads the Rocket.Chat app.
Open package/manifest.json and update the following fields:
1. In staticTabs, set the contentUrl and websiteUrl to your Rocket.Chat workspace URL. For example:
```
"contentUrl": "https://chat.example.com/",
"websiteUrl": "https://chat.example.com/",
```
2. Update validDomains with the hostname of your Rocket.Chat workspace. For example:
```
"validDomains": [
    "chat.example.com",
    "*.rocket.chat"
  ]
```
  You can use wildcards, such as *.example.com.

From the repository root, create the Teams app package:

cd package && zip -r ../rocketchat-teams-app.zip manifest.json color.png outline.png

The resulting rocketchat-teams-app.zip file is ready to upload or publish in Microsoft Teams.

Instead of hardcoding a single workspace URL in the Teams app, you can use the wrapper.html page included in the repository. The wrapper allows users to enter or select their Rocket.Chat workspace when they launch the app.

Host the wrapper.html file from the repository on a secure static host you control.
If you have Git installed, clone the repository:
```
git clone https://github.com/RocketChat/rc-msteams-app.git
cd rc-msteams-app
```
If you do not have Git installed, download the repository as a ZIP file from the Github repository and extract it.
Open the package directory. It contains the files required to package the Teams app:
```
package/
├── manifest.json
├── color.png
└── outline.png
```
The manifest.json file defines how Microsoft Teams identifies and loads the Rocket.Chat app.
Open package/manifest.json and update the following fields:
1. In staticTabs, set the contentUrl and websiteUrl to your hosted wrapper URL. For example:
```
"contentUrl": "https://apps.yourcompany.com/rc-tab/wrapper.html",
"websiteUrl": "https://apps.yourcompany.com/rc-tab/wrapper.html",
```
2. Update validDomains with the hostname of your Rocket.Chat workspace. For example:
```
"validDomains": [
    "chat.example.com",
    "*.rocket.chat"
  ]
```
  You can use wildcards for subdomains, such as *.example.com.

From the repository root, create the Teams app package:

cd package && zip -r ../rocketchat-teams-app.zip manifest.json color.png outline.png

The resulting rocketchat-teams-app.zip file is ready to upload or publish in Microsoft Teams.

If you are creating a second Rocket.Chat Teams app in the same Microsoft 365 tenant, generate a new app ID. The id field in manifest.json must be unique within the tenant.
Do not add a packageName field. It is not part of the current manifest format and will cause validation to fail.
If you change the app version, update the version field in manifest.json before packaging the app.

Step 3: Distribute the app

Once you have configured and packaged the app, distribute the package using one of the following methods:

Publish to your organization: Add the app privately within the organization for internal use to make it available to all authorized users. Refer to the official Microsoft Teams guide for more details.
Sideload as a custom app: Provide the .zip file directly to individual users or teams to upload via the Teams client.

Use Rocket.Chat in Microsoft Teams

Once distributed by an administrator, users can install and use Rocket.Chat inside Teams.

Step 1: Install the app

Open the Microsoft Teams desktop app.
Click Apps in the left sidebar.
Install the app based on how your administrator distributed it:
1. App published to your organization: Click Built for your org, select the Rocket.Chat app, and click Add.
2. Custom app file: Click Manage your apps > Upload an app > Upload a custom app, select the zip file, and click Add.
Click Open to launch the Rocket.Chat tab.

Tip: Right-click the Rocket.Chat icon in the Teams sidebar and select Pin to keep it readily accessible.

Step 2: Access Rocket.Chat in Microsoft Teams

Open the Microsoft Teams desktop app.
Select Rocket.Chat from the Teams app list.
Follow the prompts displayed in the app:
1. If your administrator configured a specific Rocket.Chat workspace, the workspace opens directly.
2. If your administrator configured dynamic workspace selection, enter your Rocket.Chat workspace URL.
Sign in to Rocket.Chat using your Rocket.Chat credentials.

Once signed in, you can access your rooms, send messages, search discussions, upload files, and use supported Rocket.Chat features from within Teams.

Known limitations

Authentication: Microsoft Teams SSO is not supported. Users sign in to Rocket.Chat separately inside Teams. Your Rocket.Chat session inside Teams is separate from your session in a regular browser. SAML and OAuth authentication may not work if your identity provider does not support embedded authentication or relies on third-party cookies.
Deep linking: Teams notifications do not link directly to specific Rocket.Chat rooms. msteams:// links and Teams channel deep links do not open corresponding Rocket.Chat conversations. Rocket.Chat desktop notifications may not work while the workspace is open inside Teams.
Calls and media: Camera, microphone, and screen-sharing behavior depends on the Teams client and its webview. Rocket.Chat calls and integrations such as Jitsi or Pexip may therefore not work as expected inside Teams. Treat audio and video features as best effort and test them with your Teams client before deployment.
File transfers: File uploads and downloads are handled by the Teams webview and may behave differently from the same operations in a regular browser.

Documentation Index