Slack + 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, users 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

To Configure the Integration

In PagerDuty

• 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 your PagerDuty account has been mapped to your Slack workspace (see above) users with a Manager team role or base role can add the Slack extension to services.

In Slack

You need to be a workspace admin or owner.

To Use the Integration

In order to use the Slack slash command /pd trigger to trigger a PagerDuty incident, you must have a PagerDuty user license. In other words, Slack users who have associated 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 — will respect the user’s PagerDuty permissions.

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

How it Works

• Users can trigger, acknowledge, resolve, escalate, add notes and run Response Plays within Slack, which will send events to PagerDuty, resulting in the corresponding incident actions.
• When a PagerDuty incident is triggered outside of Slack, an event is sent to the mapped Slack workspace, which generates a message with the incident's details in the designated channel. Users can then perform actions (listed above) within Slack, or within PagerDuty, and the actions will be synced bi-directionally.

Please see 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's 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, please follow our instructions here.

Integration Walkthrough

Initial Configuration

📘

Note

• Multiple Slack workspaces can be mapped to a single PagerDuty account by repeating the below 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 before, you will need to map your PagerDuty account to your Slack Workspace. If you have already configured Slack before (such as with Slack v1, etc.), please skip ahead to Add the Slack Extension to a Service.
2. Navigate to Integrations Extensions. Select the top Slack tile.
3. On the Slack Workspace Mapping screen, click the Install App into Workspace button 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 can be executed from any Slack channel.
4. On the next screen, you will be asked to authorize the PagerDuty for Slack extension to perform the following actions:

• Confirm your identity on PagerDuty
• Access and modify information about your channels: In order to send prompts to Slack users to associate their Slack and PagerDuty usernames, the extension needs to obtain 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 allows the extension to access your team’s profile information and it is used for Slack user association. The list of members from the channel endpoint only gives PagerDuty your Slack ID and this allows it to obtain necessary usernames.
• Send messages as [Workspace Name] for Slack: This allows the extension to post to specific channels in your Slack workspace.
• Access your workspace’s profile information: Similar to the above, this allows the extension to access your team’s profile information and it is used for Slack user association. The list of members from the channel endpoint only gives PagerDuty your Slack ID and this allows it to obtain necessary usernames.
• Send messages as you: This is used to post notifications into the selected channel when a PagerDuty incident has been triggered, updated or resolved.

Click Allow to authorize. Once this step is complete, you can then 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 click the name of your desired service Integrations tab Add or Manage Extensions + New Extension.

2. Select Slack V2 from the dropdown menu and enter a user-friendly Name for the integration, such as SlackV2-Service-Name (e.g. If your service name is Shopping Cart, for example, the extension name would be SlackV2-Shopping-Cart). Next, select the Service that you would like to integrate with the Slack extension. In the Details section, you can select which updates you want sent to Slack: Escalate, Resolves, Acknowledgements, Reassign and Notes actions. 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. Please note that if you plan to use Slack V1 and V2 at the same time, you will need to integrate Slack V2 into the same workspace. Next, in the Choose a channel... dropdown, search and select the channel where you would like PagerDuty to send messages. This authorization screen has many of the same permissions listed above in step 4, with the following differences:

   • Access information about your direct messages: In order to send prompts to Slack users to associate their Slack and PagerDuty usernames, the extension needs to obtain user IDs from multi-party direct messages (i.e., private messages to a specific group of users).
   • View email addresses of people on your workspace: This allows the extension to access your team’s profile information and it is used for Slack user association.

Once you have reviewed these permissions, click Authorize. You may add the Slack extension to multiple services by repeating steps 5-7.

4. The Slack integration is now complete. You should see a message in your designated Slack channel 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 is triggered, the trigger message in Slack will show Acknowledge and Resolve buttons, and under the More actions… menu, you will see the options View Details, Add a Note, Escalate or Run a Play.

Available Slash Commands

After completing the integration, new slash commands will be available. These slash commands can be run from Slack channels that are 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 in order 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, PagerDuty users can create on-demand Slack channels within PagerDuty. These can be created on the Incident Details screen in the web application by clicking Set Channel. You will have the ability to create new public or private channels or associate an existing channel to an incident.

🚧

User Permission Notes

• When you click Set Channel you may be prompted to authorize the connection between your PagerDuty and Slack accounts again, as PagerDuty will now be creating a channel behalf of your individual Slack user account.
• You will only be able to view channels that you have permission in Slack to access.
• If you do not have permission in Slack to create channels, you will not be able to create them from the Set Channel link in a PagerDuty incident.
• If your PagerDuty account has multiple Slack workspaces connected, you will have the option to 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 select Tools Workflow Builder. Click Create on the right, enter a workflow name, such as 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, such as Trigger PD incident, and then click Next.
3. Next, to create a form for users to enter incident Titles and Descriptions, click Add Step and then click Add next to Create a form. Enter a Title for the form, such as Trigger PD incident, enter Title under Add a question, select Short answer and ensure Make this required is checked. Next, click Add Question and enter Description under Add a question, select Short answer, ensure Make this required is checked and click Done. Uncheck Send submitted responses to a channel or to someone in a DM and then click Save to save both forms.
4. Next, click Add Step, select the Steps from Apps tab, search and then select Trigger Incident. You will be prompted to sign into your PagerDuty account, click Sign in. Once signed in, the Trigger Incident Step will be added to your Slack workflow. Select your preferred Impacted service, optionally select the Assign to user and optionally select your preferred Priority. Next, under Title click Insert a variable and select Response to: “Title” to add the Title form. Similarly, under Description, click Insert a variable and select Response to: “Description” and then click Save. If you would like to add an optional message to be sent with this workflow, continue to step 5. 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. Under Send this message to: select Channel where workflow started. Under Message text enter your preferred message to be sent with the workflow. You have the option to 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. Finally, click Publish in the upper right 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 and click the Shortcuts at the bottom left of your text field and select the Trigger PD incident workflow.
2. Enter the Title and Description of the incident and click Submit.
3. The incident will be created in PagerDuty and you will be able to see the incident details in your Slack channel.

Granular Bot Permissions

Slack now uses granular bot permissions, as detailed in the Bot Token Scopes table. All channel connections will be affected by granular bot permissions, but new connections will closely follow Slack workspace security settings. Creating channel connections could require users to have additional Slack permissions or Admin authorization, as detailed in the Approve App Update section below.

Approve App Update

There are two Slack settings that may impact the app update:

• App Updates require a 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 a notification will be sent to Slack admin to approve connection. If a Slack Admin does not approve the new changes, users will not be able to 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 may need to reauthorize your Slack scopes in order to gain access to new features.

To reauthorize, admins should visit Integrations Extensions Slack Integration. If reauthorization is required, you will see a Reauthorize button next to the name of your Slack workspace:

After clicking Reauthorize you will be asked to approve the additional scopes and permissions needed for new functionality. Reauthorization will 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 will need to add Slack V2 as a new extension, and once you're finished testing, delete the Slack V1 extension. You'll then need to complete the Workspace mapping step (Step 3 of Initial Configuration, above) to connect your Slack Workspace to PagerDuty.

To migrate to Slack V2 Next Generation:

Please follow instructions here to use our migration tool.

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

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

If I don’t connect my PagerDuty and Slack accounts, can I still action notifications in Slack?

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

I changed my channel from public to private, and now my incidents aren't posting to Slack.

You'll need to 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 do need to 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 will function. Note: At the moment 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 do this by running the /pd oncall command.

What do I do if I’m 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 above.