Skip to main content

Setting up Slack

If you plan on self-hosting Papercups, you'll need to set up your own Slack app if you want to handle messaging through Slack.

NB: if you're not self-hosting, you can safely ignore this guide :)

Creating the app#

  • Go to
  • Click “Create New App”
  • Name it whatever you’d like, and pick the Slack workspace you’d like to test it against

Subscribing to Slack events#

  • Go to “Event Subscriptions”
  • Toggle “Enable Events” to “On”
  • Input your webhook URL in the “Request URL” input
    • It should look like https://YOUR_APP_HOST/api/slack/webhook
    • In my case, this was

  • Subscribe to the following bot events:

    • message:channels
    • message:groups
  • Also, subscribe to the same user events:

    • message:channels
    • message:groups

Setting up scopes and permissions#

  • Go to “OAuth & Permissions”
  • Click the “Install App to Workspace” button to install your app to your test workspace if you haven’t already

  • Add the redirect URL we’ll be using in the dashboard
    • It should look like https://YOUR_APP_HOST/integrations/slack
    • In my case, this was

  • Add the bot scopes we’ll be using
    • channels:history
    • channels:manage
    • chat:write
    • chat:write.public
    • incoming-webhook

  • Add the user scopes we’ll be using
    • channels:history

Enabling distribution of your app#

  • Set up your app for distribution
  • Under “Basic Information”, go to the “Manage distribution” section and click “Distribute App”

  • Indicate that hard-coded information has been removed from your code
    • (We’ve handled this for you!)

  • Click on “Activate Public Distribution”

Setting up your environment variables#

  • In the “Basic Information” section, scroll down to “App Credentials” to get the keys you’ll be using as environment variables

  • Export the following environment variables:
  • If you're using Heroku, set the environment variables on the config:


  • Go to the /integrations path in your dashboard
  • Click on "Connect" for Slack

  • Go through the OAuth flow for your app
  • Select a channel to connect with

  • If successful, it should take you back to this page:

  • To test that it works, go to the "Getting started" tab
  • Try sending a message in the widget on the right:

  • Check Slack to verify you received a message
  • Try sending a reply through Slack

  • Verify that the reply was received


That should be it! Feel free to open an issue if you have any problems getting set up :)