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:

Activate Slack integration

After creating and configuring the Slack app and configuring the instance as detailed on this page, you’ll need to set up the Slack integration within Plane.

Create Slack App

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

Go to Your Apps on Slack.
Click Create an App.
Choose From a manifest.
Select the workspace where you want the app installed.

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

{
"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": "issue_shortcut",
            "description": "Create a new issue in plane"
        },
        {
            "name": "Link Work Item",
            "type": "message",
            "callback_id": "link_work_item",
            "description": "Links thread with an existing work item"
        }
    ],
    "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
}
}

{
"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": "issue_shortcut",
            "description": "Create a new issue in plane"
        },
        {
            "name": "Link Work Item",
            "type": "message",
            "callback_id": "link_work_item",
            "description": "Links thread with an existing work item"
        }
    ],
    "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
}
}

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: issue_shortcut
    description: Create a new issue in plane
    - name: Link Work Item
    type: message
    callback_id: link_work_item
    description: Links thread with an existing work item
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

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

Feature	Explanation
`bot_user`	Required to send thread messages while syncing issues or sending Plane notifications to Slack.
`slack_commands`	A Slack command (`/plane`) allows users to create issues directly from Slack using a slash command.
`shortcuts`	After activation, users can create issues from messages inside Slack.
`unfurl_domain`	Specifies the domain where Plane is hosted. When an issue, cycle, or module link is pasted in Slack, it generates a preview of the entity.

Variables

Variable	Explanation
`YOUR_DOMAIN`	The domain where Plane is hosted. This is required for sending webhook events and authentication callbacks.
`YOUR_APP_NAME`	The name you want to give your Slack app. “Plane” is a good default option.
`YOUR_APP_DESCRIPTION`	A short description of your Slack app’s purpose.

Event subscription

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

Bot event	Explanation
`link_shared`	When a link is shared in Slack and its hostname matches `unfurl_domain`, Plane receives the event and generates a preview of the entity.
`message_channels`	When a message is posted in a channel, an event is triggered in Plane to support thread sync.
`message_im`	When a direct message (DM) is posted, an event is triggered in Plane to support thread sync.

User permissions

Permission	Explanation
`chat:write`	Allows the bot to send messages in channels and conversations it is a member of.
`identify`	Allows the bot to verify its own identity and retrieve basic information.
`im:read`	Enables the bot to view direct messages (DMs) where it has been added.
`im:write`	Allows the bot to send direct messages (DMs) to users.
`links:write`	Permits the bot to add, edit, and remove link unfurls.
`links:read`	Allows the bot to view link unfurls and associated metadata.

Bot permissions

Permission	Explanation
`channels:join`	Allows the bot to join public channels.
`channels:read`	Permits viewing public channel information and members.
`users:read`	Allows viewing user information and presence status.
`users:read.email`	Enables access to users’ email addresses.
`chat:write`	Allows sending messages in channels and conversations.
`chat:write.customize`	Enables customization of the bot’s name and profile when sending messages.
`channels:history`	Allows viewing message history in public channels.
`groups:history`	Permits viewing message history in private channels.
`mpim:history`	Enables access to message history in multi-person direct messages.
`im:history`	Allows viewing message history in direct messages.
`links:read`	Permits viewing link unfurls and associated metadata.
`links:write`	Allows adding, editing, and removing link unfurls.
`groups:read`	Enables viewing private channel information and members.
`im:read`	Allows viewing direct messages where the bot is added.
`mpim:read`	Permits viewing multi-person direct messages.
`reactions:read`	Enables viewing emoji reactions on messages.
`reactions:write`	Allows adding and removing emoji reactions.
`files:read`	Permits viewing and downloading files.
`files:write`	Enables uploading, editing, and deleting files.
`im:write`	Allows sending direct messages to users.
`commands`	Enables the bot to add and respond to slash commands.

Configure Plane instance

After creating your Slack app, follow these steps:

Go to the Event Subscriptions tab.
Click Retry to verify your event subscription URL.
Navigate to the Basic Information tab on Slack to find your client_id and client_secret.
Add these environment variables with the values to your Plane instance’s .env file.
```
SLACK_CLIENT_ID=<client_id>
SLACK_CLIENT_SECRET=<client_secret>
```
Save the file and restart the instance.
Once you’ve completed the instance configuration, activate the Slack integration in Plane.

Self-host Plane

Install

Configure

Manage

Troubleshoot

Configure Slack App for Plane integration

Create Slack App

Manifest reference

Features

Variables

Event subscription

User permissions

Bot permissions

Configure Plane instance

Self-host Plane

Install

Configure

Manage

Troubleshoot

​Create Slack App

​Manifest reference

​Features

​Variables

​Event subscription

​User permissions

​Bot permissions

​Configure Plane instance

Create Slack App

Manifest reference

Features

Variables

Event subscription

User permissions

Bot permissions

Configure Plane instance