Configure Slack App for Plane integration

This guide walks you through setting up a Slack App to enable Slack integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for Slack, you’ll need to set up the necessary authentication, permissions, and event subscriptions to ensure seamless communication between Plane and Slack.

In this guide, you’ll:

1. Create and configure a Slack App
2. Configure your Plane instance

​

Create Slack App

To configure Slack integration, you’ll need to create a Slack App within your organization. Follow these steps:

1. Go to Your Apps on Slack.

2. Click Create an App.

3. Choose From a manifest.

4. Select the workspace where you want the app installed.

5. Remove the default manifest and paste the one below, making sure to update the placeholders with your actual values.

   • JSON
   • YAML

   {
   "display_information": {
       "name": "[YOUR_APP_NAME]",
       "description": "[YOUR_APP_DESCRIPTION]",
       "background_color": "#224dab"
   },
   "features": {
       "bot_user": {
           "display_name": "[YOUR_APP_NAME]",
           "always_online": false
       },
       "shortcuts": [
           {
               "name": "Create new issue",
               "type": "message",
               "callback_id": "create_new_issue",
               "description": "Create a new issue in plane"
           }
       ],
       "slash_commands": [
           {
               "command": "/plane",
               "url": "https://[YOUR_DOMAIN]silo/api/slack/command/",
               "description": "Create issue in Plane",
               "should_escape": false
           }
       ],
       "unfurl_domains": [
           "[YOUR_DOMAIN]"
       ]
   },
   "oauth_config": {
       "redirect_urls": [
           "https://[YOUR_DOMAIN]silo/api/slack/team/auth/callback/",
           "https://[YOUR_DOMAIN]silo/api/slack/user/auth/callback/"
       ],
       "scopes": {
           "user": [
               "chat:write",
               "identify",
               "im:read",
               "im:write",
               "links:write",
               "links:read"
           ],
           "bot": [
               "channels:join",
               "channels:read",
               "users:read",
               "users:read.email",
               "chat:write",
               "chat:write.customize",
               "channels:history",
               "groups:history",
               "mpim:history",
               "im:history",
               "links:read",
               "links:write",
               "groups:read",
               "im:read",
               "mpim:read",
               "reactions:read",
               "reactions:write",
               "files:read",
               "files:write",
               "im:write",
               "commands"
           ]
       }
   },
   "settings": {
       "event_subscriptions": {
           "request_url": "https://[YOUR_DOMAIN]silo/api/slack/events",
           "bot_events": [
               "link_shared",
               "message.channels",
               "message.im"
           ]
       },
       "interactivity": {
           "is_enabled": true,
           "request_url": "https://[YOUR_DOMAIN]silo/api/slack/action/",
           "message_menu_options_url": "https://[YOUR_DOMAIN]silo/api/slack/options/"
       },
       "org_deploy_enabled": false,
       "socket_mode_enabled": false,
       "token_rotation_enabled": true
   }
   }
   

6. Review the permissions and click Create.

​

Manifest reference

The manifest file defines the configuration for integrating Plane with Slack. It requests access to several features, enabling Plane to interact with Slack efficiently.

​

Features

​

Variables

​

Event subscription

For thread sync and link unfurling to work, event subscriptions must be enabled. These events send relevant activity to Plane.

​

User permissions

​

Bot permissions

​

Configure Plane instance

After creating your Slack app, follow these steps:

1. Go to the Event Subscriptions tab.

2. Click Retry to verify your event subscription URL.

3. Navigate to the Basic Information tab on Slack to find your client_id and client_secret.

4. Add these environment variables with the values to your Plane instance’s .env file.

   SLACK_CLIENT_ID=<client_id>
   SLACK_CLIENT_SECRET=<client_secret>
   

5. Save the file and restart the instance.

6. Once you’ve completed the instance configuration, activate the Slack integration in Plane.