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.
3.x to 4.xVersion 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:
2.x to 3.xVersion 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'
}
}
]
}
1.x to 2.xVersion 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:
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.This is the simplest way to set up the integration. To set up the Slack integration using OAuth, click the authorization button and follow the instructions to connect your Botpress chatbot to Slack. This method is recommended as it simplifies the configuration process and ensures secure communication between your chatbot and Slack.
When using this configuration mode, a Botpress-managed Slack application will be used to connect to your workspace. The application will have the necessary permissions to send and receive messages, access channels, and perform other actions on your behalf. If you require more granular control over the permissions or prefer to use your own Slack application, you can opt for the manual configuration mode instead.
This configuration mode automatically creates a dedicated Slack app for your bot using the Slack App Manifest API. Unlike the default OAuth method which uses a shared Botpress-managed Slack app, this gives you your own Slack app with full control, without the manual setup steps of the manual configuration mode.
The created Slack app is fully yours and visible at api.slack.com/apps.
If you prefer to manually configure the integration, you can provide a bot token to connect your custom Slack application to Botpress. To set up the Slack integration manually, follow these steps:
https://webhook.botpress.cloud/oauth
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 intompim: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.xoxe-1-) or legacy Bot Token (starts with xoxb-). You will need it to set up the integration on Botpress. You may need to refresh the page in the Slack API portal to see the token.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.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:
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.
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.