Documentation Grafana Cloud Observe and act Manage on-call and incidents Connect integrations Chat and collaboration Microsoft Teams

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.

To announce and manage incidents, refer to 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.

For more information about the app permissions, refer to 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 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.

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.

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 <CODE> with the code you copied:

   text Copy

   @Grafana IRM linkTeam <CODE>

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.

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.

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 <CODE> with the code you copied:

   text Copy

   linkUser <CODE>

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 <STACK_SLUG> in a direct chat with the bot.

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:

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.

Each integration has three Microsoft Teams template fields:

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.

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.
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.

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:

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.

Bot replies are visible in the chat, channel, or thread where you send the command.

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.

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.

By granting access to the app, you authorize the following permissions in your Microsoft Entra tenant:

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.

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:

Message and conversation

In direct chats and incident conversations, the bot has the following capabilities:

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. 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.

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 to send alert groups to the right Microsoft Teams channel
• Configure escalation chains to control who gets paged