This project is archived. Slack has released the Events API that achieves the same.
Ready to create a Slack bot, but not-so-ready to code a Real-Time Messaging app? Wondering how you’re going to maintain a bot across hundreds of teams?
Don’t worry, no need to change the way you code, let Bot2Hook take care of RTM for you. Thanks to Bot2Hook, developing a bot is as easy as developing a slash command app.
Bot2Hook is written in PHP and uses RabbitMQ, but you only need to know Docker to run it.
Bot2Hook is brought to you by the makers of MailClark (we use it in production).
An alternative solution is Relax by our friends at Nestor.
Under the hood
Bot2Hook has three main components:
- An incoming hook called to add new bots to the system. It can either be a webhook (default), or a RabbitMQ queue.
- A service which opens a websocket client connection for each bot:
- When a bot receives an event, this service pushes it to a RabbitMQ queue.
- This service also opens a websocket server connection, used to receive ‘add a new bot’ messages.
- A consumer which consumes all RabbitMQ queues and launches separate processes.
Prerequisites
- composer
- docker
- docker-compose
Installation
git https://github.com/Mailclark/bot2hook.git
cd bot2hook
Storage folders
Execute these commands in the root folder.
mkdir -m 777 -p storage
mkdir -m 777 -p storage/sqlite
mkdir -m 777 -p storage/logs
touch storage/logs/error.log
chmod 777 storage/logs/error.log
mkdir -m 777 -p storage/rabbitmq
Composer
Execute composer install
in the root folder.
Testing Boot2Hook
Define the local domain
Edit the /etc/hosts
file using your favorite editor, with root permissions.
Add this line to the file:
127.0.0.1 bot2hook.local
Edit the PHP config file
Go to the sample/config/
folder. Copy the sample_webhook.php
file into a new testing_webhook.php
.
Edit the new testing_webhook.php
file.
Uncomment the logger
section.
Define the Slack team for Logger
Go to https://api.slack.com/web, scroll down to the bottom of the page and create a personal token associated to your team.
Copy and paste this token to the token
subkey of the logger->slack
array of the testing_webhook.php
config file.
In the channel
subkey, indicate the channel to receive logs (e.g. #debug
— it has to be an existing channel).
Start Docker containers
docker-compose -f docker/docker-compose.yml -f sample/docker-compose.webhook.yml up -d
You’ll receive 3 messages in the log channel:
Boot2Hook server starting
Boot2Hook consumer starting
phpws listening on tcp://0.0.0.0:12345
Check out Docker-compose CLI documentation for more commands.
Create a test bot for your Slack team
Go to the ‘Configure Bots’ page in Slack App Directory: https://my.slack.com/apps/manage/A0F7YS25R-bots
Install a bot, or configure a new one for your team:
- Choose his name.
- Save the integration.
- Go to http://bot2hook.local/add_bot.php?bot=XXX replacing
XXX
with the new bot API token you’ve just created.
You’ll receive a wave of new messages in the log channel, including a message beginning with:
Sample webhook event received:
Followed by the JSON of the rtmStart event.
Talk to your bot!
The test bot must now appear as connected in your Slack team. Talk to him, you’ll receive the events corresponding to your messages in the log channel.
Configuration
We recommend to keep the sample/
folder for future reference. Duplicate it and rename the new folder.
Docker-compose file
Edit your_conf_folder/docker-compose.webhook.yml
.
- Update the
bot2hook_rabbitmq
parameters: - User and password to connect to RabbitMQ Management UI;
- Change the port, if needed (by default http://your.bot2hook.domain:8085).
- Update
volumes
: - Replace
sample/
with the path to your files; - Remove the third volume pointing to sample/public, only used for testing purposes.
- Update
CONF_FILE
: pick any name you like. - Remove
extra_hosts
, only used for testing purposes.
Apache config file
Edit your_conf_folder/apache2/bot2hook.conf
. Rename this file if you like—just keep the .conf
extension.
- Update
CONF_FILE
with the value found in the docker-compose file. - Update
ServerName
with the domain where you’ll host your Bot2Hook instance.
PHP config file
Edit your_conf_folder/config/sample_webhook.php
. Name this file with the CONF_FILE
value (found in both the docker-compose and Apache config files), keep the .php
extension.
- In production, we recommend you comment the following lines:
error_reporting
,display_errors
,debug
. - Choose a
signature_key
, used for encryption purposes. Your pet’s name will do ;) - Uncomment the
logger
section if — as for local testing — you want to monitor Bot2Hook activity in a Slack channel. - Update
priority
to be less notified (e.g.Logger:CRIT
— check out Logger documentation). - Uncomment the
server
section and updatewebhook_url
with the URL to receive webhooks.
Signature check
Whenever you send data to the ‘add a new bot’ webhook, or Bot2Hook sends data to your external webhook, a signature must used for the data’s origin to be certified.
This signature is passed in the BOT2HOOK_SIGNATURE
header.
Have a look at sample/public/webhook.php
and app/classes/Bot2Hook/Signature.php
to see how to generate or validate a signature.
API
Add a new bot
To add a bot to Bot2Hook, 2 options:
[
'bot' => 'the-bot-token',
]
or
[
'bot' => [
'bot_id' => 'BOT_ID',
'bot_token' => 'the-bot-token',
'team_id' => 'TEAM_ID',
'users_token' => [
'FIRST_USER_ID' => 'first-user-token',
'SECOND_USER_ID' => 'second-user-token',
],
],
]
The users_token
is used by Bot2Hook to retrieve missing messages, using Slack Web API, when a bot gets disconnected (it does happen). This operation isn't allowed with a bot token.
Receiving messages
When a bot receives an event from Slack, Bot2Hook posts it to your webhook URL.
[
'webhook_event' => [
'type' => 'event_type',
'bot' => 'BOT_ID',
'team' => 'TEAM_ID',
'event' => [
//... Same event receive from Slack
],
]
]
For event and type keys, read Slack API documentation.
There are also three Bot2Hook-specific event types:
channel_recovery
(5 keys:type
,bot
,team
,channel
andlatest
) when Bot2Hook has missed messages in a channel and isn’t able to recover them.group_recovery
(5 keys:type
,bot
,team
,group
andlatest
) when Bot2Hook has missed messages in a group and isn’t able to recover them.bot_disabled
(3 keys:type
,bot
andteam
) when Bot2Hook receives an error indicating that the bot token has been revoked.
Use RabbitMQ only (no webhooks)
Bot2Hook uses RabbitMQ in the background to queue events. You can actually disable webhook processes and use RabbitMQ only. MailClark uses Bot2Hook this way.
To do so:
- Write your own docker-compose base file, without the
bot2hook_rabbitmq
container.- In the
bot2hook_lasp
section, updatelinks
with your RabbitMQ container. - In the
bot2hook_lasp
section, don’t mount a volume for the Apache configuration.
- In the
- Write your own PHP config file, using
sample/config/sample_rabbithook.conf
as a basis.- Update the
rabbitmq
section with your RabbitMQ configuration. - In the
server
section, you may change the name of the queue used to add bots to Bot2Hook.
- Update the