> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/alerting-integrations/microsoft-teams.md).

# Microsoft Teams

We support Microsoft Teams as an alerting destination. A [Policy Maker](https://docs.teleskope.ai/the-platform/policy-maker.md) policy can:

* **Post to a channel** — an alert card in the Teams channel you choose.
* **Message the data owner** — a direct message to the person who owns the flagged data.
* **Collect a response** — buttons on the card record how the recipient responded, back on the finding in Teleskope.

Alerts are sent by a bot that lives in your own Azure tenant, so you control it.

## Required permissions

One Global Administrator who is also a Contributor on an Azure subscription can complete every step alone. Otherwise, each step needs:

| Step                                                           | Who can do it                                                                                            |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Create the Azure Bot                                           | **Contributor** or **Owner** on an Azure subscription or resource group                                  |
| Register the bot's app in Microsoft Entra ID                   | Any user, if your tenant lets users register apps; otherwise **Application Developer**                   |
| Create the client secret                                       | The app registration's owner, or an **Application Administrator** or **Cloud Application Administrator** |
| Grant admin consent for Microsoft Graph **User.Read.All**      | **Privileged Role Administrator** or **Global Administrator**                                            |
| Allow custom apps, upload the app and choose who gets it       | **Teams Administrator** or **Global Administrator**                                                      |
| Add the app to an alert channel's team                         | An owner of that team the app is available to, or a **Teams Administrator**                              |
| Save the credentials and download the app package in Teleskope | A Teleskope user who can create and edit policies                                                        |

{% hint style="info" %}
Application Administrators and Cloud Application Administrators can't grant consent for Microsoft Graph application permissions. Plan for a Privileged Role Administrator or Global Administrator at that step. Without that consent, channel alerts still work, but data-owner messages fail and responses are recorded under the clicker's display name instead of their email.
{% endhint %}

## Setup

{% stepper %}
{% step %}
**Create the Azure Bot**

1. In the Azure portal, create an **Azure Bot** resource.
2. Set **Type of App** to **Single Tenant** and create a new Microsoft App ID.
3. Open the bot's **Configuration** and set **Messaging endpoint** to `https://oauth.nexus.teleskope.ai/callback/teams`.
4. From **Configuration**, open the linked app registration (**Manage Password**). Under **Certificates & secrets**, create a **client secret** and copy its value. It is shown only once.
5. Note the **Microsoft App ID** and **App Tenant ID** from the bot's **Configuration** page.
6. Under **Channels**, add the **Microsoft Teams** channel and accept the terms.

{% hint style="warning" %}
Client secrets expire. Set a reminder to create a new one and save it in Teleskope before the old one runs out.
{% endhint %}
{% endstep %}

{% step %}
**Grant Graph permission**

1. Open the bot's app registration in **Microsoft Entra ID → App registrations**.
2. Under **API permissions**, add **Microsoft Graph → Application permissions → User.Read.All**.
3. Select **Grant admin consent** for your organization.

Teleskope uses this permission to find the data owner to message, and to record who clicked a response button.
{% endstep %}

{% step %}
**Save the credentials in Teleskope**

1. In Teleskope, go to **Policies → Integrations** and select the **Microsoft Teams** tile.
2. Enter the **App Id**, **Tenant Id** and **App Secret** from the previous steps.
3. Leave **Service Url (optional)** blank unless Teleskope support tells you otherwise.
4. Select **Save**.
   {% endstep %}

{% step %}
**Download and upload the app**

1. After you save, the settings stay open and **Download Teams app package** appears. Select it to download `teleskope-teams-app.zip`.
2. In the **Teams admin center**, go to **Teams apps → Manage apps** and select **Upload new app**.
3. Upload `teleskope-teams-app.zip` as it is. Don't unzip it.

Your tenant's org-wide app settings must allow custom apps, or the uploaded app can't be used.
{% endstep %}

{% step %}
**Choose who gets the app**

On the app's page in the Teams admin center, two settings decide who can receive alerts: **Available to** and **Installed for**. Pick one of these models.

| Model                                  | Set both settings to                | What works                                                                                          |
| -------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Security team only** (default)       | A security group                    | Channel alerts. Data-owner messages reach only members of that group; messages to anyone else fail. |
| **Everyone** (for data-owner messages) | Everyone, or an all-employees group | Channel alerts and data-owner messages to anyone in your organization.                              |

The app only sends alert cards and records button clicks for the alert each card belongs to. It gives users no access to Teleskope.

If your tenant doesn't show **Installed for**, use a Teams **app setup policy** instead: add the app under **Installed apps** and assign the policy to the same users.
{% endstep %}

{% step %}
**Add the app to alert channels**

1. For each team with a channel that should receive alerts, add the Teleskope app to that team. A team owner the app is available to can add it from Teams, or a Teams admin can add it from the app's page in the Teams admin center.
2. In Teams, open the channel's menu and select **Get link to channel**. The link looks like `https://teams.microsoft.com/l/channel/19%3A...%40thread.tacv2/Security%20Alerts?groupId=...&tenantId=...`.
3. In Policy Maker, add a **Microsoft Teams notification** alert to your policy and paste that link as the channel.

Channel alerts fail for any channel whose team doesn't have the app.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
The same steps are available in Teleskope under **Settings → Policy Maker Guide → Microsoft Teams**.
{% endhint %}

## Replacing the bot or its secret

* **New client secret:** save the new secret in Teleskope. No new app package is needed.
* **New bot:** a new bot makes a new app. Save its credentials, download the package again and upload it as a new app. Remove or block the old app, then repeat **Choose who gets the app** and **Add the app to alert channels**.

## Troubleshooting

When a Teams alert fails, the reason is recorded on the finding's activity. Find the message below and fix the step it points to.

| Message contains                                                    | What it means                                                                                      | Fix                                                                                                                                                |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get token`                                                         | The App Id, Tenant Id or App Secret is wrong, or the secret expired.                               | Check the values in **Save the credentials in Teleskope**. If the secret expired, create a new one (**Create the Azure Bot**, step 4) and save it. |
| `missing or invalid policymaker.TeamsConfig secrets`                | The saved Teams credentials are missing or incomplete.                                             | **Save the credentials in Teleskope**                                                                                                              |
| `cannot read Entra users`                                           | The Graph permission is missing or not consented.                                                  | **Grant Graph permission**                                                                                                                         |
| `no account status returned`                                        | The Graph permission is missing or not consented.                                                  | **Grant Graph permission**                                                                                                                         |
| `could not open a chat with`                                        | The app isn't installed for that person, or a permission policy blocks it.                         | **Choose who gets the app**                                                                                                                        |
| `no Entra user for`                                                 | The data owner's email isn't a user in your tenant, for example someone outside your organization. | Not a setup issue. Use a channel alert for this data.                                                                                              |
| `is a guest`                                                        | The data owner is a guest; Teams alerts reach members of your tenant only.                         | Not a setup issue. Use a channel alert for this data.                                                                                              |
| `is disabled`                                                       | The data owner's account is disabled.                                                              | Not a setup issue.                                                                                                                                 |
| `Entra users match`                                                 | More than one Entra account has the data owner's email.                                            | Remove the duplicate in Microsoft Entra ID.                                                                                                        |
| A channel alert fails with `403 Forbidden` and no row above matches | The app hasn't been added to that channel's team.                                                  | **Add the app to alert channels**                                                                                                                  |

Two problems don't leave a message on the finding:

* **Clicking a button does nothing, or Teams shows an error.** The bot's messaging endpoint is wrong. Set it to the URL in **Create the Azure Bot**, step 3.
* **The card says "Couldn't record that response. Try again or contact your security team." after a click.** Teleskope either couldn't record the response, or recorded it but couldn't finish the step that follows it. Contact Teleskope support.
