- Installation & Setup
- Supported Features
- Usage with a Slack App (recommended)
- Usage with the Realtime API
- Usage with an outgoing webhook
- Sending Slack Menus
First you need to pull in the Slack Driver.
composer require botman/driver-slackThen load the driver before creating the BotMan instance (only when you don't use BotMan Studio):
DriverManager::loadDriver(\BotMan\Drivers\Slack\SlackDriver::class);
// Create BotMan instance
BotManFactory::create($config);Or if you use BotMan Studio:
php artisan botman:install-driver slackSlack is a cloud-based set of team collaboration tools and services.
{callout-info} If you're using ngrok be aware that Slack has a timeout of 3 seconds. When using ngrok, depending on your location and connection speed, the time it takes for Slack to get a 200 OK can be longer than 3 seconds. In such cases you'll notice that your bot will answer multiple times. If you're facing this issue a possible solution is to deploy your bot to a production server or try to change the ngrok server location.
This is a list of features that the this driver supports. If a driver does not support a specific action, it is in most cases a limitation from the messaging service - not BotMan.
| Feature | Supported? |
|---|---|
| Question-Buttons | ✅ |
| Image Attachment | ✅ |
| Video Attachment | ✅ |
| Audio Attachment | ✅ |
| Location Attachment | ❌ |
The easiest way of making use of all BotMan features in your Slack team, is to create your own Slack app. You can do this at the Slack API website.
Once you have created a new Slack app, you need to configure three sections:
Interactive messages allow your chatbot to respond to message buttons. If you want to use this feature, just configure it and provide the URL that points to your BotMan logic / controller.
Event subscription is needed, so that your BotMan application receives all incoming messages. You can either use event subscriptions or the Realtime API. When configuring your Slack app for event subscriptions, provide the URL that points to your BotMan logic / controller in the "Request URL" field.
Then subscribe for these bot events:
message.channels - A message was posted to a channel
message.im - A message was posted in a direct message channel
This is the most obvious part - to communicate with BotMan in your Slack team, you need a bot user. Just give it a nice name.
After you have configured these sections, go to "Install App" and install the app in your own team.
Take note of the Bot User OAuth Access Token and use this token as your slack_token configuration parameter.
That's it.
{callout-info} Please note: The Realtime API requires the additional composer package
mpociot/slack-clientto be installed.Simply install it using
composer require mpociot/slack-client.
Add a new Bot user to your Slack team and take note of the bot token slack gives you.
Use this token as your slack_token configuration parameter.
As the Realtime API needs a websocket, you need to create a PHP script that will hold your bot logic, as you can not use the HTTP controller way for it.
<?php
require 'vendor/autoload.php';
use React\EventLoop\Factory;
use BotMan\BotMan\BotManFactory;
use BotMan\BotMan\Drivers\DriverManager;
use BotMan\Drivers\Slack\SlackRTMDriver;
// Load driver
DriverManager::loadDriver(SlackRTMDriver::class);
$loop = Factory::create();
$botman = BotManFactory::createForRTM([
'slack' => [
'token' => 'YOUR-SLACK-BOT-TOKEN',
],
], $loop);
$botman->hears('keyword', function($bot) {
$bot->reply('I heard you! :)');
});
$botman->hears('convo', function($bot) {
$bot->startConversation(new ExampleConversation());
});
$loop->run();Then simply run this file by using php my-bot-file.php - your bot should connect to your Slack team and respond to the messages.
Add a new "Outgoing Webhook" integration to your Slack team - this URL needs to point to the controller where your BotMan bot is living in. You will find this integration when you search for Outgoing WebHooks in the Slack Apps Directory.
To let BotMan listen to all incoming messages, do not specify a trigger word, but define a channel instead.
With the Webhook implementation, there is no need to add a slack_token configuration.
BotMan supports sending Slack's interactive message menus through an expressive and easy to use API. They can be used in combination with BotMan's conversation questions.
There are multiple ways to define an interactive message menu. You can simply attach a Menu object to your question, just as you would with regular Buttons.
You can access the selected option(s) using $answer->getValue() which will then return an array containing the selected option values.
// Inside your conversation
$question = Question::create('Would you like to play a game?')
->callbackId('game_selection')
->addAction(
Menu::create('Pick a game...')
->name('games_list')
->options([
[
'text' => 'Hearts',
'value' => 'hearts',
],
[
'text' => 'Bridge',
'value' => 'bridge',
],
[
'text' => 'Poker',
'value' => 'poker',
]
])
);
$this->ask($question, function (Answer $answer) {
$selectedOptions = $answer->getValue();
});
// Inside your conversation
$question = Question::create('Who wins the lifetime supply of chocolate?')
->callbackId('select_users')
->addAction(
Menu::create('Who should win?')
->name('winners_list')
->chooseFromUsers()
);
$this->ask($question, function (Answer $answer) {
$selectedOptions = $answer->getValue();
});
// Inside your conversation
$question = Question::create('It\'s time to nominate the channel of the week')
->callbackId('select_channel')
->addAction(
Menu::create('Which channel changed your life this week?')
->name('channels_list')
->chooseFromChannels()
);
$this->ask($question, function (Answer $answer) {
$selectedOptions = $answer->getValue();
});// Inside your conversation
$question = Question::create('Let\'s get a productive conversation going')
->callbackId('select_conversation')
->addAction(
Menu::create('Who did you talk to last?')
->name('conversations_list')
->chooseFromConversations()
);
$this->ask($question, function (Answer $answer) {
$selectedOptions = $answer->getValue();
});