masterro / laravel-slack
Slack plugin
Requires
- fideloper/proxy: ^4.4
- guzzlehttp/guzzle: >=6.3
- illuminate/contracts: ^5.7|^6.0|^7.0|^8.0
- illuminate/support: ^5.7|^6.0|^7.0|^8.0
README
Description
This package is used for sending Slack messages and handling interactions with slack messages: clicking on messages buttons and interacting with users through dialogs.
Installition
Install the package via composer:
composer require pdffiller/laravel-slack
Install service provider:
// config/app.php 'providers' => [ ... Pdffiller\LaravelSlack\LaravelSlackServiceProvider::class, ];
Publish config and database migration file:
php artisan vendor:publish --provider="Pdffiller\LaravelSlack\LaravelSlackServiceProvider"
Run migrations:
php artisan migrate
This is the contents of the published laravel-slack-plugin.php
config file:
return [ /* * Bot User OAuth Access from Slack App */ 'bot-token' => env('SLACK_BOT_TOKEN', null), /* * Verification token from Slack App */ 'verification_token' => env('SLACK_VERIFICATION_TOKEN', null), /* * Handlers are processed by controller */ 'handlers' => [ ], /* * Endpoint URL */ 'endpoint-url' => 'slack/handle' ];
Usage
Sending messages
Plugin supports this methods from slack api:
You can inject service Pdffiller\LaravelSlack\Services\LaravelSlackPlugin
into your method.
Service has 2 methods:
buildMessage((AbstractMethodInfo $method), [Model $model], [string $options])
sendMessage([$message])
Instances of these classes can be used as a $method
parameter:
Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage
Pdffiller\LaravelSlack\AvailableMethods\ChatUpdate
Pdffiller\LaravelSlack\AvailableMethods\DialogOpen
Pdffiller\LaravelSlack\AvailableMethods\FilesUpload
Eloquent models can be used as a not obligatory $body
parameter.
All sent slack messages via chat.postMessage
method are saved in the database in the laravel_slack_message
table.
Slack message ts
and channel
are saved for every message.
If eloquent model is sent as the $body
parameter to the buildMessage
method, model's primary key and model's path are also saved.
If json options are sent as a $options parameter to the buildMessage
method, it will be also saved in the db.
You can then use ts
and channel
parameters in chat.update
method in order to update existing slack message.
Sending plain text message
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); $slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage()) ->setChannel("#ABCDEF") //channel id from web app ->setText("asdsadsad"); $slack->sendMessage();
Update slack message
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatUpdate()) ->setChannel("#ABCDEF") ->setTs('1405894322.002768') ->setText("updated text"); $slack->sendMessage();
Building messages with attachments
For building messages with attachments plugin has this classes:
Pdffiller\LaravelSlack\RequestBody\Json\Attachment
Pdffiller\LaravelSlack\RequestBody\Json\AttachmentField
Pdffiller\LaravelSlack\RequestBody\Json\AttachmentAction
Sending message with text attachment
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); $slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage()) ->setChannel("#ABCDEF") ->addAttachment(\Pdffiller\LaravelSlack\RequestBody\Json\Attachment::create() ->setText("this is text") ->setColor('#36a64f')); // default color is #D3D3D3 $slack->sendMessage();
Sending message with attachment including fields
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); $slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage()) ->setChannel("#ABCDEF") ->addAttachment(\Pdffiller\LaravelSlack\RequestBody\Json\Attachment::create() ->addFields([ [ 'title' => 'User Id', 'value' => 10 /*, 'short'=true/false*/ // short is true by default, it means that next field is shown on the same line ], \Pdffiller\LaravelSlack\RequestBody\Json\AttachmentField::create('Team Id', 10), ] )); $slack->sendMessage();
Sending message with attachment including actions
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); $slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\ChatPostMessage()) ->setChannel("#ABCDEF") ->addAttachment(\Pdffiller\LaravelSlack\RequestBody\Json\Attachment::create() ->setCallbackId('callback-id-is-used-in-handler') ->setFallback('Fallback text') // Required plain-text summary of the attachment ->setColor('#36a64f') ->addActions([ [ 'name' => 'button-name', 'text' => 'Accept', 'value' => 1, /*'style' => 'primary/danger', 'type' => 'button'*/ ], \Pdffiller\LaravelSlack\RequestBody\Json\AttachmentAction::create('button-name', 'Decline', 0) ] )); $slack->sendMessage();
Sending message with file
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); $slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\FilesUpload()) ->setChannel("#ABCDEF") ->setFilePath("/uploads/one.txt") //path to file in your project or web ->setFileName("one.txt); $slack->sendMessage();
Open dialogs after messages interaction
Dialog can be opened after interaction with message, for example clicking on a button. After interaction with message, trigger_id
is sent in the request payload. This parameter is used in the dialog.open
method.
For building dialog plugin has this classes:
Pdffiller\LaravelSlack\RequestBody\Json\Dialog
Pdffiller\LaravelSlack\RequestBody\Json\DialogElement
$slack = resolve(\Pdffiller\LaravelSlack\Services\LaravelSlackPlugin::class); $slack->buildMessage(new \Pdffiller\LaravelSlack\AvailableMethods\DialogOpen()) ->setTriggerId('trigger_id') ->setDialog(\Pdffiller\LaravelSlack\RequestBody\Json\Dialog::create() ->setCallbackId('will-be-used-in-handler') ->setTitle('Title') ->setSubmitLabel('Save') //->setState(json_encode([])) // you can save some data between opening dialog and handling it's interaction in the state parameter ->addElement(\Pdffiller\LaravelSlack\RequestBody\Json\DialogElement::create() ->setName('reason') ->setLabel('...') ->setType(DialogElement::TEXTAREA_TYPE)) ); $slack->sendMessage();
Handling Interactive Components
Plugin supports handling interacrtions with buttons and dialogs. All requests from slack are sent to the plugin's endpoint. It's url can be changed in the generated laravel-slack-plugin.php
config in the endpoint-url
section. This URL should be added to the Interactive Components
section in your Slack app. OAuth Access Token and Verification token from Slack App should be added to your config file.
Plugin has convenient system of handlers for processing all interactions.
Both Attachment and Dialog have callback_id
parameter. After every interaction with button or dialog slack sends request to the /slack/handle
endpoint. callback_id
parameter is included in the request payload, so all requests can be distinguished by this parameter.
So, one handler should be implemented for the requests of one callback_id
type.
Plugin has Pdffiller\LaravelSlack\Handlers\BaseHandler
class which has this methods:
shouldBeHandled()
handle()
In your project you should implement your own handlers on top of plugin's BaseHandler
class.
Handler example
use Pdffiller\LaravelSlack\Handlers\BaseHandler; class CustomHandler extends BaseHandler { // check if this handler should be executed public function shouldBeHandled() { $payload = json_decode($this->request->get('payload'), true); $callBackId = Arr::get($payload, 'callback_id'); return $callBackId === 'some-callback-id'; } public function handle() { $payload = json_decode($this->request->get('payload'), true); // ... } }
Handler should be added to the handlers
section in the generated laravel-slack-plugin.php
config file in your project.
'handlers' => [ \App\Slack\Handlers\CustomHandler::class, ... ]