> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Add a bot to Slack using the official integration.

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KQF3XKNH2W5EPAXK6G4CMW96)
*v5.0.2*

The official Slack integration allows members of your Slack workspace to chat with your bot via a Slack app.

## Setup

> [tab] Automatic configuration
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Slack workspace](https://slack.com/get-started?entry_point=help_center#/createnew)
>
> 1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
> 2. Search for the **Slack** integration, then select **Install Integration**.
> 3. In the **Configuration** menu, select **Authorize Slack**.
> 4. Follow the instructions to connect Botpress to your Slack account.

> [tab] Manual configuration
>
> For advanced use cases, you can use your own Slack app with our integration.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Slack workspace](https://slack.com/get-started?entry_point=help_center#/createnew)
>
> ### 1. Install the Slack integration in Botpress
>
> 1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
> 2. Search for the **Slack** integration, then select **Install Integration**.
> 3. In the **Configuration** menu, select the drop-down menu, then select **Configure by manually supplying the refresh token and signing secret**.
> 4. Leave the configuration fields empty for now—you'll come back to them after you've setup your Slack app.
>
> ### 2. Create a Slack app
>
> Next, you'll need to create a Slack app for your bot:
>
> 1. Open a new tab and go to your [Slack API portal](https://api.slack.com/apps). Login if you haven't already.
> 2. Select **Create New App**, then **From a manifest**.
> 3. Select the workspace you want to connect your bot to.
> 4. Erase everything in the field, then paste this code:
>
> ```json JSON [expandable] lines theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> {
>     "display_information": {
>         "name": "Bot (powered by Botpress)"
>     },
>     "features": {
>         "bot_user": {
>             "display_name": "Bot (powered by Botpress)",
>             "always_online": false
>         }
>     },
>     "oauth_config": {
>         "redirect_urls": [
>             "https://webhook.botpress.cloud/oauth"
>         ],
>         "scopes": {
>             "bot": [
>                 "channels:history",
>                 "channels:manage",
>                 "channels:read",
>                 "chat:write",
>                 "groups:history",
>                 "groups:read",
>                 "groups:write",
>                 "im:write",
>                 "im:read",
>                 "im:history",
>                 "mpim:history",
>                 "mpim:read",
>                 "mpim:write",
>                 "reactions:read",
>                 "reactions:write",
>                 "team:read",
>                 "users.profile:read",
>                 "users:read",
>                 "users:read.email"
>             ]
>         }
>     },
>     "settings": {
>         "event_subscriptions": {
>             "request_url": "https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
>             "bot_events": [
>                 "member_joined_channel",
>                 "member_left_channel",
>                 "message.channels",
>                 "message.groups",
>                 "message.im",
>                 "message.mpim",
>                 "reaction_added",
>                 "reaction_removed",
>                 "team_join"
>             ]
>         },
>         "org_deploy_enabled": false,
>         "socket_mode_enabled": false,
>         "token_rotation_enabled": false
>     }
> }
> ```
>
> ```yaml YAML [expandable] lines theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> display_information:
>   name: Bot (powered by Botpress)
> features:
>   bot_user:
>     display_name: Bot (powered by Botpress)
>     always_online: false
> oauth_config:
>   redirect_urls:
>     - https://webhook.botpress.cloud/oauth
>   scopes:
>     bot:
>       - channels:history
>       - channels:manage
>       - channels:read
>       - chat:write
>       - groups:history
>       - groups:read
>       - groups:write
>       - im:write
>       - im:read
>       - im:history
>       - mpim:history
>       - mpim:read
>       - mpim:write
>       - reactions:read
>       - reactions:write
>       - team:read
>       - users.profile:read
>       - users:read
>       - users:read.email
> settings:
>   event_subscriptions:
>     request_url: https://webhook.botpress.cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
>     bot_events:
>       - member_joined_channel
>       - member_left_channel
>       - message.channels
>       - message.groups
>       - message.im
>       - message.mpim
>       - reaction_added
>       - reaction_removed
>       - team_join
>   org_deploy_enabled: false
>   socket_mode_enabled: false
>   token_rotation_enabled: false
> ```
>
> 5. Select **Create**. This creates a Slack app with all the necessary scopes and subscriptions for the Botpress Slack integration.
>
> ### 3. Install the app to your workspace
>
> Next, you need to install the app to your Slack workspace and enable token rotation:
>
> 1. Navigate to **OAuth and Permissions** in the left navigation bar of your Slack app's settings.
>
> 2. Under OAuth Tokens, select **Install to (your workspace name)**, then follow the on-screen instructions to authorize the app.
>
> > [!WARNING]
> >
> > Make sure you follow this step before moving on—otherwise, you won't be able to install the app to your workspace.
>
> 3. Scroll up to **Advanced token security via token rotation**, then select **Opt In**.
>
> ### 4. Configure the integration in Botpress
>
> Now you can use your app's credentials to fill in the configuration fields from [Step 1](#step-1-install-the-slack-integration-in-botpress):
>
> > [accordion] Slack Refresh Token or Bot Token
> >
> > 1. Navigate to **OAuth & Permissions** in the left navigation bar of your Slack app's settings.
> > 2. Copy the **Bot User OAuth Token**.
> > 3. Paste it into the **Slack Refresh Token or Bot Token** field.
>
> > [accordion] Slack Client ID
> >
> > 1. Navigate to **Basic Information** in the left navigation bar of your Slack app's settings.
> > 2. Copy the **Client ID**.
> > 3. Paste into the **Slack Client ID** field.
>
> > [accordion] Slack Client Secret
> >
> > 1. Navigate to **Basic Information** in the left navigation bar of your Slack app's settings.
> > 2. Copy the **Client secret**.
> > 3. Paste into the **Slack Client Secret** field.
>
> > [accordion] Slack Signing Secret
> >
> > 1. Navigate to **Basic Information** in the left navigation bar of your Slack app's settings.
> > 2. Copy the **Signing secret**.
> > 3. Paste into the **Slack Signing Secret** field.
>
> When all the fields have been filled in, scroll down and select **Save Configuration**. This automatically activates the integration.
>
> ### 5. Add the integration's webhook URL
>
> All you need to do now is add the integration's webhook URL to your Slack app:
>
> 1. Scroll up and copy the webhook URL at the top of the integration's **Configuration** menu. It should start with `webhook.botpress.cloud`.
>
> 2. Go back to your Slack app's settings. Navigate to the **Event Subscriptions** section.
>
> 3. In the **Request URL** field, erase the placeholder webhook URL and paste your actual webhook URL.
>
> 4. Select **Save Changes** at the bottom of the page.
>
> > [!TIP]
> >
> > Your Slack integration is ready. Within your Slack workspace, you can search for the app and add it to any channel—it should respond as your bot.

***

## Options

The Slack integration's **Configuration** menu offers a few additional options:

### Custom display name / avatar

* Fill in the **Bot name** field to display a custom name as the sender in Slack conversations.
* Fill in the **Bot avatar URL** field to set a custom image as the bot's Slack avatar.

> [!NOTE]
>
> The image should be square, at least 512x512 pixels, and no larger than 1024x1024 pixels. The URL must be publicly accessible. Supported formats include GIF, PNG, JPG, JPEG, HEIC, and HEIF.

### Typing indicator emoji

When the **Typing indicator emoji** option is enabled, the bot will [react](https://www.google.com/url?sa=t\&source=web\&rct=j\&opi=89978449\&url=https://slack.com/help/articles/202931348-Use-emoji-and-reactions\&ved=2ahUKEwjkjonOtueOAxXug4kEHWXTNBsQFnoECBcQAQ\&usg=AOvVaw0_PwUudKr3nwqdIQhPpFza) to incoming messages with an emoji to indicate that it's processing the message.

### Reply threading

When the **Reply Threading Enabled** option is enabled, the bot will reply to incoming messages in [threads](https://slack.com/help/articles/115000769927-Use-threads-to-organize-discussions).

If you want the bot to only reply in a thread when [mentioned](https://slack.com/help/articles/205240127-Use-mentions-in-Slack), enable the **Require Bot Mention for Reply Threading** option.

{/* <Note>
Enabling reply threading alone doesn't stop your bot from posting in the main channel. To restrict responses exclusively to threads, modify your Workflow to terminate when receiving messages from the main channel:

1. Insert a Standard Node at the very beginning of your Main Workflow. Then, connect it to your existing Workflow.
2. Add an [expression Card](https://botpress.com/docs/studio/concepts/cards/flow-logic.md#expression) to the Standard Node.
3. Set the expression Card's condition to `event.channel === 'channel'`.
TODO: modify conditional to account for other channel types
3. Create an End Card and connect the expression Card to it.
</Note> */}

## Limitations

Here are some limitations with the Slack integration:

### API rate limits

Standard Slack API limits apply to the Slack integration in Botpress. These include rate limits, message size restrictions, and other constraints imposed by the Slack platform. Ensure that your bot adheres to these limits to maintain optimal performance and reliability.

> [!NOTE]
>
> For more information, check out the [Slack API documentation](https://api.slack.com/apis/rate-limits).

### Rich text processing

Slack uses a proprietary markup language, [mrkdwn](https://api.slack.com/reference/surfaces/formatting#lists), to format rich text in messages. Since Botpress uses [standard Markdown](https://www.markdownguide.org/cheat-sheet/) for rich text, we convert incoming `mrkdwn` messages from Slack to Markdown. This is to ensure that:

* Studio's interface can read them properly
* Botpress' AI inference engine can understand them

However, any outgoing AI-generated messages your bot sends to the Slack integration will still be rendered in Markdown by default. This means **rich text messages from your bot may not be rendered properly in Slack** without additional processing.

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Add Reaction

Add a reaction to a message

**input** `object`

**name** `string` *required*

The name of the reaction to add, ex: thumbsup

**messageId** `string` *required*

The ID of the message, ex: \{\{event.messageId}}

**output** `object`

This Card has no output.

### Find Target

Find a target in Slack (ex: a channel, a user to send a dm, etc)

**input** `object`

**query** `string` *required*

What to search for, ex name of a channel, a user, etc.

**channel** `enum\<string\>` *required*

Which channel to look into, ex: dm, channel

Available options: `dm`, `channel`

**output** `object`

**targets** `array` *required*

The matching targets

**array item properties**

**displayName** `string` *required*

The display name of the target

**tags** `object` *required*

The tags of the target

**channel** `enum\<string\>` *required*

The type of channel of the target

Available options: `dm`, `channel`

### Get Channels Info

Get information about Slack channels one page at a time. Returns channel details for the current page and a cursor for the next page.

**input** `object`

**includeArchived** `boolean`

Whether to include archived channels in the results

**includePrivate** `boolean`

Whether to include private channels in the results

**includeDm** `boolean`

Whether to include direct messages in the results

**cursor** `string`

Pagination cursor for fetching the next page of channels. Omit for the first page.

**output** `object`

**channels** `array` *required*

List of channels on this page

**array item properties**

**id** `string` *required*

The Slack ID of the channel

**name** `string` *required*

The name of the channel

**topic** `string` *required*

The topic of the channel

**purpose** `string` *required*

The purpose of the channel

**numMembers** `number` *required*

The number of members in the channel

**isPrivate** `boolean` *required*

Whether the channel is private

**isArchived** `boolean` *required*

Whether the channel is archived

**isDm** `boolean` *required*

Whether this is a direct message conversation

**userId** `string` *required*

The Slack user ID of the other participant (for 1:1 DMs)

**creator** `string` *required*

The Slack user ID of the channel creator

**created** `number` *required*

The Unix timestamp of when the channel was created

**nextCursor** `string` *required*

Cursor for the next page. Empty string if no more pages.

### Get or Create a Conversation

Proactively create a conversation from a bot

**input** `object`

**conversation** `object` *required*

**channelId** `string`

The Slack channel ID. If provided, the channel name lookup is skipped. (for channel type)

**output** `object`

**conversationId** `string` *required*

The Botpress ID of the created conversation

### Get User Profile

Get information about a user

**input** `object`

**userId** `string` *required*

The ID of the user to retrieve information about

**output** `object`

**firstName** `string`

The first name of the user

**lastName** `string`

The last name of the user

**email** `string`

The email of the user

**displayName** `string`

The display name of the user

### Retrieve Message

Retrieve a message from Slack

**input** `object`

**ts** `string` *required*

The timestamp of the message to retrieve

**channel** `string` *required*

The channel of the message to retrieve

**output** `object`

**type** `string` *required*

The type of the message

**user** `string` *required*

The user who sent the message

**ts** `string` *required*

The timestamp of the message

**text** `string` *required*

The text of the message

### Sync Members

Sync Slack workspace members to Botpress users. This action keeps track of the last sync timestamp and will only sync updated members since the last sync.

**input** `object`

This Card has no input fields.

**output** `object`

**syncedCount** `number` *required*

The number of members synced

### Update Channel Topic

Update the topic of a channel

**input** `object`

**topic** `string` *required*

The new topic of the channel

**channelId** `string` *required*

The channel id of the target channel

**output** `object`

This Card has no output.

***

## Triggers

{/* vale off */}

Here's a reference for all [Triggers](https://botpress.com/docs/studio/concepts/triggers.md) available with the integration:

> [!TIP]
>
> You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.

### Member Joined Channel

Triggered when a member joins a channel

**payload** `object`

**botpressUserId** `string` *required*

The Botpress ID of the user who joined the channel

**botpressConversationId** `string` *required*

The Botpress ID of the channel the user joined

**inviterBotpressUserId** `string`

The Botpress ID of the user who invited the new member

**targets** `object` *required*

Slack IDs of the user, channel and inviter

**slackUserId** `string` *required*

The Slack ID of the user who joined the channel

**slackChannelId** `string` *required*

The Slack ID of the channel the user joined

**slackInviterId** `string`

The Slack ID of the user who invited the new member

### Member Joined Workspace

Triggered when a member joins the workspace

**payload** `object`

**userId** `string` *required*

The Botpress ID of the user who joined the workspace

**target** `object` *required*

Slack user who joined the workspace

**userId** `string` *required*

The Slack ID of the user who joined the workspace

**userName** `string` *required*

The username of the user who joined the workspace

**userRealName** `string` *required*

The real name of the user who joined the workspace

**userDisplayName** `string` *required*

The display name of the user who joined the workspace

### Member Left Channel

Triggered when a member leaves a channel

**payload** `object`

**botpressUserId** `string` *required*

The Botpress ID of the user who left the channel

**botpressConversationId** `string` *required*

The Botpress ID of the channel the user left

**targets** `object` *required*

Slack IDs of the user and channel

**slackUserId** `string` *required*

The Slack ID of the user who left the channel

**slackChannelId** `string` *required*

The Slack ID of the channel the user left

### Reaction Added

Triggered when a reaction is added to a message

**payload** `object`

**reaction** `string` *required*

The reaction that was added

**userId** `string`

The ID of the user who added the reaction

**conversationId** `string`

The ID of the conversation

**targets** `object` *required*

The targets of the reaction

**dm** `object`

The DMs targeted by the reaction

**channel** `object`

The channels targeted by the reaction

**thread** `object`

The threads targeted by the reaction

### Reaction Removed

Triggered when a reaction is removed from a message

**payload** `object`

**reaction** `string` *required*

The reaction that was removed

**userId** `string`

The ID of the user who removed the reaction

**conversationId** `string`

The ID of the conversation

**targets** `object` *required*

The targets of the reaction

**dm** `object`

**channel** `object`

**thread** `object`

### Workflow Webhook

Triggered when the workflow webhook is triggered

**payload** `object`

**value** `string`

The value of the workflow webhook

**userId** `string`

The Slack ID of the user who triggered the workflow

***

## Tags

You can read [event tags](https://botpress.com/docs/studio/guides/advanced/event-properties.md#param-tags) to get information about an active Slack conversation:

### Slack conversation ID

To get the Slack conversation ID:

`event.tags.conversation["slack:id"]`

### Slack thread ID

To get the Slack conversation thread ID (if it's a thread):

`event.tags.conversation["slack:thread"]`

### Slack user ID

To get the Slack user ID:

`event.tags.user["slack:id"]`

### Slack message ID

To get the Slack message ID:

`event.tags.message["slack:id"]`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.