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 probably ignore this guide :)

Creating the app

• Go to https://api.slack.com/apps
• 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 https://alex-papercups-staging.herokuapp.com/api/slack/webhook

• Subscribe to the message.channels bot event
• Subscribe to the message.channels user event

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 https://alex-papercups-staging.herokuapp.com/integrations/slack

• 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:

export PAPERCUPS_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
export REACT_APP_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
export PAPERCUPS_SLACK_CLIENT_SECRET='YOUR_CLIENT_SECRET_HERE'

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

heroku config:set PAPERCUPS_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
heroku config:set REACT_APP_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
heroku config:set PAPERCUPS_SLACK_CLIENT_SECRET='YOUR_CLIENT_SECRET_HERE'

Testing

• 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

Done!

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