Slack and PagerDuty Integration Benefits

The Slack V2 integration allows you to acknowledge and resolve PagerDuty incidents from the Slack user interface.

This update includes incident response capabilities: trigger and escalate incidents and run response plays from Slack. Additionally, you can create on-demand Slack channels from PagerDuty incidents.

The Slack V2 integration also has improvements such as an updated notification design with more context from monitoring tools, and actions that respect PagerDuty user permissions.

Requirements

Configuration Requirements

PagerDuty Requirements

• Initial Configuration: This integration requires an Admin, Global Admin, or Account Owner base role to perform the initial configuration. This includes mapping your PagerDuty account to your Slack workspace.
• Service-Level Configuration: Once you map your PagerDuty account to your Slack workspace (as detailed in the following section), if you have a Manager team role or base role, you can add the Slack extension to services.

Slack Requirements

You must be a workspace admin or owner.

Usage Requirements

To use the Slack slash command /pd trigger to trigger a PagerDuty incident, you must have a PagerDuty user license. Slack users who associate their Slack account with PagerDuty can trigger incidents from the Slack interface. Other actions — such as acknowledging, resolving, viewing incident details, adding a note, escalating, or running a response play — respect your PagerDuty permissions.

• If you are not sure what role you have, or if you need your permissions adjusted, view our articles on Check Your User Role or Edit User Roles.

How It Works

• You can trigger, acknowledge, resolve, escalate, add notes, and run response plays within Slack, which sends events to PagerDuty, resulting in the corresponding incident actions.
• When a PagerDuty incident triggers outside of Slack, an event is sent to the mapped Slack workspace, which generates a message with the details of the incident in the designated channel. You can then perform actions (listed in the previous section) within Slack or within PagerDuty, and the actions sync bi-directionally.

View the PagerDuty Privacy Policy to read more about how we collect, use, and disclose your information.

Version

This guide details configuration of our Slack V2 integration.

📘

Looking for Another Version?

The following version is also available:

• Slack V2 Next Generation is our latest integration.

👍

Slack V2 Next Generation

What is the difference between Slack V2 and Slack V2 Next Generation?

• Slack V2 uses a V2 webhook extension and comes with standard features.
• Slack V2 Next Generation uses a V3 Webhook Subscription and comes with updated features.

To migrate to Slack V2 Next Generation, follow the instructions here.

Integration Walkthrough

Initial Configuration

📘

Note

• Multiple Slack workspaces can be mapped to a single PagerDuty account by repeating the following steps for each workspace.
• At this time, mapping multiple PagerDuty accounts to a single Slack workspace is not supported.

1. If you have never configured the Slack integration, you must map your PagerDuty account to your Slack workspace. If you already configured Slack (such as with Slack V1), skip ahead to Add the Slack Extension to a Service.
2. Navigate to Integrations Extensions. Click the top Slack tile.
3. On the Slack Workspace Mapping screen, click Install App into Workspace to connect your PagerDuty account to your Slack workspace. Connecting your PagerDuty account to your Slack workspace ensures that the PagerDuty bot is present and that PagerDuty slash commands execute from any Slack channel.
4. On the next screen, the extension prompts you to authorize the PagerDuty for Slack extension to perform the following actions:
   • Confirm your identity on PagerDuty
   • Access and modify information about your channels: To send prompts to Slack users to associate their Slack and PagerDuty usernames, the extension requires user IDs from the associated channel. The modify channels access is only used for the per-incident, on-demand Slack channel feature.
   • Add slash commands and add actions to messages (and view related content)
   • Access information about your workspace: This action allows the extension to access the profile information of your team and uses it for Slack user association. The list of members from the channel endpoint only provides PagerDuty with your Slack ID, which allows it to obtain necessary usernames.
   • Send messages as [Workspace Name] for Slack: This action allows the extension to post to specific channels in your Slack workspace.
   • Access your workspace’s profile information: Similar to the previous item, this action allows the extension to access the profile information of your team and uses it for Slack user association. The list of members from the channel endpoint only provides PagerDuty with your Slack ID, which allows it to obtain necessary usernames.
   • Send messages as you: This action posts notifications into the selected channel when a PagerDuty incident triggers, updates, or resolves.

Click Allow to authorize. Once this step is complete, you can begin connecting PagerDuty services to a specific Slack channel. Continue to Add the Slack Extension to a Service to complete the integration.

Add the Slack Extension to a Service

1. Navigate to Services Service Directory, select the name of your desired service, select the Integrations tab, and click Add or Manage Extensions + New Extension.
2. Complete the following fields on the extension configuration screen:

Click Authorize to continue.

3. On the authorization screen, ensure that you are in the correct Slack workspace by checking the dropdown in the upper right-hand corner. If you plan to use Slack V1 and V2 at the same time, you must integrate Slack V2 into the same workspace. Next, in the Choose a channel... dropdown, search for and select the channel where PagerDuty sends messages. This authorization screen contains many of the same permissions listed in the previous section, with the following differences:
   • Access information about your direct messages: To send prompts to Slack users to associate their Slack and PagerDuty usernames, the extension requires user IDs from multi-party direct messages (that is, private messages to a specific group of users).
   • View email addresses of people on your workspace: This action allows the extension to access the profile information of your team and uses it for Slack user association.

Once you review these permissions, click Authorize. You can add the Slack extension to multiple services by repeating these steps for each service.

4. The Slack integration is now complete. A message appears in your designated Slack channel stating that the PagerDuty integration has been added. If you set up the integration on a private channel, add @pagerduty to your channel. When an incident triggers, the trigger message in Slack shows Acknowledge and Resolve buttons, and under the More actions… menu, displays the options View Details, Add a Note, Escalate, or Run a Play.

Available Slash Commands

After completing the integration, new slash commands are available. These slash commands execute from Slack channels configured with PagerDuty:

• /pd help: Displays a help message with a list of available slash commands.
• /pd trigger: Trigger a new PagerDuty incident within the Slack interface.
• /pd unlink: Unlink your current Slack user from your PagerDuty user.
• /pd invite @ [Slack User Name]: Invites the specified Slack user as a responder to your PagerDuty account.
• /pd oncall: View who is on call for a PagerDuty service.
• /pd insights: Configure the PagerDuty Analytics Slack integration to send recurring Insights to Slack.

🚧

Required Permissions

/pd oncall requires channel-specific permissions. You must invite @PagerDuty to private Slack channels to use this Slack slash command.

It is not possible to use this command in other direct messages outside of a direct message with @PagerDuty.

Create On-Demand Slack Channels

With this Slack integration, you can create on-demand Slack channels within PagerDuty. These can be created on the Incident Details screen in the web app by clicking Set Channel. You can create new public or private channels or associate an existing channel to an incident.

🚧

User Permission Notes

• When you click Set Channel, the system may prompt you to authorize the connection between your PagerDuty and Slack accounts again, as PagerDuty creates a channel on behalf of your individual Slack user account.
• You can only view channels that you have permission in Slack to access.
• If you do not have permission in Slack to create channels, you cannot create them from the Set Channel link in a PagerDuty incident.
• If your PagerDuty account has multiple Slack workspaces connected, you can pick which workspace to use.

Create an Incident Trigger Slack Workflow

Slack workflows can be used to trigger PagerDuty incidents from Slack with pre-configured details such as service and priority.

1. In your Slack desktop, click your Workspace Name dropdown in the top left and navigate to Tools Workflow Builder. Click Create, enter a workflow name (for example, Trigger PD incident), and click Next.
2. Click Select next to Shortcut, select your preferred channel under Which channel?, enter a name under Add a short name (for example, Trigger PD incident), and click Next.
3. Click Add Step and click Add next to Create a form. Complete the following fields for the first question:

Click Add Question and complete the following fields for the second question:

Click Done. Uncheck Send submitted responses to a channel or to someone in a DM and click Save to save both forms.

4. Click Add Step, select the Steps from Apps tab, and select Trigger Incident. Click Sign in to log in to your PagerDuty account. Once signed in, complete the following fields in the Trigger Incident step:

Click Save. If you want to add an optional message, continue to the next step. If you do not want to add a message, skip to step 6.

5. Send a Message With Workflow (Optional): Click Add Step and click Add next to Send a message. Complete the following fields:

You can include variables such as Impacted technical service, Incident number, Incident title, and Incident url by clicking Insert a variable under the message form. Click Save.

6. Click Publish to publish your workflow.

Use an Incident Trigger Slack Workflow

1. In your Slack desktop, enter a channel with an Incident Trigger Slack Workflow configured, click the Shortcuts icon at the bottom left of your text field, and select the Trigger PD incident workflow.
2. Complete the following fields in the workflow form:

Click Submit.

3. The incident is created in PagerDuty, and you can view the incident details in your Slack channel.

Granular Bot Permissions

Slack uses granular bot permissions, as detailed in the Bot Token Scopes table. All channel connections are affected by granular bot permissions, but new connections closely follow Slack workspace security settings. Creating channel connections can require additional Slack permissions or admin authorization, as detailed in the Approve App Update section below.

Approve App Update

Two Slack settings can impact the app update:

• App updates require Slack admin approval.
• Only Slack admins or Slack app managers can create PagerDuty service to Slack channel connections.

If a user does not have the correct Slack user permissions, then the system sends a notification to the Slack admin to approve the connection. If a Slack admin does not approve the new changes, you cannot create new Slack channel and PagerDuty service connections. If your Slack account has not restricted these settings, no action is necessary.

To approve the app update as a Slack admin:

1. Navigate to the Slack admin portal and search for the PagerDuty app.
2. At the top right of the page, click Approve next to Manage app for entire workspace? and approve PagerDuty app changes.

Bot Token Scopes

Reauthorization

If your Slack integration was configured prior to April 1, 2021, you must reauthorize your Slack scopes to gain access to new features.

To reauthorize, navigate to Integrations Extensions Slack Integration. If reauthorization is required, a Reauthorize button appears next to the name of your Slack workspace:

Click Reauthorize to approve the additional scopes and permissions required for new functionality. Reauthorization does not impact your current functionality or integration configuration.

FAQ

If I already have the Slack V1 extension installed, how do I migrate to Slack V2 or Slack V2 Next Generation?

Slack V1 was deprecated on November 1, 2021, and accounts using this version must migrate to Slack V2 or Slack V2 Next Generation.

To migrate to Slack V2:

You must add Slack V2 as a new extension, and once you are finished testing, delete the Slack V1 extension. You must then complete the workspace mapping step (Step 3 of Initial Configuration) to connect your Slack workspace to PagerDuty.

To migrate to Slack V2 Next Generation:

Please follow the instructions here to use our migration tool.

How do I know if I am using V1 or V2 integration when looking at the Slack notification?

If the notification in Slack contains a More Actions menu, you are using the updated V2 integration.

If I do not connect my PagerDuty and Slack accounts, can I still action notifications in Slack?

No. The Slack V2 integration requires you to connect so that it can respect PagerDuty user permissions.

I changed my channel from public to private, and now my incidents are not posting to Slack.

You must invite the PagerDuty bot into your Slack channel after you set it to private.

Do I need to install anything separate to use the slash command?

No. In the V2 integration, this is no longer a separate app. You must ensure that you map the Slack extension and your Slack workspace to PagerDuty (step 4 of the Integration Walkthrough), and then the /pd trigger command functions. Note: Currently in V2, only PagerDuty users can use /pd trigger. If you want to allow anyone to use the slash command, you should keep the legacy slash command integration in place.

Can I add multiple Slack workspaces to a single PagerDuty account?

Yes, multiple workspaces can be mapped to a single PagerDuty account by repeating the Initial Configuration and adding the extensions to services for each workspace.

How do I view on-call information in Slack?

You can view on-call information by running the /pd oncall command.

What do I do if I am seeing a 403_client_error when running the /pd trigger command?

You are likely attempting to trigger an incident from a Slack channel that is not connected to PagerDuty. Ensure that you have connected Slack to PagerDuty as shown in step 3.