> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/self-managed/features/integrations/ms-teams.md).

# Self-managed Microsoft Teams

This guide explains how to configure the Microsoft Teams integration for a [Cortex self-managed](/self-managed.md) account. This integration requires a Teams app, which needs to be configured in your own Teams workspace when using Cortex Self-Managed.

If you are looking for instructions on configuring a Microsoft Teams integration for your Cortex cloud workspace, please see [Integrations > Microsoft Teams](/ingesting-data-into-cortex/integrations/microsoftteams.md).

## Setup instructions[​](https://docs.cortex.io/docs/self-managed/guides/microsoft-teams#setup-instructions) <a href="#setup-instructions" id="setup-instructions"></a>

### Create the app[​](https://docs.cortex.io/docs/self-managed/guides/microsoft-teams#create-the-app) <a href="#create-the-app" id="create-the-app"></a>

1. Use existing OAuth credentials or create a new Enterprise application in Azure. The following environment variables are referred to later on.

   `MICROSOFT_TEAMS_CLIENT_ID` - the Application ID

   `MICROSOFT_TEAMS_CLIENT_SECRET` - the Client Secret

   `MICROSOFT_TEAMS_REDIRECT_URI` - the Redirect URI, "\[Cortex Frontend URL]/oauth/internal/microsoft\_teams"
2. Create a Bot Service in Azure. The following environment variables are referred to later on.

   `MICROSOFT_TEAMS_BOT_APP_ID` - the Microsoft App ID for the bot

   `MICROSOFT_TEAMS_BOT_APP_PASSWORD` - the Bot Password
3. Create/Upload the Teams App

   Use the following manifest to create a new Teams app in your workspace.

   Make sure to replace the URLs found in `[]` with the [URLs you set up](/self-managed.md) for your self-managed Cortex instance.

   ```
   {
     "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
     "manifestVersion": "1.16",
     "version": "1.0.0",
     "id": "[MICROSOFT_TEAMS_BOT_APP_ID]",
     "developer": {
       "name": "Cortex",
       "websiteUrl": "https://www.cortex.io",
       "privacyUrl": "https://www.cortex.io/legal/privacy-policy",
       "termsOfUseUrl": "https://www.cortex.io/legal/terms-of-service",
       "mpnId": "6762083"
     },
     "name": {
       "short": "Cortex",
       "full": "Cortex | Engineering Operations Platform"
     },
     "description": {
       "short": "Stay on top of your Cortex Scorecard scores & Initiatives",
       "full": "Cortex Scorecards and Initiatives help your team establish best practices and improve quality. We’ll send you a weekly notification to let you know what’s on your plate for the week as well as notifications for any new Initiatives, upcoming Initiative deadlines, and score changes for services that you own. Book a demo: https://www.cortex.io/demo?utm_source=docs\nContact sales: https://go.cortex.io/contact-sales-request.html\nSupport hub: https://support.getcortexapp.com/hc/en-us\nSupport email: support@cortex.io\nGet started: https://docs.cortex.io"
     },
     "icons": {
       "outline": "cortex32x32.png",
       "color": "cortex192x192.png"
     },
     "accentColor": "#25074D",
     "bots": [
       {
         "botId": "[MICROSOFT_TEAMS_BOT_APP_ID]",
         "scopes": [
           "personal"
         ],
         "needsChannelSelector": false,
         "isNotificationOnly": false,
         "supportsFiles": false,
         "supportsCalling": false,
         "supportsVideo": false,
         "commandLists": []
       }
     ],
     "validDomains": [
       "[Cortex Backend URL]"
     ],
     "showLoadingIndicator": false,
     "isFullScreen": false,
     "defaultBlockUntilAdminAction": false,
     "defaultInstallScope": "personal",
     "configurableProperties": [],
     "webApplicationInfo": {
       "id": "[MICROSOFT_TEAMS_CLIENT_ID]"
     }
   }
   ```
4. Configure the Messaging endpoint - "\[Cortex API URL]/api/v1/microsoft/teams/webhook"
5. Upload a zipped manifest along with the icons to your Teams instance. Note: only Teams admins can do this.

{% hint style="warning" %}
If your Cortex Self-Managed installation is not available from the public internet, the Microsoft Teams notifications will not work, as Microsoft Teams needs to be able to hit the Cortex API when a command is run.
{% endhint %}

### Connect your Cortex instance[​](https://docs.cortex.io/docs/self-managed/guides/microsoft-teams#connect-your-cortex-instance) <a href="#connect-your-cortex-instance" id="connect-your-cortex-instance"></a>

You'll need to configure your on-prem deployment to be able to talk your Teams App.

1. Create a k8s secret and add the secret in your `values.yaml` file for the Helm chart. You may already have a secret set up if you had configured a persistent store previously, so be sure to verify in your Helm chart.
2. Add the follow key/values to the secret (keeping in mind they need to be base64 encoded in k8s):
   1. `MICROSOFT_TEAMS_CLIENT_ID`
   2. `MICROSOFT_TEAMS_CLIENT_SECRET`
   3. `MICROSOFT_TEAMS_REDIRECT_URI`
   4. `MICROSOFT_TEAMS_BOT_APP_ID`
   5. `MICROSOFT_TEAMS_BOT_APP_PASSWORD`
3. Restart your Cortex backend deployment


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/self-managed/features/integrations/ms-teams.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.