botonomous-logo

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”:

Add Bot User

After adding the bot user you will be asked to reinstall your app.

re authorise 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 to event
  • 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 for clientId and clientSecret
  • Set appId by checking your app URL https://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 for oAuthToken and botUserToken

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”

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.

Enabled Events

  • Under “Subscribe to Team Events” click on “Add Team Event” and choose message.channels and message.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

Response from 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 the src/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 of botUserId and botUsername in this case U5W97U92S and lunch_app
  • In the channel type @lunch_app /ping and you should get pong 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:

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:

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:

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.