Slack Integration Guide | PagerDuty

Slack + PagerDuty Integration Benefits

  • The new Slack integration, like the V1 integration, allows you to acknowledge and resolve PagerDuty incidents from the Slack user interface.
  • This update includes new incident response capabilities: trigger and escalate incidents and run response plays from Slack. Additionally, users will now be able to create on-demand Slack channels from PagerDuty incidents.
  • The new Slack integration also has improvements such as an updated notification design with more context from monitoring tools, and actions that respect PagerDuty user permissions.

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.

Requirements

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.
  • Using the Integration: In order to use the Slack slash command /pd trigger to trigger a PagerDuty incident, you must have a PagerDuty user license. I.e., all Slack users who have mapped their Slack and PagerDuty accounts 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 follow the PagerDuty user permissions for each action.
  • If you're not sure what role you have, or if you need your permissions adjusted, visit our sections on Checking Your User Role or Changing User Roles.

In Slack: You need to be a workspace admin or owner.

📘

Looking for Another Version?

The Slack V1 integration guide is also available.

Integration Walkthrough

Initial Configuration

To begin the integration, you will need to map your PagerDuty account to your Slack Workspace. If this has already been performed, please skip ahead to the Add the Slack Extension to a Service section.

📘

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. Navigate to Apps & Add-Ons Extensions.
  2. Select Slack.
  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 friendly Name for the integration, such as SlackV2-Service-Name (e.g. If your service name is Shopping Cart, 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.

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

Once the updated integration has been installed, 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 these 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.

🚧

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.

Creating On-Demand Slack Channels

With the updated 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.

If you would like to use this feature and don’t see it in your PagerDuty account, please reach out to our Support team.

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

OAuth Scope

Slack Description

PagerDuty Request Reason

app_mentions:read

View messages that directly mention @pagerduty in conversations that the app is in.

Used for interactions with PagerDuty bot and responding to commands.

channels:join

Join public channels in a workspace.

After a public channel has been created, we will use this scope to join the channel.

channels:manage

Manage public channels that PagerDuty has been added to and create new ones.

This will allow us to create public channels.

channels:read

View basic information about public channels in a workspace.

Getting user IDs from a channel in order to prompt those users about associating their PagerDuty user to their Slack username.

chat:write

Send messages as @pagerduty.

Used to post incident notifications to channels in Slack.

chat:write.public

Send messages to channels @pagerduty isn't a member of.

Used to post incident notifications to channels in Slack.

commands

Add shortcuts and/or slash commands that people can use.

Used for interactions with the PagerDuty bot and responding to commands.

groups:read

View basic information about private channels that PagerDuty has been added to.

Access information about a user’s private channels: Getting user IDs from a private channel in order to prompt those users about associating their PagerDuty user to their slack username.

groups:write

Manage private channels that PagerDuty has been added to and create new ones

This will allow us to create a private channel for PagerDuty incident.

im:read

View basic information about direct messages that PagerDuty has been added to.

Getting user IDs from a multi-party direct message (private messages to a specific group users) in order to prompt those users about associating their PagerDuty user to their Slack username.

im:write

Start direct messages with people.

Replying to a multi-party direct message about associating their PagerDuty user to their Slack username.

incoming-webhook

Post messages to specific channels in Slack.

PagerDuty communicates with Slack via webhooks to notify users of a new incident in PagerDuty. Used to post to channels in slack.

FAQ

If I already have the Slack V1 extension installed, can I update to 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.

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.

Can I use the same Slack workspace for multiple different PagerDuty accounts?

At this time, mapping multiple PagerDuty accounts to a single Slack workspace is not supported.

How do I provide feedback, suggestions and/or bugs?

Please contact our Support team.

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.

Updated 5 days ago


Learn more

Please visit our Slack V1 FAQ for more information.

Slack V1 Integration Guide

Slack Integration Guide | PagerDuty


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.