# Install Brev in Microsoft Teams (admin guide) For Microsoft 365 and Teams admins: add Brev to your organization's Teams app catalog, approve it, and roll it out to your members. This guide is for the Microsoft 365 admin who adds Brev to your organization's Microsoft Teams. It takes about 15 minutes, and members don't need to do anything until it's done. > **Note: Why Brev is a custom app for now** > > Brev's listing in the Microsoft Teams Store is in Microsoft's review. Until it's published, your organization adds Brev to Teams by uploading our app package to your own app catalog. It's the same app the store will list, and everything in Brev works the same way. ## Before you start Three roles take part. One person can hold all of them: - **Teams Administrator (or Global Administrator)**: Uploads the Brev app in the Teams admin center and chooses who can use it. - **Global Administrator (or Privileged Role Administrator)**: Approves Brev for the whole organization (Microsoft calls this tenant-wide admin consent). Brev asks for application permissions to Microsoft Graph, and only these two roles can grant them. - **Brev Org Admin**: Starts the connection from Brev's Integrations page. If your Microsoft admin isn't one, invite them to your Brev organization as an Org Admin, or sit together for step 4 (see [Roles & permissions](https://help.brev.io/roles-and-permissions/)). - Your organization needs a Brev workspace with Microsoft Teams turned on. If you don't see a Microsoft Teams card on the Integrations page, contact Brev support. - Your Brev members' email addresses should match their Microsoft 365 sign-in or email address. That's how Brev finds each person in Teams. ## 1. Download the Brev app package Download [brev-teams-app.zip](https://app.brev.io/downloads/brev-teams-app.zip). You don't need a Brev account to download it, so you can send the link to an admin who doesn't use Brev. It's also in Brev: in Settings, then Integrations, click **Connect** on the Microsoft Teams card, then **Download Teams app**. Upload the zip file as it is. Don't unzip it or edit it: Teams reads the file inside to know which app it is. ## 2. Allow custom apps in your organization Teams blocks apps your organization uploads unless custom apps are allowed. Many organizations already allow them. To check: 1. **Open Manage apps**: Sign in to the [Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps), then go to Teams apps, then Manage apps. 2. **Open Org-wide app settings**: Click **Actions**, then **Org-wide app settings**. 3. **Turn on custom apps**: Under Custom apps, turn on both **Let users install and use available apps by default** and **Let users interact with custom apps in preview**, then click **Save**. If both are already on, click **Cancel**. ![The Custom apps section of Org-wide app settings in the Teams admin center, with Let users install and use available apps by default and Let users interact with custom apps in preview both turned on.](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-allow-custom-apps.png) *Org-wide app settings, Custom apps: both switches on.* If your Teams admin center looks different (an older layout uses app permission policies instead), allow custom apps in the permission policy that applies to your members. ## 3. Upload Brev to your app catalog ![Brev's page in the Teams admin center: Published version 1.2.0, Upload file under New version, and Available to Everyone (org-wide default).](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-upload-the-app.png) *Brev's page in Manage apps: Upload file under New version.* 1. **Open Brev in Manage apps**: In the Teams admin center, go to Teams apps, then Manage apps. Search for Brev, then click Brev in the results to open its page. 2. **Upload the package**: Under New version, click **Upload file**, then **Select a file**, and pick brev-teams-app.zip. If Brev isn't in the list, click **Actions**, then **Upload new app** instead. 3. **Make Brev available to your members**: Back in Manage apps, in Brev's row, App status should be **Unblocked** and Available to should be **Everyone**, or groups that hold every member who uses Brev. To change who can use it, open Brev, then the **Users and groups** tab. Brev can only reach people the app is available to. ![Brev in the Manage apps list after the upload: Installed for No one, Available to Everyone (org-wide default), App status Unblocked.](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-upload-the-app-availability.png) *Right after the upload: available to everyone and unblocked. Installed for stays No one until Brev adds itself in step 4.* Open Brev's Permissions tab to see what it asks for. You don't need to grant anything there: you approve Brev from Brev in step 4. ![Brev's Permissions tab in the Teams admin center, listing eight permissions: User.Read, AppCatalog.Read.All, TeamsAppInstallation.ReadWriteForUser.All and User.Read.All from Entra ID, and ChannelMessage.Read.Group, TeamMember.Read.Group, ChannelSettings.Read.Group and TeamSettings.Read.Group as resource-specific consent.](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-upload-the-app-permissions.png) *The eight permissions Brev asks for.* - **Microsoft Graph, for your whole organization**: Read all users' full profiles (User.Read.All), to find each Brev member's Teams account by email. Read all app catalogs (AppCatalog.Read.All), to find the Brev app you uploaded. Manage Teams apps for all users (TeamsAppInstallation.ReadWriteForUser.All), to add Brev to each member's Teams. Sign in and read user profile (User.Read), for the sign-in that confirms your organization. - **Teams, per team (approved by the team owner)**: Read the team's channel messages, its members, its channel names and settings, and the team's own settings, such as whether it's public or private (ChannelMessage.Read.Group, TeamMember.Read.Group, ChannelSettings.Read.Group, TeamSettings.Read.Group). Only for teams that add Brev. You can also upload from the Teams app: Apps, then **Manage your apps**, then **Upload an app**. As an admin, choose **Upload an app to your org's app catalog**. Someone who isn't a Teams admin can choose **Submit an app to your org** instead: the admin then finds Brev under Pending approval in Manage apps, and approves it there. > **Warning: Upload it to the catalog, not for yourself** > > If Teams also offers Upload a custom app, don't use it for Brev. It installs an app for you alone, and Teams refuses that for Brev. Changes in the Teams admin center can take a few hours to reach every Teams client. You can go on to the next step straight away. ## 4. Connect Brev and approve it for your organization Do this after the upload: when you approve Brev, it looks for the app in your catalog to add it to Teams for your members. 1. **Open the Microsoft Teams card**: In Brev, go to Settings, then Integrations. On the Microsoft Teams card, in the Communication section, click **Connect**. A dialog shows the two steps; you've done the first. 2. **Approve the permissions**: Click **Connect** in the dialog. Microsoft asks you to sign in: use a Global Administrator or Privileged Role Administrator account. Microsoft lists what Brev asks for, the permissions in step 3. Click **Accept**. 3. **Sign in once more**: Microsoft asks you to sign in again, so Brev can confirm which organization approved it. Use a work account in that organization: a guest or personal Microsoft account can't finish connecting. You're back in Brev, and the Microsoft Teams card is in the Connected section. ## 5. Check what your members get - Within a few minutes, Brev adds itself to Teams for each Brev member it can match by email, and sends them a welcome message in a 1:1 chat. Nobody needs to install anything. - Brev adds itself only for people who are in your Brev organization when you connect. For someone who joins Brev later, install Brev for them from the Teams admin center (below), or they connect their Teams coworker from Settings, AI coworkers, which adds it for them. - Members find Brev in Teams under Apps, Built for your org. - What Brev sends and answers in Teams is in [Chat & notifications](https://help.brev.io/integrations-chat/). ![Brev listed under Built for your org in the Apps section of Microsoft Teams, described as Your Brev agent in Teams: goals, check-ins, weekly recaps, and nudges.](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-what-members-see-apps.png) *Brev in Teams, under Apps, Built for your org.* To check it works, open your chat with Brev in Teams and send **Hi**. Brev replies within a few seconds with a welcome card offering Summarize my week and What's at risk?. Its answers are about your Brev goals, meetings and check-ins. ![Brev's welcome card in Teams: Hi, I'm your Brev assistant, with the buttons Summarize my week and What's at risk?.](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-what-members-see.png) *Brev's welcome card.* Teams labels every message Brev sends as AI generated, and each answer card ends with a reminder to review it and a **Report an issue** link. To report an answer that's wrong or objectionable, use that link or email success@brev.io. To install Brev for people yourself, for example everyone at once or someone who joined Brev later, use the Teams admin center: in Manage apps, select Brev, click **Edit installs**, choose **Everyone** or **Specific users or groups** under Install to, then click **Apply**. Installed for in the list changes straight away; Teams can take a few hours to show Brev to those people. ![The Install to menu in the Edit installs panel of the Teams admin center, with the options Everyone, Specific users or groups, and No one.](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-what-members-see-edit-installs.png) *Edit installs, Install to: Everyone, or Specific users or groups.* ## Add Brev to a team To use Brev in a team's channels, a Teams admin adds it in the Teams admin center: in Manage apps, select Brev, click **Add to team**, search for the team, click **Add**, then **Apply**. Brev posts its welcome card in the team's General channel. A team owner can also add it from Teams: Apps, Brev under Built for your org, a channel under **Or choose a place to use the app**, then **Go**. Adding Brev to a team asks for that team's permissions listed in step 3. If channel reading later can't read a team that a Teams admin added Brev to, have one of the team's owners add Brev to the team from Teams as above. In channels, Brev answers only when someone @mentions it. It keeps those messages and its replies as part of the conversation, and keeps no other channel messages unless a Brev Org Admin turns channel reading on. ## Turn on channel reading Channel reading lets Brev answer questions about what a team discussed in its channels. It's off until a Brev Org Admin turns it on. 1. **Open the Microsoft Teams settings**: In Brev, go to Settings, then Integrations. On the Microsoft Teams card, click **Edit**. 2. **Turn it on**: Turn on **Read standard channels in teams where Brev is installed**, then click **Turn on channel reading**. 3. **Exclude channels (optional)**: Under **Channels Brev should never read**, choose any channels Brev should skip, then click **Save exclusions**. - Once a day, Brev summarizes each standard channel in the teams it's in. When you turn reading on, it also reads the last 14 days. - Only members of a team get answers from its channel summaries. Guests in your Brev organization never do. - Private and shared channels are never read. - Brev stops reading an excluded channel from the next day. What it already kept stays, but no one gets answers from it while it's excluded. Removing a channel from the list reads its last 14 days again. - To stop channel reading, turn the switch off in the same place. Summaries Brev already kept still answer the team's members. ## Disconnect Teams from Brev In Brev, go to Settings, then Integrations. On the Microsoft Teams card, click the trash icon (**Disconnect integration**). Brev doesn't delete the channel summaries it kept, but no one gets answers from them while Teams is disconnected. Disconnecting doesn't remove the app from Teams: to do that, delete Brev in Manage apps in the Teams admin center. ## Update to a new version When the Microsoft Teams card in Brev asks you to upload the current package, or this page lists a newer version, update the app: ![Brev's page in the Teams admin center: Published version 1.2.0, Upload file under New version, and Available to Everyone (org-wide default).](https://help.brev.io/doc-assets/screenshots/microsoft-teams-admin-install-upload-the-app.png) *Brev's page in Manage apps: Upload file under New version.* 1. Download the latest brev-teams-app.zip from the link above. 2. In the Teams admin center, search for Brev in Manage apps and open it. Under New version, click **Upload file**, then **Select a file**, and pick the zip. Published version changes to the new number. Teams accepts only a package with a higher version than the one you have. 3. If the new version asks for permissions or features members haven't approved, they see New version of Brev is available at the top of their chat with Brev. They click **Update**, review what's new and the permissions, then click **Update now**. Otherwise Teams updates Brev for them, and they don't need to do anything. 4. If the new version asks for new team permissions, team owners update Brev in their teams and approve them there. > **Warning: Update Brev, don't delete it** > > Deleting Brev from Manage apps removes it from everyone's Teams, and uploading it again doesn't put it back: you'd have to install it for people again. To change versions, always use Upload file on Brev's page. ## Once Brev is in the Teams Store The app you upload today keeps working. When Brev is published in the Teams Store, this page will say whether there's anything to change. ## Troubleshooting ### I can't find Upload file, or it's greyed out. Your account needs the Teams Administrator or Global Administrator role. If you have it, check that custom apps are allowed (step 2 above). ### Teams says the app is blocked, or members can't find Brev. In Manage apps, check that Brev's App status is Unblocked and that Available to includes those members. If your organization uses app permission policies instead, allow custom apps (or Brev) in the policy that applies to them. Changes can take a few hours to reach every Teams client. ### Microsoft says Need admin approval when I click Connect. The account you signed in with can't grant tenant-wide consent. Sign in with a Global Administrator or Privileged Role Administrator account, or have one click Connect from Brev. ### I connected Brev before uploading the app, and members got no welcome message. Brev couldn't find the app in your catalog when you connected. Upload it (step 3), then install it for your members with Edit installs in the Teams admin center (see step 5). ### One member didn't get Brev. Brev matches people by email. Check that the member has joined your Brev organization, and that their Brev email matches their Microsoft 365 sign-in or email address. You can also install Brev for them with Edit installs in the Teams admin center (see step 5). ### A member's chat with Brev says You cannot send messages to this bot. Brev isn't installed for them, for example after the app was deleted and uploaded again. Install it for them with Edit installs in the Teams admin center (see step 5), and allow a few hours for Teams to catch up. ### Adding Brev from Teams says Something went wrong. Use the Teams admin center instead: Edit installs to add Brev for people, or Add to team to add it to a team. Teams can take a few hours after an upload before adding from the Teams app works. ### Uploading for myself fails with an error about the app's tenant. Teams doesn't let one person install Brev for themselves from a package. Upload it to your organization's catalog instead (step 3). ### Brev can't read a team's channels after channel reading is turned on. The team owner has to approve Brev's permissions when adding it to the team. If your organization has turned off resource-specific consent for all apps, Brev can be added to teams but can't read their channels: a Global Administrator can change that in Microsoft Entra.