PHP SlackBot 🤖 Create Slack bots in PHP with ease

SlackBot is a framework agnostic PHP library that is designed to simplify the task of developing innovative bots for Slack.

Getting Started

1. Open the Laravel/Symfony/PHP project your new Bot will live in

2. Install SlackBot with composer

3. Obtain a Bot Token on Slack

4. Make your application respond to Slack Event requests

5. Implement your bot logic

Installation using Composer

Require this package with composer using the following command:

$ composer require mpociot/slackbot

Using SlackBot within a Laravel app

SlackBot comes with a Service Provider to make using this library in your Laravel application as simple as possible.

Go to your config/app.php and add the service provider:

Mpociot\SlackBot\SlackBotServiceProvider::class,

Also add the alias / facade:

'SlackBot' => Mpociot\SlackBot\Facades\SlackBot::class

That's it.

Core Concepts

Bots built with SlackBot have a few key capabilities, which can be used to create clever, conversational applications. These capabilities map to the way real human people talk to each other.

Bots can hear things, say things and reply to what they hear.

With these two building blocks, almost any type of conversation can be created.

Basic Usage

Here's an example of using SlackBot with Slack's Event API.

This sample bot listens for the word "hello" - either in a direct message (a private message inside Slack between the user and the bot) or in a message the bot user is invited to.

$slackbot = new SlackBot();
$slackbot->initialize(<my_slack_bot_token>);

// give the bot something to listen for.
$slackbot->hears('hello', function (SlackBot $bot, $message) {
  $bot->reply('Hello yourself.');
});

Developing with SlackBot

Table of Contents

• Receiving Messages
• Sending Messages

Receiving Messages

Matching Patterns and Keywords with hears()

SlackBot provides a hears() function, which will listen to specific patterns in public and/or private channels.

Argument	Description
pattern	A string with a regular expressions to match
callback	Callback function that receives a SlackBot object, as well as additional matching regular expression parameters
in	Defines where the Bot should listen for this message. Can be either SlackBot::DIRECT_MESSAGE or SlackBot::PUBLIC_CHANNEL

$slackbot->hears('keyword', function(SlackBot $bot, $message) {

  // do something to respond to message
  $bot->reply('You used a keyword!');

});

When using the built in regular expression matching, the results of the expression will be passed to the callback function. For example:

$slackbot->hears('open the {doorType} doors', function(SlackBot $bot, $doorType) {
  if ($doorType === 'pod bay') {
    return $bot->reply('I\'m sorry, Dave. I\'m afraid I can\'t do that.');
  }
  return $bot->reply('Okay');
});

Sending Messages

Bots have to send messages to deliver information and present an interface for their functionality. SlackBot bots can send messages in several different ways, depending on the type and number of messages that will be sent.

Single message replies to incoming commands can be sent using the $bot->reply() function.

Multi-message replies, particularly those that present questions for the end user to respond to, can be sent using the $bot->startConversation() function and the related conversation sub-functions.

Single Message Replies to Incoming Messages

Once a bot has received a message using hears(), a response can be sent using $bot->reply().

Messages sent using $bot->reply() are sent immediately. If multiple messages are sent via $bot->reply() in a single event handler, they will arrive in the client very quickly and may be difficult for the user to process. We recommend using $bot->startConversation() if more than one message needs to be sent.

You may pass either a string, or a Question object to the function.

As a second parameter, you may also send any additional fields supported by Slack:

Slack's chat.postMessage API accepts several additional fields. These fields can be used to adjust the message appearance, add attachments, or even change the displayed user name.

$bot->reply()

Argument	Description
reply	String or Question Outgoing response
callback	Optional Array containing additional parameters

Simple reply example:

$slackbot->hears('keyword', function (SlackBot $bot, $message) {

  // do something to respond to message
  // ...

  $bot->reply("Tell me more!");

});

Slack-specific fields and attachments:

$slackbot->hears('keyword', function (SlackBot $bot, $message) {

    // do something...

    // then respond with a message object
    //
    $bot->reply("A more complex response",[
      'username' => "ReplyBot",
      'icon_emoji' => ":dash:",
    ]);

})

Multi-message Replies to Incoming Messages

For more complex commands, multiple messages may be necessary to send a response, particularly if the bot needs to collect additional information from the user.

SlackBot provides a Conversation object that is used to string together several messages, including questions for the user, into a cohesive unit. SlackBot conversations provide useful methods that enable developers to craft complex conversational user interfaces that may span a several minutes of dialog with a user, without having to manage the complexity of connecting multiple incoming and outgoing messages across multiple API calls into a single function.

Start a Conversation

$bot->startConversation()

Argument	Description
conversation	A Conversation object

startConversation() is a function that creates conversation in response to an incoming message. You can control where the bot should start the conversation by calling startConversation in the hears() method of your bot.

Simple conversation example:

$slackbot->hears('start conversation', function (SlackBot $bot, $message) {

  $bot->startConversation(new PizzaConversation);

});

Creating Conversations

When starting a new conversation using the startConversation() method, you need to pass the method the conversation that you want to start gathering information with. Each conversation object needs to extend from the SlackBot Conversation object and must implement a simple run() method.

This is the very first method that gets executed, when the conversation starts.

Example conversation object:

class PizzaConversation extends Conversation
{
	protected $size;

	public function askSize()
	{
		$this->ask('What pizza size do you want?', function(Answer $answer) {
			
			// Save size for next question
			$this->size = $answer->getText();

			$this->say('Got it. Your pizza will be '.$answer->getText());
            
        });
	}

	public function run()
	{
		// This will be called immediately
		$this->askSize();
	}

}

Control Conversation Flow

$conversation->say()

Argument	Description
message	String or Question object

Call $conversation->say() several times in a row to queue messages inside the conversation. Only one message will be sent at a time, in the order they are queued.

$conversation->ask()

Argument	Description
message	String or Question object
callback or array of callbacks	callback function in the form function($answer), or array of arrays in the form [ 'pattern' => regular_expression, 'callback' => function($answer) { ... } ]

When passed a callback function, $conversation->ask will execute the callback function for any response. This allows the bot to respond to open ended questions, collect the responses, and handle them in whatever manner it needs to.

When passed an array, the bot will look first for a matching pattern, and execute only the callback whose pattern is matched. This allows the bot to present multiple choice options, or to proceed only when a valid response has been received. The patterns can have the same placeholders as the $bot->reply() method has. All matching parameters will be passed to the callback function.

Callback functions passed to ask() receive (at least) two parameters - the first is an Answer object containing the user's response to the question. If the conversation continues because of a matching pattern, all matching pattern parameters will be passed to the callback function too. The last parameter is always a reference to the conversation itself.

Using $conversation->ask with a callback:

	// ...inside the conversation object...
	public function askMood()
	{
		$this->ask('How are you?', function (Answer $response) {
			
			$this->say('Cool - you said ' . $response->getText());
			
		});
	}

Using $conversation->ask with an array of callbacks:

	// ...inside the conversation object...
	public function askNextStep()
	{
		$this->ask('Shall we proceed? Say YES or NO', [
			[
				'pattern' => 'yes|yep',
				'callback' => function () {
					$this->say('Okay - we\'ll keep going');
				}
			],
			[
				'pattern' => 'nah|no|nope',
				'callback' => function () {
					$this->say('PANIC!! Stop the engines NOW!');
				}
			]
		]);
	}

Using $conversation->ask with a Question object

Instead of passing a string to the ask() method, it is also possible to create a Question object. The Question objects make use of Slack's interactive messages to present the user buttons to interact with.

When passing question objects to the ask() method, the returned Answer object has a method called isInteractiveMessageReply to detect, if the user interacted with the message and clicked on a button.

Creating a simple Question object:

	// ...inside the conversation object...
	public function askForDatabase()
	{
    $question = Question::create('Do you need a database?')
      ->fallback('Unable to create a new database')
      ->callbackId('create_database')
      ->addButtons([
          Button::create('Of course')->value('yes'),
          Button::create('Hell no!')->value('no'),
    ]);

    $this->ask($question, function (Answer $answer) {
      // Detect if button was clicked:
      if ($answer->isInteractiveMessageReply()) {
        $selectedValue = $answer->getValue(); // will be either 'yes' or 'no'
        $selectedText = $answer->getText(); // will be either 'Of course' or 'Hell no!'
      }
    });

  }

Long running tasks

SlackBot uses the Slack Event API to get information from Slack. When Slack sends the information to your app, you have 3 seconds to return a HTTP 2xx status. Otherwise Slack will consider the event delivery attempt failed and Slack will attempt to deliver the message up to three more times.

This means that you should push long running tasks into an asynchronous queue.

Queue example using Laravel:

	// ...inside the conversation object...
  public function askDomainName()
  {
    $this->ask('What should be the domain name?', function (Answer $answer) {
      // Push long running task onto the queue.
      $this->reply('Okay, creating subdomain ' . $answer->getText());
      dispatch(new CreateSubdomain($this, $answer->getText()));
      
    });
  }

License

SlackBot is free software distributed under the terms of the MIT license.