Docs

Slack

Add a bot to Slack using the official integration.

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

Setup

    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.

    For advanced use cases, you can use your own Slack app with our integration.

    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.

    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. 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:
    
{
"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
}
}

    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
    1. Select Create. This creates a Slack app with all the necessary scopes and subscriptions for the Botpress Slack integration.

    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.
    1. Scroll up to Advanced token security via token rotation, then select Opt In.

    Configure the integration in Botpress

    Now you can use your app’s credentials to fill in the configuration fields from Step 1:

    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.

    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.

    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.

    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.

    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.

    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.

    Typing indicator emoji

    When the Typing indicator emoji option is enabled, the bot will react 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.

    If you want the bot to only reply in a thread when mentioned, enable the Require Bot Mention for Reply Threading option.

    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.

    Rich text processing

    Slack uses a proprietary markup language, mrkdwn, to format rich text in messages. Since Botpress uses standard Markdown 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

    Add Reaction

    Add a reaction to a message

    inputobject

    Find Target

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

    inputobject
    outputobject

    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.

    inputobject
    outputobject

    Get or Create a Conversation

    Proactively create a conversation from a bot

    inputobject
    outputobject

    Get User Profile

    Get information about a user

    inputobject
    outputobject

    Retrieve Message

    Retrieve a message from Slack

    inputobject
    outputobject

    startTypingIndicator

    inputobject

    stopTypingIndicator

    inputobject

    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.

    outputobject

    Update Channel Topic

    Update the topic of a channel

    inputobject

    Triggers

    Member Joined Channel

    Triggered when a member joins a channel

    payloadobject

    Member Joined Workspace

    Triggered when a member joins the workspace

    payloadobject

    Member Left Channel

    Triggered when a member leaves a channel

    payloadobject

    Reaction Added

    Triggered when a reaction is added to a message

    payloadobject

    Reaction Removed

    Triggered when a reaction is removed from a message

    payloadobject

    Workflow Webhook

    Triggered when the workflow webhook is triggered

    payloadobject

    Tags

    You can read event 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"]