Microsoft Teams Integration Guide | PagerDuty

Microsoft Teams + PagerDuty Integration Benefits

  • Reduce downtime and streamline incident remediation by adding PagerDuty’s incident management functionality to Microsoft Teams' collaboration tools.
  • Send PagerDuty incident notifications with critical details to team channel members.
  • Team channel members will be able to view and create incidents. They can acknowledge, resolve and perform other actions within Microsoft Teams.

Requirements

A PagerDuty Admin is required to authorize the connection of PagerDuty to Microsoft Teams. If you do not have this role, please reach out to a PagerDuty Admin or Account Owner within your organization to configure the integration. For more information about these PagerDuty user roles, please read our Advanced Permissions guide.

A Microsoft Teams Admin must enable third-party apps for your organization, in order to download the PagerDuty app.

A Microsoft Admin will need to authorize the Microsoft Graph API permissions required by the PagerDuty app.

🚧

Private & Shared Channels

Please note that the PagerDuty application cannot currently be integrated with private or shared channels in Microsoft Teams.

We do support the creation of private Microsoft Teams chats for an incident, using our Teams actions in Incident Workflows.

How it Works

  • PagerDuty’s Microsoft Teams application installs into a team and can be configured for one or more of the team’s channels.
  • A PagerDuty service uses webhooks to send information about an incident to a Pagerduty-developed Microsoft Teams service. This service receives the webhook from PagerDuty, composes a message, and sends to team channels via Microsoft’s Bot Kit Framework. Any subsequent changes to the PagerDuty incident will update on progress within the channel, and additional incident details can be viewed from the Microsoft Teams notification card.
  • Read more about how authentication with Microsoft Teams works.

Version

This guide is for our latest Microsoft Teams integration, version 1.2.0.

📘

Looking for a Different Version?

The legacy Microsoft Teams integration guide is also available for those who have previously installed and are still using that version. The legacy Microsoft Teams application is no longer available for initial installation from the Microsoft store. For customers using the legacy application, Microsoft has kept all configurations and will continue to support the integration for these customers.

If you would like to upgrade your application from the legacy to the most current version, please follow our Upgrade Instructions

Integration Walkthrough

Connect PagerDuty to a Microsoft Team

Note: These steps are only necessary upon initial app installation to a Microsoft Team. If the PagerDuty app is already installed to your team, you can proceed with linking PagerDuty services to your team’s channels .

  1. From the Microsoft Teams Marketplace app store, search and click the PagerDuty app. If your PagerDuty account is hosted in the EU service region, click the PagerDuty EU app.
  2. Click Add to a Team and select a Team or Channel for initial installation. The app will be installed to standard channels within the selected team.
PagerDuty installation

PagerDuty installation

  1. Click Set up a bot to install the app.

    After the installation, you will receive a message in a private chat with the PagerDuty bot, confirming that the installation is complete.

    PagerDuty Private Chat Prompt to Authorize the App

    PagerDuty Private Chat Prompt to Authorize the App

  2. Click into the chat message with the PagerDuty bot.

    • If you are a PagerDuty Admin: Click Authorize to connect your team to PagerDuty.

    • If you are not a PagerDuty Admin: Click I'm not a PagerDuty Admin.

      The message will be expanded to include instructions that you can send to your PagerDuty Admin, to authorize your team's connection to PagerDuty.

      App Authorization Instructions for PagerDuty Admin

      App Authorization Instructions for PagerDuty Admin

  3. After your PagerDuty Admin clicks Authorize, a PagerDuty login page will open in a separate window. Log in with PagerDuty Admin or Account Owner credentials to connect PagerDuty to the team you selected.
    Note: If you are already logged into PagerDuty, this step will be bypassed.
    You will be directed to the Microsoft Teams Integration page in your PagerDuty account and you should see a success message:
    "You've successfully connected the [YOUR TEAM NAME] team to PagerDuty".
    If you receive the following error messages:

    • "We can't connect Microsoft Teams to PagerDuty. Authorization cannot be completed at this time. You may close this window."
    • "We can't connect Microsoft Teams to PagerDuty. The authorization link has expired or is not valid. Return to Teams to generate a new one. You may close this window."
      Your PagerDuty user account may not have the correct permissions to complete the setup, or the connection link has expired. Ensure that your PagerDuty role is an Account Owner or Global Admin, check to see if another private chat with the PagerDuty bot has been sent with a renewed link, and retry authorizing the connection from Microsoft Teams.
  4. For the final phase of setup, you will receive a message from the PagerDuty app to complete setup by authorizing PagerDuty to the Microsoft Graph API.

    Microsoft API Authorization Prompt

    Microsoft API Authorization Prompt

  • If you are a Microsoft Admin: Click Authorize and complete setup.

  • If you are not a Microsoft Admin:

    • Ask your Microsoft admin to message the PagerDuty app with the command appconnect to complete this step
    • Or ask them to visit the PagerDuty web app, navigate to Integrations → Microsoft Teams Integration, and click Authorize
  1. After clicking Authorize and complete setup, a Microsoft permissions prompt will open in a separate window. Click Accept.

    Note: For a full list of the permissions being requested and their purpose, please see the FAQ: What Microsoft Graph permissions are required by the PagerDuty app?

    Microsoft API Permissions Consent Screen

    Microsoft API Permissions Consent Screen

  2. Setup is now complete!

To connect additional teams to the same PagerDuty account

  1. You can repeat step 1 of this section from within Microsoft Teams.

    Alternatively, a PagerDuty Admin can visit the PagerDuty web app, navigate to Integrations → Microsoft Teams Integration, and click + Connect More Teams.

    Connect More Teams button on the Microsoft Teams Integration page in PagerDuty

    Connect More Teams button on the Microsoft Teams integration page in PagerDuty

  2. From there, follow steps 2 to 5, and repeat this process for each additional team you would like to connect to PagerDuty.

To enable PagerDuty to create Microsoft Teams meetings

During setup, your Microsoft admin granted PagerDuty access to the Microsoft Graph API. One of the permissions we request is for the ability to create calendar events. This allows our application to create a calendar event and attach a Microsoft Teams meeting, which will be used as the PagerDuty incident’s conference bridge.

The permission to create calendar events is optional. If you need to revoke this permission, your Microsoft admin must configure an access policy to allow applications to create new Teams meetings on behalf of users. Please see the official Microsoft documentation for instructions, or have your Microsoft admin run the following Powershell command:

Note: PAGERDUTY_ACCESS_POLICY below is a placeholder policy name, and can be modified.

Install-Module -Name PowerShellGet -Force -AllowClobber
Install-Module -Name MicrosoftTeams -Force -AllowClobber
Import-Module MicrosoftTeams
$credential = Get-Credential
Connect-MicrosoftTeams -Credential $credential
New-CsApplicationAccessPolicy -Identity "PAGERDUTY_ACCESS_POLICY" -AppIds "05ffe668-5b27-45ff-a64d-b2ed6c475d7a" -Description "Policy for enabling online meetings with application token for PagerDuty"
Grant-CsApplicationAccessPolicy -PolicyName "PAGERDUTY_ACCESS_POLICY" -Global

Or the following command for customers in the EU:

Install-Module -Name PowerShellGet -Force -AllowClobber
Install-Module -Name MicrosoftTeams -Force -AllowClobber
Import-Module MicrosoftTeams
$credential = Get-Credential
Connect-MicrosoftTeams -Credential $credential
New-CsApplicationAccessPolicy -Identity "PAGERDUTY_ACCESS_POLICY" -AppIds "8f79a561-d2f1-4a1e-8092-c2039043a40e" -Description "Policy for enabling online meetings with application token for PagerDuty"
Grant-CsApplicationAccessPolicy -PolicyName "PAGERDUTY_ACCESS_POLICY" -Global

Link PagerDuty Services to Microsoft Teams Channels

After you connect PagerDuty to your team, you can begin linking PageDuty services to your team's channels. You can link a channel to one or many PagerDuty services.

🚧

Required User Permissions

PagerDuty Admins can configure service-channel mappings through the PagerDuty web app or the PagerDuty app in Microsoft Teams.

PagerDuty Managers can configure service-channel mappings through the PagerDuty app in Microsoft Teams only.

  1. PagerDuty Managers (base role) can link any PagerDuty service to Microsoft Team channels.
  2. PagerDuty Managers (team role) can link their PagerDuty team’s services to Microsoft Team channels.

Using the PagerDuty Web App

  1. In the PagerDuty web app, navigate to Integrations → Microsoft Teams Integration.
  2. Expand the team that you have connected to PagerDuty, and click + Connect Notification Channel.
  3. Select which PagerDuty service and which Microsoft Teams channel that you would like to connect to each other from the dropdown lists.
  4. Click Connect to complete the service-channel connection.
  5. Repeat these steps to connect additional services and channels.

Using the PagerDuty app in Microsoft Teams

  1. In Microsoft Teams, under the team you have connected to PagerDuty, select the channel that you would like to connect to a PagerDuty service.
  2. Click Start a post.
  3. Enter the following app command, ensuring the PagerDuty bot is mentioned in the message: @PagerDuty connect [link to the service URL in PagerDuty]
  4. Click Connect Service.
  5. Repeat these steps to connect additional services and channels.

Once the PagerDuty service is connected to a team’s channel, incident notifications will be visible to all members in the channel.

Link PagerDuty and Microsoft Teams User Accounts

To perform incident actions in Microsoft Teams, responders must link their PagerDuty and Microsoft Teams user accounts.

  1. To receive a personal account mapping link, users can follow the below options:
    • Click Link Accounts on the welcome message posted by the PagerDuty bot in the General channel, upon successfully connecting its team to PagerDuty;
    • Click Link Accounts on the welcome message posted by the PagerDuty bot in a channel, upon successfully connecting the channel to a PagerDuty service; or
    • In a private chat message with the PagerDuty bot, enter linkUser
      You will receive a private chat message from the PagerDuty bot, containing your personal user account mapping button.
  2. From the PagerDuty bot's private chat message, click Link Accounts.
  3. A PagerDuty login page will open in a separate window. Log in with your PagerDuty credentials to link your PagerDuty and Microsoft Teams user accounts.
    Note: If you have already logged in, this step will be bypassed.
    You will be directed to the Microsoft Teams Integration page in your PagerDuty account and you should see a success message:

    You've successfully linked your user accounts.

    All PagerDuty actions you perform as [MS-TEAMS-NAME] in Microsoft Teams will be associated with [PAGERDUTY-NAME] (PAGERDUTY-EMAIL) in PagerDuty.

    If you this is not correct, please enter the @PagerDuty unlinkUser command in Microsoft Teams to unlink your account.
    If you receive an error, verify that the PagerDuty credentials are correct and the user account is provisioned in the correct PagerDuty account. To find which PagerDuty account is connected to Microsoft Teams, enter the app command @PagerDuty open in any channel. Your organization’s PagerDuty account will open in a new browser window, and you can see your account’s subdomain in the address bar (e.g. subdomain.pagerduty.com).

👍

Microsoft Teams User Guide

Once initial configuration is complete, please read our Microsoft Teams User Guide for instructions on how to use the integration.

Upgrade PagerDuty's Microsoft Teams Application

To use the features in the latest Microsoft Teams integration, customers using the legacy Microsoft Teams connector application will need to upgrade.

Microsoft no longer supports the legacy Microsoft Teams application. If you have been using the legacy Microsoft Teams application and you would like to upgrade to our current one, you must first remove the legacy connectors.

  1. In your Microsoft Teams console, search for and select the Pagerduty (Legacy) app.
  2. Click Add to a Team, and then select the team that is using the legacy connectors.
  3. Once a team has been selected, click Set up Connector, which will take you to the connectors page. In the left menu, navigate to Manage Configured.
  4. Click the Manage button next to the connector. The remove option is located towards the bottom of the page.
  5. After you have removed all the connectors, you will need to remove the app from the team. Navigate to Teams click the ellipsis to the right of your team's name Manage team Apps tab click the to the right of the PagerDuty (Legacy) app.
  6. Repeat the above steps for each team that uses connectors.

Microsoft Teams User Guide

Please read our Microsoft Teams User Guide for more information about using the integration after it has been configured.

FAQ

Why do I see a NOT AUTHORIZED message next to my Microsoft Teams tenant ID?

This message indicates you have not authorized PagerDuty with the Microsoft Graph API. This authorization is required for PagerDuty to automate incident tasks, such as creating Teams meetings and dedicated chats for an incident.

Please have your Microsoft Admin authorize this tenant to enable all features of our PagerDuty Teams application.

Note: If you had previously authorized your Microsoft Teams Tenant, you may be seeing this message again due to recent and ongoing changes to our Microsoft Teams permissions model. Please see the FAQ for more information: What Microsoft Graph permissions are required by the PagerDuty app?

What Microsoft Graph permissions are required by the PagerDuty app?

🚧

Ongoing changes to our Teams permission model

Previously, PagerDuty would automate incident tasks in Teams by requesting user-level (AKA delegated) permissions from individual users.

We are now transitioning to use application-level permissions, granted by your Microsoft Teams admin.

These new application permissions are all "Least Privileged Permissions" - we are only requesting the minimum permissions necessary to support the features of the PagerDuty application.

In order to ensure no interruption to service, we are currently requesting both user-level and application-level permissions, but user-level permissions will be removed when this transition is complete.

In the table below, all permissions of type Delegated will be removed, targeting September 1st, 2024. Application type permissions will remain.

PagerDuty Cloud Operations and Incident Management functionality in Microsoft Teams requires access to the following scopes.

The Description field is what is displayed on the Microsoft Permissions Consent screen that you are presented when first installing and configuring the PagerDuty Teams app.

Required Permissions

PurposeDescriptionPermissionTypeLeast Privileged Permission
Creating a new dedicated chat for an incidentRead and write user chat messagesChat.ReadWriteDelegated
Ability to refresh tokens to ensure features continue workingMaintain access to data you have given it access tooffline_accessDelegated
Creating an online meetingRead and create user's online meetingsOnlineMeetings.ReadWriteDelegated
Adding the PagerDuty app to a dedicated incident chat for sending incident card messagesManage installed Teams apps in chatsTeamsAppInstallation.ReadWriteForChatDelegated
Fetching the name of the Teams organization, so it can be displayed and selected in PagerDuty workflow configuration screensSign in and read user profileUser.ReadDelegated
Creating an online meetingRead all users' basic profilesUser.ReadBasic.AllDelegated
Adding claim information about the user when making requestsopenid, email, profileDelegated
Creating a new dedicated chat for an incidentCreate chatsChat.CreateApplication
Adding incident responders to dedicated incident chatsAdd and remove members from all chatsChatMember.ReadWrite.AllApplication
Creating an online meetingRead and create online meetingsOnlineMeetings.ReadWrite.AllApplication
Fetching the name of the Teams organization, so it can be displayed and selected in PagerDuty workflow configuration screensRead organization informationOrganization.Read.AllApplication
Adding the PagerDuty app to a dedicated incident chat for sending incident messagesManage Teams apps for all chatsTeamsAppInstallation.ReadWriteSelfForChatApplication
Automatically adding responders to Teams meetings and chats without requiring their accounts to be linked. (1)Read all users' full profilesUser.Read.AllApplication

(1) We request a limited set of information from the Microsoft Graph API when using this scope: id, mail and userPrincipalName.

Optional Permissions

The PagerDuty app for Microsoft Teams requests some permissions which are optional, depending on how customers would like our application to function. These optional permissions can be revoked following installation of our application.

PurposeDescriptionPermissionTypeLeast Privileged Permission
Create an online meetingRead and write calendars in all mailboxes.

If revoked, customers must perform manual configuration to enable PagerDuty to create meetings.
Calendars.ReadWriteApplication

How do I remove the PagerDuty service from my team channel connection?

A PagerDuty Admin or Account Owner can remove a service to channel connection via PagerDuty’s Microsoft Teams extension page.

  1. Navigate to Integrations Extensions Microsoft Teams Integration tile.
  2. Next, click next to Notification Channels Remove next to the service-channel connection you’d like to disconnect.
Remove connection

Remove connection

  1. In the confirmation dialog, click Remove.

How do I disconnect the PagerDuty app from a team?

A PagerDuty Admin or Account Owner can disconnect the app in PagerDuty on the Microsoft Teams extension's page. Disconnecting or un-authorizing a team removes the link between Microsoft Teams and PagerDuty. By disconnecting, all channel to service connections will be deleted and user account mappings will be removed.

  1. Navigate to Integrations Extensions Microsoft Teams Integration tile.
  2. Click Disconnect next to the team name.
  3. Enter disconnect in the text field.
  4. Click I understand my actions. Remove PagerDuty from this Microsoft Team. to complete the disconnection.

If you choose to reauthorize an application, users will need to reinstall the application into a team.

How are Microsoft Teams users able to take action on messages from the PagerDuty bot?

We utilize user mapping between a PagerDuty user and their associated Microsoft Teams user. This is done via OAuth Tokens. These tokens are used to communicate with PagerDuty’s REST API.

Can a single Microsoft Teams environment connect to multiple different PagerDuty accounts?

Yes, that is correct.

What information is stored?

After adding the PagerDuty bot to a team, the bot has access to:

  • Channels in the team.

After adding the PagerDuty bot to a channel or chat, it can:

  • Read the members’ information of the channel, chat, or conversation where it was added.
  • Send messages.
  • Reply in conversation.
  • Update messages sent to it.
  • Read messages where it was mentioned.
  • Get an event when a team or channel is renamed.
  • Get an event when a new user is added.
  • Show popups.

The bot cannot:

  • Read any message it wasn't mentioned in.
  • Be added to private channels.

As we use Microsoft Graph API, some confirmation will be requested during the installation/authorization process.

It requests such scopes as:

  • user.readbasic.all
  • onlinemeetings.readwrite
  • offline_access

Please read Microsoft's documentation for more information about scopes.