botpress--botpress/integrations/slack/hub.md

The Slack integration enables seamless communication between your AI-powered chatbot and Slack, the popular collaboration platform. Connect your chatbot to Slack and streamline team communication, automate tasks, and enhance productivity. With this integration, your chatbot can send and receive messages, share updates, handle inquiries, and perform actions directly within Slack channels. Leverage Slack's extensive features such as chat, file sharing, notifications, and app integrations to create a powerful conversational AI experience. Enhance team collaboration and streamline workflows with the Slack Integration for Botpress.

Migrating from version 4.x to 5.x

Version 5.0 of the Slack integration introduces a unified setup wizard and changes to several actions.

Configuration changes

The separate configuration modes ("OAuth", "Manual configuration" and "App Manifest") have been replaced by a single unified setup wizard. When you save the integration, the wizard will prompt you to choose between the default Botpress app, creating a new Slack app via App Manifest, or using an existing Slack app. If you previously used a manual or App Manifest configuration, you will need to re-run the setup wizard.

Action changes

• startDmConversation and startChannelConversation have been removed. Use getOrCreateChannelConversation instead by passing the Slack channel ID of the conversation.
• getChannelsInfo is a new action that returns paginated information about Slack channels, including support for filtering by archived, private, and DM channels. Use the cursor parameter to paginate through results.
• getOrCreateChannelConversation now accepts a conversation object with a channelId field instead of requiring a Slack user ID.

Migrating from version 3.x to 4.x

Version 4.0 of the Slack integration refines the bot's reply behaviour by introducing the possibility to reply in either channel, thread or channel and thread. This replaces the previous createReplyThread configuration option by adding the ability to only reply in threads.

Features that have been added are:

• Improved reply behaviour
• Added rich text! Users are now able to input markdown text and it display in rich text in slack

Migrating from version 2.x to 3.x

Version 3.0 of the Slack integration changes the way the mention system works with Botpress. It now swaps the mention text from slack to fullname and gives a infos about the mention. the payload looks like this:

{
   text: 'hey <@John Doe>!'
   mentions: [
      {
         type: 'user',
         start: 6,
         end: 14,
         user: {
            id: 'user_abc123', // This will be a botpress user id
            name: 'John Doe'
         }
      }
   ]
}

It will also do the same when the bot sends a string with mentions in it. The payload needs to look like this to work.

{
   text: 'hey <@John Doe>!'
   mentions: [
      {
         type: 'user',
         start: 6,
         end: 14,
         user: {
            id: 'U123', // This needs to be a slack member id
            name: 'John Doe'
         }
      }
   ]
}

Migrating from version 1.x to 2.x

Version 2.0 of the Slack integration introduces rotating authentication tokens. If you previously configured the integration using automatic configuration, no action is required once you update to the latest version.

If you configured the integration using manual configuration, you will need to update your Slack app to use rotating tokens. To do this, follow these steps:

1. Go to the Slack API portal and navigate to your app.
2. In the "OAuth & Permissions" section, scroll down to the "Advanced token security via token rotation" section.
3. Click "Opt In" to enable token rotation. Confirm you wish to opt in.
4. Copy the Refresh Token (starts with xoxe-1-) or legacy Bot Token (starts with xoxb-) and paste it into the integration settings in Botpress. You may need to refresh the page in the Slack API portal to see the new token.

Configuration

When you add the Slack integration to your bot and save the configuration, a setup wizard will guide you through connecting to Slack. The wizard presents three options:

Use the default Botpress Slack Application (recommended)

This is the simplest way to set up the integration. A Botpress-managed Slack application will be used to connect to your workspace. Simply select this option in the wizard and you will be redirected to Slack to authorize the app. The application has the necessary permissions to send and receive messages, access channels, and perform other actions on your behalf.

Configure a new Slack Application (App Manifest)

This option automatically creates a dedicated Slack app for your bot using the Slack App Manifest API. Unlike the default method which uses a shared Botpress-managed Slack app, this gives you your own Slack app with full control, without the manual setup steps.

Prerequisites

• A Slack workspace where you have admin permissions.

Steps

1. Navigate to api.slack.com/apps and log in.
2. Scroll to the bottom of the page and find the "Your App Configuration Tokens" section.
3. Click "Generate Token" next to the workspace you want to install the bot in. Copy the generated token. Note that configuration tokens expire after 12 hours.
4. In Botpress, add the Slack integration to your bot and save the configuration.
5. In the setup wizard, select "Configure a new Slack Application".
6. Paste your App Configuration Refresh Token and optionally choose a name for the app, then submit.
7. The wizard will automatically create a Slack app with all required scopes, event subscriptions, and interactivity pre-configured.
8. You will be redirected to Slack to authorize the app. Click "Allow" to install it in your workspace.
9. Once complete, you will see a success page. The integration is now configured and ready to use.

The created Slack app is fully yours and visible at api.slack.com/apps.

Use an already existing Slack Application (Manual)

If you already have a Slack app you want to connect to Botpress, select this option in the wizard and provide your app's credentials.

Step 1 - Preparing your Slack application

1. In your browser, navigate to the Slack API portal and log in.

2. Open your Slack app (or create a new one).

3. Navigate to the "OAuth & Permissions" section of your Slack app.

4. Scroll down to the "Redirect URLs" section and add the following URL:

   https://webhook.botpress.cloud/oauth
   

5. Still in the "OAuth & Permissions" section, add the following Bot Token Scopes to your bot token:

   • channels:history: needed to receive incoming messages and to fetch the history of channels the bot gets invited into.
   • channels:manage: needed to open new DMs and to set the current topic.
   • channels:read: needed to obtain a list of all available channels, to retrieve details about conversations, and to receive notifications when a user joins or leaves a channel.
   • chat:write: needed to send messages as @Botpress in channels or DMs.
   • groups:history: needed to receive incoming messages and to fetch the history of private channels the bot gets invited into.
   • groups:read: needed to obtain a list of all available private channels, to retrieve details about conversations, and to receive notifications when a user joins or leaves a private channel.
   • groups:write: needed to open new DMs and to set the current topic.
   • im:history: needed to receive incoming messages and to fetch the history of private channels the bot gets invited into.
   • im:read: needed to obtain a list of all available DMs and to retrieve details about specific DMs.
   • im:write: needed to open new DMs and to set the current topic of existing DMs.
   • mpim:history: needed to receive incoming messages and to fetch the history of multi-person DMs the bot gets invited into.
   • mpim:read: needed to obtain a list of all available multi-person DMs, to retrieve details about conversations, and to receive notifications when a user joins a multi-person DM.
   • mpim:write: needed to open new DMs and to set the current topic.
   • reactions:read: needed to receive notifications when reactions are added.
   • reactions:write: needed to add new reactions to messages.
   • team:read: needed to obtain metadata on your team in order to operate on the right instance of your bot.
   • users.profile:read: needed to retrieve profile information for channel and DM members.
   • users:read: needed to obtain a list of all members of the workspace and to receive notifications when new members join the workspace.
   • users:read.email: needed for the Get User Profile action.

6. Scroll up to the "Advanced token security via token rotation" section and click "Opt In" to enable token rotation. Confirm you wish to opt in.

7. Navigate to the "Basic Information" section and note your Client ID, Client Secret, and Signing Secret.

Step 2 - Completing the setup wizard

1. In Botpress, add the Slack integration to your bot and save the configuration.
2. In the setup wizard, select "Use an already existing Slack Application".
3. Enter the Client ID, Client Secret, and Signing Secret from your Slack app.
4. You will be redirected to Slack to authorize the app. Click "Allow" to install it in your workspace.

Step 3 - Enabling webhooks

1. In the integration settings, copy the webhook URL provided by Botpress. You will need it later.
2. Navigate to the Slack API portal and log in. Open your Slack app.
3. Navigate to the "Event Subscriptions" section of your Slack app.
4. Enable event subscriptions and paste the webhook URL into the "Request URL" field. Save the changes for your Slack app.
5. You may now suscribe to bot events as needed:
   • message.channels: Subscribe to these events to allow the bot to receive messages from channels.
   • messages.groups: Subscribe to these events to allow the bot to receive messages from private channels.
   • messages.im: Subscribe to these events to allow the bot to receive messages from direct messages.
   • messages.mpim: Subscribe to these events to allow the bot to receive messages from multi-party direct messages.
   • reaction_added: Subscribe to these events to allow the bot to know when reactions are added to messages.
   • reaction_removed: Subscribe to these events to allow the bot to know when reactions are removed from messages.
   • member_joined_channel: Subscribe to these events to allow the bot to know when members join channels.
   • member_left_channel: Subscribe to these events to allow the bot to know when members leave channels.
   • team_join: Subscribe to these events to allow the bot to know when new members join the workspace.
6. Save the changes on Slack.

Optional: Set a custom Display Name and Avatar

Regardless of the configuration mode you choose, you can optionally set a custom display name or avatar for your bot. To do this, fill in the following fields as needed:

• Bot Name: If provided, this name will be displayed as the sender in Slack conversations.
• Bot Avatar URL: If provided, the bot's avatar will be updated to the image at this URL. 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.

Replying in threads instead of the main channel

To minimize disruption in busy Slack channels, you can activate reply threading in the integration settings. This feature creates a thread for each incoming message, where the bot will respond. For a more targeted approach, enable the "Require Bot Mention for Replies" to only create threads when the bot is mentioned by name.

Limitations

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

More details are available in the Slack API documentation.