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

In PagerDuty: An Admin base role is required to perform the initial Integration Walkthrough steps 1–4. If you do not have this role, please reach out to an Admin or Account Owner within your organization to configure the integration.

In Microsoft Teams: A Teams administrator will need to perform the initial Integration Walkthrough steps 1–4. Microsoft Teams administrators are not required after the initial configuration.

🚧

Private & Shared Channels

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

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

In Microsoft Teams

  1. Download the PagerDuty application in the Microsoft Teams Marketplace app store. If your PagerDuty account is hosted in the EU service region, please download the EU version of the app, "PagerDuty EU".
  2. Next, click Add to a Team and select a Team or Channel for initial installation. Note: The application will be applied to all channels within the selected team. Finally, click Set up a bot to install the application.
PagerDuty installation

PagerDuty installation

  1. Next, click Chat in the left hand menu. You will receive a message in a private chat confirming that installation is complete. Click into the chat message and click Authorize to connect your team to PagerDuty. Continue with steps in the In PagerDuty section, below.

If you are not a PagerDuty Admin, click the I’m not a PagerDuty Admin button to see additional instructions to complete authorization. You can send this message to an Admin on your PagerDuty account. A PagerDuty Admin must follow the below steps to authorize PagerDuty to connect to Teams:

a. In Microsoft Teams, start or open a chat with the PagerDuty bot by typing @PagerDuty.
b. Use the authorize [KEY] command and paste the key provided during application installation to receive a personal authorization link.

Note: This step is only necessary upon initial integration installation. If it is already installed, you can skip to step 5.

Authorize PagerDuty app

Authorize PagerDuty app

In PagerDuty

  1. A PagerDuty login page will open in a separate window. Log in with Admin or Account Owner credentials to connect PagerDuty to the team you selected. Note: If you are already logged in, this step will be bypassed. You will be directed to the Microsoft Teams Add-on page in your PagerDuty account and you should see a success message:

    • "You've successfully connected the [YOUR TEAM NAME] team to PagerDuty".

You can now begin mapping PagerDuty services to your Microsoft Teams channels by proceeding to step 5.

Errors

If you receive the following error messages, your account may not have the correct permissions to complete set up or the connection link has expired. Please ensure your PagerDuty role is an Account Owner or Global Admin, check to see if another private chat has been sent with a renewed link, and retry Step 4 of In Microsoft Teams. For more information about PagerDuty user roles, please read Advanced Permissions.

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

Link PagerDuty Services to Microsoft Teams Channels

🚧

Required User Permissions

  • Users with a Manager base role in PagerDuty can complete this step, once an Account Owner or Global Admin has configured Steps 1–4.
    • Base role Managers can link any PagerDuty service to Microsoft Team channels.
    • Team role Managers can link their Team’s PagerDuty services to Microsoft Teams channels.
  • Managers can link PagerDuty services to Microsoft Teams channels via the app command: @PagerDuty connect [link to the service URL in PagerDuty] in the Microsoft Teams Conversation Channel.
  1. In the PagerDuty web app, navigate to Integrations Extensions Microsoft Teams Integration and click Edit.
  2. Click Notification Channels Connect Notification Channel. Select which PagerDuty service and which Microsoft Teams channel that you would like to connect to each other from the PagerDuty Service and Microsoft Team Channel dropdowns.
  3. Click Connect to complete the integration.

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

In order for users to take action on incident notifications 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:

    a. Via Channel Message: Use the Link Accounts button to receive a personal account mapping link.

    Posted in General channel after Microsoft Teams connection:

Microsoft Teams connection

Microsoft Teams connection

Posted in a channel after a PagerDuty service is connected:

Service connection

Service connection

b. Via App Command: Use the app command @PagerDuty linkUser in a private PagerDuty bot chat to receive a personal account mapping link.

  1. 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 Add-on 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 this is not correct, please enter the @PagerDuty unlinkUser command in Microsoft Teams to unlink your account.”

Errors

If you receive an error, please verify 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

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

Expand

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?

Expand

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. A pop-up message will appear that will require the Admin to input 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?

Expand

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?

Expand

Yes, that is correct.

What information is stored?

Expand

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.

What Microsoft Graph permissions are required by the PagerDuty app?

Expand

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

PagerDuty App FeatureScopePagerDuty Request Reason
App Configurationoffline_accessAllows the PagerDuty app to obtain a refresh token. The PagerDuty app uses this refresh token to obtain a new user access token without requiring the user to re-authenticate. This enables long-term authorization and eliminates the need for manual application reauthorization.
App ConfigurationUser.ReadAllows the PagerDuty app to read the full profile and organization name of the signed-in user.
Create Dedicated ChatChat.ReadWriteGrants the PagerDuty app the ability to read and write messages in chat conversations within Microsoft Teams. With this permission, the application can send new incident message cards, and update or delete messages in the chat.
Create Dedicated ChatTeamsAppInstallation.ReadWriteForChatAllows the PagerDuty app to be installed in a Microsoft Teams chat without manual action needed from the user.
Create Incident MeetingOnlineMeetings.ReadWriteAllows the PagerDuty app to create, read, update, and delete online meetings on behalf of the user.
Create Incident MeetingUser.ReadBasic.AllGrants the PagerDuty app the permission to read basic profile properties of all users in the organization. The PagerDuty app uses these details when inviting users to meetings.