Slack¶
The following steps give you an overview of the steps necessary to create a bot for Slack. Since the user interface of Slack is regularly subject to change, the following steps are not entitlement to completeness or accurateness. However, we update the documentation on a regular basis and look forward to your hints.
Slack is one of the first messaging platforms to support chatbots, and it supports several different ways to integrate chatbots.
- You can specify a webhook for a Slack channel (it could be a one-on-one conversation or a group conversation). All messages in the channel are sent to the webhook using HTTP POST. The plain text HTTP response from the webhook is displayed in the channel as a bot message. This is probably the easiest way to incorporate a chatbot into a Slack conversation.
- You can create a custom bot in your Slack team. The custom bot has a unique token. First, write an application to connect to Slack servers by using a custom TCP/IP network API called Slack Real Time Messaging (RTM) API. The application identifies itself to Slack by using the bot's secret token. Slack sends all user interactions with the bot to your connected application by using the TCP/IP channel and displays your application's responses as the bot messages.
- You can bundle a Slack bot in a Slack application. Go through an OAuth process to install your Slack application using a link. After your Slack application is installed, your bot appears in the Slack team. From that point on, Slack can interact with your application by using an RTM or an HTTP Events API.
The bot account of the Business Bot Platform is a full-fledged Slack application. It uses the HTTP Events API to communicate with the Slack platform. This implementation take care of the OAuth authentication flow and storing the tokens as well as receiving messages by using the Events API and sending responses back by using the Slack web API.
With Slack, you can configure three separate web endpoints: one for OAuth, one for Events API, and one for the interactive button clicks. Here, you use always the same WebHook URL of the Business Bot Platform for all three web endpoints a Slack application requires so you can focus on the business logic of your bot application.
- Brief overview: The installation takes place in multiple steps:
-
- (BBP) Create a new bot account for Slack
- (Slack) Create a new bot account at Slack
- (BBP) Complete bot account configuration on Business Bot Platform
Step 1: (BBP) Create a new bot account for Slack¶
Webhooks are used to send various events including messages, authentication events and callback events from Slack to the Business Bot Platform. Because Slack only supports the WebHook concept for receiving messages from Slack, no other methods are supported.
-
Login to the Business Bot Platform:
- PublicCloud users use the URL: https://my.bbp.local/
- PrivateCloud users use the URL: https://mysuffix.bbp.local/
-
Choose
Chatbot Administration
→Instant Messenger Accounts
→Create Bot Account
. The following data is required to create the bot account:Field Example value Name: MySlackBotAccount Description: BotAccount for department Z Instant Messenger: Slack -
The bot account has been created and must still be configured with the instant messenger account information. To do this, click on the icon
Settings
and modify the following parameters:Required Fields Description Example value Messenger.WebhookId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
the Webhook-Id which is a part of the Webhook-URLdb6a19e5-e281-4683-947c-e5490cbf98da
Slack.ClientId [12x12 character string]
is the Slack Client-Id provided by Slack123456789012.123456789012
Slack.ClientSecret [32 character string]
is the Slack Secret (Password) provided by Slack4b10e88651fef234e6f7d953cb2c5dc1
Slack.ValidationToken [4x12x24 characters]
is the validation token to access the Slack API (do not change)xoxb-354768715056-RTD8RDuVoHtLZQxgPdZDhtM8
Slack.SendingTo.ChannelName [9 character string]
is the Slack-Channel to send messages instantlyDAGAKJCUE
Slack.TeamId [9 character string]
is the Slack Team-IdT9CT6F1A7
Slack.UserInfo.UserId [9 character string]
is the Slack-User ID of this accountUAENLM11N
The Messenger.WebhookId
is the unique identifier for the bot account. Slack requires for the webhook a full
URL which contains the WebhookId
. In Slack, the WebHook URL is the following compound address:
Syntax: https://demo.bbp.local/bbp/webhook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Example: https://demo.bbp.local/bbp/webhook/db6a19e5-e281-4683-947c-e5490cbf98da
The OAuth tokens are issued by Slack when a user installs the application into a Slack team. The Business Bot Platform saves the token because it is needed later when the platform needs to call the Slack web API to send messages into Slack.
Note
The Slack accepts only secure connections (HTTPS), therefore the Business Bot platform with webhook must be reachable on an SSL-enabled server. HTTP is not supported by Slack.
Other mandatory fields such as Slack.ClientId
and Slack.ClientSecret
can
not be filled yet until the Slack bot has been configured, which will be
explained in the next section.
Step 2: (Slack) Create a new bot account at Slack¶
As mentioned earlier, the chatbot can be packaged in a Slack application for easy installation by teams. This section explains the process to create a Slack application.
Configure Slack App
- Open website
https://api.slack.com/apps
to see the list of all created Slack apps. From there, create a new app. -
Click button
Create New App
-
Enter the App Name (z.B.
BBPTestBot
) and Slack workspace. Once you have created the Slack-App, the left menu shows the steps to complete a Slack application. -
The Basic Information tab shows the application's ID and secret, which are required in the OAuth flow when a user tries to add the application to a team. On this tab, upload an icon for the app, complete the application descriptions, and provide links to the application website and terms and privacy policies.
-
On the OAuth & Permissions tab, enter the URL to the Business Bot platform as the OAuth redirect URL. The Business Bot Platform handles the OAuth tokens and calls the Business Bot Plugin implementations. The URL consists of the base URL and the
Messenger.WebhookId
as described above. -
On the following tab, you have to specify the permissions that are required by the Business Bot Platform. In this case, you have to choose the
bot
permission, which contains all permissions for a bot to receive and respond to messages. -
On the Bot User tab, specify a name for the chatbot in your Slack application. After the user installs this application, the named chatbot appears as a team member.
-
On the Interactive Components tab, configure how the chatbot responds to button click events in the bot conversation. As mentioned earlier, you can use the same URL to the Business Bot platform as used before.
-
On the Slash Commands tab, you can add slash commands (e.g.,
/myCommand
) to your application. It is not needed here. -
On the Event Subscriptions tab, the Business Bot platform can subscribe to user messages (that is, events). Also here, use as request URL the WebHook URL of the Business Bot platform.
You can specify the events to be delivered to your bot. Those events are sent using HTTP POST to the Business Bot platform for processing. Following events have been selected:
message.channels
,message.groups
,message.im
, andmessage.mpim
.
Step 3: (BBP) Complete bot account configuration on Business Bot Platform¶
The easiest way to test the Slack application is to use the Add to
Slack button. The button is actually a link. Replace the
CLIENT_ID
in the URL with the your
client ID displayed in the Basic Information tab as follows:
https://slack.com/oauth/authorize?scope=bot&client_id=CLIENT_ID
After the user clicks the link, they are asked to authorize your application to access the required information from the team. After the user consents, the application is installed and the chatbot appears in the team, available for conversations.
Tip
Alternatively, you can add the application to the workspace on the
Install App tab. Click on the button Install App
and agree to the installation.
Subsequently, you need to provide the key of the Slack parameter Bot User OAuth Access Token
to the
Business Bot platform. On the Business Bot platform, add the key to the
bot account settings Slack.ValidationToken
.
Finally, the configuration of the bot account has to be completed on the Business Bot Platform.
- Choose
Chatbot Administration
→Instant Messenger Accounts
→ IconSettings
. -
Parameter
Slack.SendingTo.ChannelName
represents the name of the Slack channel, in which you want to receive push messages. The name of the Slack channel can be displayed over the Slack user interface. Therefore, navigate your browser tohttps://citunius.slack.com/messages/
and choose the channel. Subsequently, you have to define the Slack channel name in parameterSlack.SendingTo.ChannelName
as shown below: -
Parameter
Slack.TeamId
represents the unique Slack Team number. The Slack-Team-Id can be determine underhttps://api.slack.com/apps
→ Select App → MenueInstalled App Settings
. Move the mouse over the button to display the link in the browser status bar
The user account for the bot is now configured and will be used later when creating a bot for Slack.