--- title: "Microsoft Teams integration for Grafana IRM | Grafana Cloud documentation" description: "Configure the Microsoft Teams integration for Grafana IRM to respond to alert groups and manage incidents without leaving Microsoft Teams" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Microsoft Teams integration for Grafana IRM The Microsoft Teams integration for Grafana IRM brings alert response and incident collaboration into the Teams channels your team already uses. You act on alert groups from interactive cards, and IRM announces incidents in a thread that stays current as the incident changes. With Microsoft Teams connected to IRM, you can: - Acknowledge, resolve, silence, and escalate alert groups without opening Grafana - Route alert groups to the Microsoft Teams channel of your choice - Get alert notifications in a direct message from the bot as part of your personal notification rules - Announce incidents in a channel, where the announcement tracks the title, roles, status, and severity as they change - Declare and manage incidents by mentioning `@Grafana IRM` ## Understand the Microsoft Teams integration options IRM offers two Microsoft Teams integrations: one for escalation management and one for incident management. They appear as separate **MS Teams** tiles under **IRM** > **Integrations** > **Apps**, but they configure different features of the same Grafana IRM app in Microsoft Teams. The **Escalation management** integration posts alert groups to your channels and sends alert notifications as direct messages. The **Incident management** integration announces incidents in a channel and keeps the announcement up to date as the incident changes. If you use IRM for both alert escalation and incident response, configure both integrations. To start posting alert groups to Microsoft Teams channels, refer to [Set up alert group notifications in Microsoft Teams](#set-up-alert-group-notifications-in-microsoft-teams). To announce and manage incidents, refer to [Set up incident announcements in Microsoft Teams](#set-up-incident-announcements-in-microsoft-teams). ## Before you begin To configure IRM with Microsoft Teams, you need the following permissions: - In Microsoft Teams, you need permission to add the Grafana IRM app to a team. If your organization restricts apps, a Teams administrator must allow the app. - To grant the Microsoft Graph application permissions, you need the Microsoft Entra Privileged Role Administrator or Global Administrator role. - To install the incident management integration, you need IRM Admin permissions. - To connect channels and configure routes for alert groups, you need the IRM Integrations Editor role or the `grafana-irm-app.integrations:write` permission. - To mark a channel as default or disconnect a channel, you need the IRM ChatOps Editor role or the `grafana-irm-app.chatops:update-settings` permission. For more information about IRM roles, refer to [Roles and permissions](/docs/grafana-cloud/observe-and-act/respond-to-incidents/set-up/manage-access/roles-and-permissions). For more information about the app permissions, refer to [Permissions and scope](#permissions-and-scope). ## Set up alert group notifications in Microsoft Teams In this section, you add the **Grafana IRM** app to Microsoft Teams and connect a team to your Grafana Cloud stack by sending a verification code to the bot from any channel in that team. After you connect a team, IRM registers every channel in it, and you can use integration [routing rules](/docs/grafana-cloud/observe-and-act/respond-to-incidents/escalation-and-routing/routing-rules) to control which alert groups go to which channels. ### Connect your Microsoft Teams channels To connect channels to IRM, complete the following steps: 1. In Microsoft Teams, add the **Grafana IRM** app to your organization from [Microsoft AppSource](https://appsource.microsoft.com/en-us/product/office/WA200004307). 2. Install the app to the team whose channels you want to use. For instructions, refer to Microsoft’s [Add an app to Microsoft Teams](https://support.microsoft.com/en-us/office/add-an-app-to-microsoft-teams-b2217706-f7ed-4e64-8e96-c413afd02f77). 3. In Grafana Cloud, navigate to **IRM** > **Integrations** and select the **Apps** tab. 4. Click the **MS Teams** tile labeled **Escalation management**. 5. Click **Add MS Teams channel**. 6. Copy the code from the **Connect MS Teams workspace** dialog box. 7. From any channel in that team, send the following message, replacing `` with the code you copied: text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text @Grafana IRM linkTeam ``` 8. In Grafana Cloud, click **Done**. The team’s channels appear in the **Microsoft Teams Channels** table in IRM, which lists the **Team** and **Channel name** for each one. Click **Make default** to set the channel that receives alert groups when a route doesn’t name one, and **Disconnect** to remove a channel from the list. A Microsoft Teams team can connect to one Grafana Cloud stack at a time. To connect a team to a different stack, disconnect it from the first one. ### Choose a channel for a route Each integration route can post to a different channel, which is how you send different alerts to different teams. For more information about routes, refer to [Routing rules](/docs/grafana-cloud/observe-and-act/respond-to-incidents/escalation-and-routing/routing-rules). 1. In Grafana Cloud, navigate to **IRM** > **Integrations** and select your alert source integration. 2. Open the route you want to configure, or add a new one. 3. Turn on **Post to Microsoft Teams channel**. 4. Choose a channel from **Select Microsoft Teams Channel**. If you turn on **Post to Microsoft Teams channel** without choosing a channel, alert groups go to the channel marked **Default**. You can also configure this with the API. Each route exposes an `msteams` object with an `id` field for the channel and an `enabled` field that turns posting on and off. For more information, refer to [Routes](/docs/grafana-cloud/observe-and-act/respond-to-incidents/reference/oncall-api/routes). ## Link your Microsoft Teams account Link your Microsoft Teams account to your Grafana account so you can act on alert groups directly in Microsoft Teams. After you link it, you can acknowledge, resolve, or silence an alert group with the buttons on its card. Linking is a one-time step, and you do it yourself after an administrator sets up the integration. Administrators can’t link accounts for other people. 1. In Grafana Cloud, click your avatar and open your **Profile**. 2. Select the **IRM settings** tab. 3. Click **MS Teams connection**. 4. Copy the generated code. 5. In Microsoft Teams, open a direct chat with the **Grafana IRM** bot. 6. Send the following command, replacing `` with the code you copied: text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text linkUser ``` The bot confirms the link and names the Grafana account you’re now linked to. To unlink, open **Overview** under **IRM settings**, click the connected **MS Teams** entry, and then click **Disconnect**. You can also send `unlink ` in a direct chat with the bot. > Note > > A Microsoft Teams account can have one active Grafana user link at a time. If you use a code from another stack, IRM switches the link to the Grafana user in that stack. Alert group actions for the previous stack then stop working until you link the account there again. ## Respond to alert groups Alert groups arrive in Microsoft Teams as an Adaptive Card, either in the channel you chose for a route or in a direct chat for a personal notification. The card gives you what you need to triage without opening Grafana: the alert group’s number and title, its status, how many alerts it contains, the integration that sent it, and a link to open it in Grafana. As the alert group changes, IRM updates the same card, so what you’re looking at is always up to date. You only see the buttons that apply to the alert group’s current state. A resolved alert group offers **Unresolve**, and a firing one offers the full set: Expand table | Button | Description | |-------------------------------------|----------------------------------------------------------------------------------| | **Acknowledge** / **Unacknowledge** | Acknowledge the alert group, or revert your acknowledgment | | **Resolve** / **Unresolve** | Resolve the alert group, or reopen it | | **Silence** / **Unsilence** | Silence for 1, 4, 12, or 24 hours or indefinitely, or remove an existing silence | | **Skip to next escalation** | Move to the next escalation step without waiting for the current step’s timer | | **Declare incident** | Open the incident declaration form in Grafana for this alert group | **Skip to next escalation** shows you what happens next and who gets notified, and waits for you to confirm before anything escalates. **Acknowledge**, **Resolve**, **Silence**, and **Skip to next escalation** require a linked Microsoft Teams account and permission to update the alert group. **Declare incident** opens the declaration form in Grafana and doesn’t use your Microsoft Teams account link. ### Customize what the alert group card shows Microsoft Teams has its own alert templates in your IRM integration settings, so you can change what the card shows without affecting other notification channels. For more information, refer to [Customize alert templates](/docs/grafana-cloud/observe-and-act/respond-to-incidents/escalation-and-routing/customize-alert-templates). Each integration has three Microsoft Teams template fields: Expand table | Field | Controls | |-------------|-------------------------------| | `title` | The card heading | | `message` | The card body | | `image_url` | An image rendered on the card | Microsoft Teams cards support limited Markdown through Adaptive Card text fields. IRM strips channel and user mention formatting from template output, and renders template links as `title - url`. ## Get alert notifications in a direct message Add Microsoft Teams to your personal notification rules to get a direct message from IRM when an alert escalates to you, so you can act from the card. For more information, refer to [Personal notification rules](/docs/grafana-cloud/observe-and-act/respond-to-incidents/notify-responders/personal-notification-rules). A notification rule only defines how IRM notifies you when you’re paged for an alert group. Default channels and channels connected to a route keep receiving alert groups either way. 1. Link your Microsoft Teams account, as described in [Link your Microsoft Teams account](#link-your-microsoft-teams-account). 2. In your Grafana Cloud **Profile**, select the **IRM settings** tab and click **Notification rules**. 3. Add a notification rule and choose **Microsoft Teams** as the notification channel. Selecting Microsoft Teams as a notification channel doesn’t link your account, so link it first. If **MS Teams connection** isn’t available in your profile, ask an administrator whether Microsoft Teams connections are enabled for your organization. For more information, refer to [Notification channels](/docs/grafana-cloud/observe-and-act/respond-to-incidents/notify-responders/notification-channels). ## Set up incident announcements in Microsoft Teams In this section, you install and configure the Microsoft Teams incident management integration. With this integration, IRM announces each incident in one Microsoft Teams channel and replies in that announcement’s thread as the incident changes. IRM doesn’t create, rename, or archive Microsoft Teams channels. This configuration uses the app’s linked Azure registration and Microsoft Graph, and requires tenant-wide admin consent. ### Install the integration and choose a channel To start receiving incident announcements, complete the following steps: 1. In Grafana Cloud, navigate to **IRM** > **Integrations**. 2. Select the **Apps** tab. 3. Click the **MS Teams** tile labeled **Incident management**. 4. Click **Install Integration**. 5. When you’re redirected to Microsoft sign-in, sign in with an account that can grant tenant-wide admin consent. 6. Review the requested permissions, then click **Accept**. Microsoft redirects you back to Grafana IRM. 7. Configure the integration settings: - **Select the MS Team**: the team that contains the channel you want to use - **MS Teams channel to create the thread in**: the channel that receives incident announcements - **Include incidents**: whether to announce all incidents, drill incidents, or non-drill incidents. The default is non-drill incidents - **Post important updates to the incident thread**: whether incident activity is posted into the thread. This is on by default IRM announces new incidents in the channel you selected. You can change these settings at any time from the same tile. ### Configure what gets posted to the incident thread IRM keeps the announcement card up to date for you. Whenever the incident’s title, roles, status, or severity change, the card changes with it, so the channel always shows where the incident stands. For additional incident updates, turn on **Post important updates to the incident thread**. This setting is all-or-nothing: you can’t select individual activity types. Depending on the incident’s state, IRM can reply in the announcement thread with the following activity: Expand table | Activity type | Updates shared | |---------------|---------------------------------------------------------------------------| | Incident | Created, Closed, Title changed, Severity changed, Status changed, Summary | | Role | Assigned (Commander), Assigned (Investigator) | | Label | Added, Removed | | Data | Query | | User | Note | | Task | Completed | IRM doesn’t post incident start, incident end, or action run activity to the thread. After an incident is resolved, role and label changes remain in the IRM timeline but aren’t posted to Microsoft Teams. To stop thread replies but keep announcements, turn off **Post important updates to the incident thread**. To stop announcements, disconnect the integration. ## Manage incidents from Microsoft Teams Incident commands let you declare an incident, check its status, and update it without leaving Microsoft Teams. Always mention the bot when you use an incident command, for example `@Grafana IRM incident list`. Commands that create, list, or select a stack work in a direct chat or channel. Commands that act on the current incident only work in that incident’s announcement thread. Expand table | Command | Description | Where to use it | |-------------------------------------|----------------------------------------------------------------------------------------------------|---------------------------------------------------------| | `incident help` | List all available incident commands | A direct chat, channel, or incident announcement thread | | `incident new ""` | Create an incident, or use plain text, for example `incident new something went wrong` | A direct chat or channel | | `incident list` | List all active incidents | A direct chat or channel | | `incident roles` | See who’s involved in the current incident | The incident announcement thread | | `incident talk` | Find an online place to discuss the incident | The incident announcement thread | | `incident status` | Get a live inline status update | The incident announcement thread | | `incident severity <SEVERITY>` | Update the incident severity, for example `incident severity major` | The incident announcement thread | | `incident tasks` | Manage tasks. Use `incident tasks add '<TASK>'` with an optional `@user`, or `incident tasks list` | The incident announcement thread | | `incident notes` | Add and view notes. Use `incident notes add "<NOTE>"` and `incident notes list` | The incident announcement thread | | `incident stacks` | List Grafana stacks | A direct chat or channel | | `incident stack <STACK_NAME>` | Set the default stack for new incidents | A direct chat or channel | Bot replies are visible in the chat, channel, or thread where you send the command. > Note > > Incident commands don’t require you to link your Microsoft Teams account. IRM recognizes you by matching your Microsoft Teams email address to the one on your Grafana Cloud account. If incident commands fail to recognize you, verify that the two email addresses match. ## Bot commands and where to use them In a channel, the bot only sees messages that mention it, so start your message with `@Grafana IRM`. In a direct chat with the bot, you can send most commands on their own. The `help` card lists the basic account and team linking commands. It doesn’t list `unlink` or incident commands. Expand table | Command | Description | Where to use it | |-----------------------|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| | `help` | List the basic account and team linking commands | A direct chat or a channel | | `linkUser <CODE>` | Link your Microsoft Teams account to your Grafana account | A direct chat only | | `linkTeam <CODE>` | Connect a Microsoft Teams team and its channels to your stack | A channel only, after the app is installed to the team | | `unlink <STACK_SLUG>` | Disconnect from a stack | Either, after linking to that stack. A direct chat unlinks your account; a channel unlinks the team | | `incident <COMMAND>` | Manage incidents | General commands: direct chat or channel. Current incident commands: announcement thread. Always mention the bot | For incident command help, send `@Grafana IRM incident help`. ## Permissions and scope The Grafana IRM app requests Microsoft Graph **Application** permissions, which are app-only and need tenant admin consent. It doesn’t request **Delegated** permissions. ### Microsoft Graph application permissions The **Description** column matches Microsoft’s wording on the consent screen, so you can map what Microsoft shows you to the permission name. For more information about any permission, refer to the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference). By granting access to the app, you authorize the following permissions in your Microsoft Entra tenant: Expand table | Permission | Description | Purpose | |-------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------------------| | `Calendars.ReadWrite` | Read and write calendars in all mailboxes | Create online meetings. You can revoke this permission if you don’t use that feature. | | `ChannelSettings.ReadWrite.All` | Read and write the names, descriptions, and settings of all channels | Populate the channel list. | | `Chat.Create` | Create chats | Create incident-specific conversations. | | `TeamsAppInstallation.ReadWriteSelfForTeam.All` | Allow the Teams app to manage itself for all teams | Install the Grafana IRM bot in the selected team. | | `TeamSettings.Read.All` | Read all teams’ settings | Populate the team list. | | `User.Read.All` | Read all users’ full profiles | Read user profiles, such as display name and email, to match Grafana and Teams accounts. | These permissions apply to your whole Microsoft Entra tenant, but the bot only acts in teams where it’s installed. After installation, a Microsoft Entra administrator with sufficient permissions can revoke individual permissions in the Microsoft Entra admin center: **Enterprise applications** > **Grafana IRM** > **Permissions**. Revoking a permission might break the Grafana IRM features that depend on it. ### Install the app manually instead of granting self-install If you don’t want to grant `TeamsAppInstallation.ReadWriteSelfForTeam.All`, an administrator can revoke it in the Microsoft Entra admin center. An administrator must then add the Grafana IRM app to each team manually in Microsoft Teams. > Caution > > This alternative isn’t officially supported. You have to add the app to every team you want to use with IRM, and repeat that for each team you add later. ### Teams bot capabilities These capabilities come from the Teams app manifest (`personal` and `team` scopes), not from Microsoft Graph. The bot can only act in teams where it’s installed. #### Channel access In the channels of a team where it’s installed, the bot has the following capabilities: Expand table | Capability | Purpose | |-------------------------------------|--------------------------------------------------| | Receive messages mentioning the bot | Access messages directed at the bot | | Send channel notifications | Send notifications to the designated channel | | Access team information | Access team and channel names and roster details | #### Message and conversation In direct chats and incident conversations, the bot has the following capabilities: Expand table | Capability | Purpose | |----------------------|---------------------------------------------| | Receive messages | Process messages mentioning the bot | | Send messages | Send notifications within incident channels | | View direct mentions | View messages mentioning `@Grafana IRM` | ## Troubleshoot Microsoft Teams issues Most Microsoft Teams problems come from an unlinked account, a message that didn’t mention the bot, or a permission that was never granted or was later revoked. ### Card buttons return an error If clicking a button returns a message saying your Teams user must be linked to a Grafana IRM account, refer to [Link your Microsoft Teams account](#link-your-microsoft-teams-account). Each user links their own account, so this can affect one responder while others in the same channel are unaffected. If the button reports that you don’t have permission, your Grafana user lacks the alert group write permission for that integration. If it reports that the operation requires team membership, your organization requires responders to belong to the Grafana team that owns the integration. Users who were explicitly paged for the alert group can act on it without belonging to that team. ### The bot doesn’t respond In a channel, the bot only sees messages that mention it, so start your message with `@Grafana IRM`. If it still doesn’t respond, confirm the app is installed to the team, then send `help` in a direct chat with the bot. A reply confirms that the bot is reachable and lists the basic linking commands. ### Installation fails For the incident management setup, verify that you signed in with a Microsoft Entra Privileged Role Administrator or Global Administrator account that can grant tenant-wide admin consent. For either setup path, confirm that a Teams administrator has allowed the Grafana IRM app if your organization restricts apps. Also check whether the app is blocked in the [Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps). ### Alert groups aren’t posting to a channel Work through the setup in order: - Confirm the channel appears in the **Microsoft Teams Channels** table. If it doesn’t, the `linkTeam` command didn’t complete: check that the app is installed to the team, that you mentioned the bot, and that the code hasn’t been regenerated since you copied it. - Confirm the route has **Post to Microsoft Teams channel** turned on with a channel selected, or that a **Default** channel is set. - Confirm the alert group was created in IRM, which tells you whether the route matched at all. - Confirm the app is still installed to the team. If it was removed, messages stop arriving with no notice. ### Incident announcements aren’t posting Check the **Include incidents** setting. It defaults to non-drill incidents, so drill incidents aren’t announced unless you select all or drill incidents. Then confirm the app is still connected and that Microsoft Graph consent hasn’t been revoked. ### Messages are delayed or missing during heavy alert volume Microsoft rate limits Teams messages sent for alert groups. For throttling and some gateway errors, IRM retries alert group messages up to 10 times. IRM uses the period in the `Retry-After` header when Microsoft provides one and uses retry backoff otherwise. If an initial channel post reaches the retry limit, IRM attempts to post `Could not post alert message. Max retries exceeded.` in the channel. Some alert group delivery failures aren’t retried, because retrying can’t succeed: the app was removed from the team, a user blocked the bot, or the message is too large for Microsoft Teams. If you see `Could not post alert message. Check your integrations template for possible errors.`, the Microsoft Teams alert template produced invalid output. These retry and error messages apply to alert groups. Incident announcements and incident thread updates don’t use the same delivery process. ### Notifications stopped after an administrator changed app permissions Revoking a Microsoft Graph permission breaks the IRM features that depend on it. If the team or channel lists are empty, `TeamSettings.Read.All` or `ChannelSettings.ReadWrite.All` was revoked. If incident announcements stopped, check whether consent was revoked. To review what your tenant currently allows, go to **Microsoft Entra admin center** > **Enterprise applications** > **Grafana IRM** > **Permissions**. ### Can’t connect a team or user to a second stack A Microsoft Teams team can connect to one Grafana Cloud stack at a time. If `linkTeam` reports that the team belongs to another stack, disconnect the team’s channels from that stack first. Remove them from its **Microsoft Teams Channels** table, or send `unlink <STACK_SLUG>` in a channel as a user whose Teams account is linked to that stack. A Microsoft Teams account also has one active Grafana user link at a time, but `linkUser` handles this differently. Using a code from another stack moves the link to the Grafana user from that stack instead of returning an error. ## Next steps - Configure [routing rules](/docs/grafana-cloud/observe-and-act/respond-to-incidents/escalation-and-routing/routing-rules) to send alert groups to the right Microsoft Teams channel - Configure [escalation chains](/docs/grafana-cloud/observe-and-act/respond-to-incidents/escalation-and-routing/escalation-chains) to control who gets paged