In this tutorial I’m going to show you how to build a Slack bot with Botonomous Framework and Events API. If you have followed the last tutorial you already know how to prepare the server and install Botonomous Framework.
Why Events API?
Events API is a flexible way for Slack apps and bots to listen to different events and activities in order to respond accordingly. It’s also more advanced compared to Slash Commands since it’s triggered automatically rather manually by a user.
Prepare Botonomous Framework
We can still use our Lunch App we created in the last tutorial but there are some changes need to be applied.
Add Bot User
Using Events API is a bit different from Slash Commands and you should add a bot user to your app. This way the bot can be invited to different channels and can answer the questions. So under “Basic Information” and “Add features and functionality” click on “Bots”:
After adding the bot user you will be asked to reinstall your app.
Authorize and finally click on “Save Changes”.
Configuration changes
All the necessary configurations are mentioned here but let’s do them together here again. So with any text editor open this file:
/Applications/MAMP/htdocs/lunch-bot/src/Botonomous/Config.php
:
And apply the following changes:
- Set
listener
toevent
- Make sure
verificationToken
has got the correct value - In your app page and under “App Credentials”, the same place
verificationToken
is located,
find the values forclientId
andclientSecret
- Set
appId
by checking your app URLhttps://api.slack.com/apps/YOUR_APP_ID_GOES_HERE/general
- Head to
https://api.slack.com/apps/YOUR_APP_ID_GOES_HERE/oauth
and find the values foroAuthToken
andbotUserToken
Setup the events in Slack
Enable events by following these steps:
- Head to the Lunch App page on Slack
- Under “Basic Information” click on “Event Subscriptions”
- Turn the Enable Events switch on
- As you can see a request URL should be provided to receive HTTP posts coming from Slack. Slack sends a request including a
challenge
parameter just after entering the URL so make sure MAMP and ngrok are running. If everything is fine you should see Verified label.
- Under “Subscribe to Team Events” click on “Add Team Event” and choose
message.channels
andmessage.im
events and save changes. Again you need to reinstall the app because of permission scopes changes. - Invite the bot in a channel by entering
/invite @lunch_app
- In the channel type
@lunch_app Hi
and if everything is fine you should get a response back from the bot
- At this stage you need to know the bot id. So first make sure that
logger
is enabled in the config and then check thesrc/Botonomous/tmp/bot.log
. In the log file you will find the bot id in the following format:<@U5W97U92S> Hi
. Please note if your bot is used publicly you should get the bot id after calling\Botonomous\OAuth::doOauth
and then\Botonomous\OAuth::getBotUserId
. - Update
src/Botonomous/Config.php
with the values ofbotUserId
andbotUsername
in this caseU5W97U92S
andlunch_app
- In the channel type
@lunch_app /ping
and you should getpong
response
Add a new plugin
A Botonomous plugin can be considered as a feature e.g. Help
. Every plugin or feature can have one or many functionalities known as commands. For example /help
command belongs to Help
plugin. In order to add a new plugin a folder containing the plugin class should be added to src/Botonomous/plugin
folder. For example, help plugin has got src/Botonomous/plugin/help
folder
containing src/Botonomous/plugin/help/Help.php
file (\Botonomous\plugin\help\Help
class).
Add a new command
The first step to add a new command is to add a new element to $commands
array located in src/Botonomous/CommandContainer.php
. For example the $commands
array looks like this for /ping
action:
1 2 3 4 5 6 7 |
protected static $commands = [ 'ping' => [ 'plugin' => 'Ping', 'action' => 'index', 'description' => 'Use as a health check', ] ]; |
Please note if the action is not specified, index
is considered as the default action. The next step is to add a function with the same name as the action in the plugin class:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
/** * Class Ping. */ class Ping extends AbstractPlugin { /** * @return string */ public function index() { return 'pong'; } } |
Please note since message.channels
is selected, every message in the channel triggers sending a request from Slack to the bot engine and probably the defaultCommand
. To only consider the messages that your bot is mentioned in them \Botonomous\Slackbot::youTalkingToMe
function can be used:
1 2 3 4 5 6 7 8 9 |
/** * @return string */ public function index() { if ($this->getSlackbot()->youTalkingToMe() === true) { return 'pong'; } } |
You might also need to set confirmReceivedMessage
which is used as the global confirmation message to an empty string and handle the confirmation message in the plugin itself.
So Slack Event setup in Botonomous is almost as easy as Slash Commands but it gives you more flexibility at the end of the day.
Leave a Reply