It introduces a whole new way of interacting with Slack, meaning this is a breaking change. However, it is worth it.
Put simple, this PR "upgrades" the Slack Notification Channel package from simple Webhook-based calls, to WebAPI based calls. This opens up a whole range of new options:
It allows for using BlockKit, Slack's rich message builder.
It allows for interactivity. For example, you could add a Button to your message that when clicked, shows a confirmation dialog, and when that's confirmed, triggers Slack into calling a webhook you've configured in your Slack App.
While this WebAPI works based on OAuth tokens, the tokens themselves by default do not have a refresh token, and therefore do not expire either. This essentially makes it technically work the same as a webhook, with the only distinction being that instead of an Unique URL being used, an Authentication Bearer token is used.
I did not create a default config/publisher for this, as I don't want to override what the user already has. Not sure what the best approach would be, but (obviously) feel free to adjust how this works if you have a better idea :)
Usage
Write your notification:
<?php
namespace App\Notifications;
use Illuminate\Notifications\Notification;
use Illuminate\Notifications\Slack\BlockKit\Blocks\ActionsBlock;
use Illuminate\Notifications\Slack\BlockKit\Blocks\ContextBlock;
use Illuminate\Notifications\Slack\BlockKit\Composites\ConfirmObject;
use Illuminate\Notifications\Slack\SlackMessage;
use Illuminate\Support\Facades\App;
class BlockKitBasedNotification extends Notification
{
/**
* Get the notification channels.
*
* @param mixed $notifiable
* @return array|string
*/
public function via($notifiable)
{
return ['slack'];
}
/**
* Get the Notification as a Slack message.
*/
public function toSlack(object $notifiable): SlackMessage
{
return (new SlackMessage())
->username('LaraSlackNotifier')
->to('#general')
->text('This is the fallback notification message')
->headerBlock('But first, this message from our sponsor')
->actionsBlock(function (ActionsBlock $block) {
$block->button('Click me!')
->url('https://laravel.com')
->danger()
->confirm('This action can only be undone by gnomes.', function (ConfirmObject $dialog) {
$dialog->confirm('You gnome it!');
$dialog->deny('Oh no, gnomes!');
});
})
->contextBlock(function (ContextBlock $block) {
$block->image('https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Laravel.svg/1280px-Laravel.svg.png')->alt('The Laravel Logo');
$block->text('Laravel v' . App::version());
})
->dividerBlock()
->imageBlock('https://laravel.com/img/og-image.jpg', 'Laravel Homepage Image');
}
}
Here's what this Notification will generate:
Then, there's a couple of ways to route the notification when using direct routes:
Using the config settings (or what's defined in the notification itself). This requires the OAuth token to be set in the config:
use Illuminate\Notifications\Slack\SlackRoute;
Notification::route('slack', SlackRoute::make('channel', 'token'))->notify(new BlockKitBasedNotification());
In the SlackRoute object example, either value is optional/nullable, but this effectively allows you to customize both the OAuth Token, as well as the channel.
Extras
If you quickly want to see what blocks you've been building, you can chain the dd() call on the end of the SlackNotification. This will generate and dump an URL to the BlockKitBuilder, which then previews the payload + the notification itself in your browser. For example, here's the URL to the notification above
If you instead just want the original dd() method and dump the whole payload, you can pass true to the dd() call.
Notes
This doesn't implement all the blocks/elements, just the ones that are useful for regular send-and-forget type notifications. They could be extended (e.g. you could add text fields or dropdown menus) to write complete Laravel-based Slack bots.
This replaces the Webhook's "Attachments".
This drops support for EOL Laravel apps (<= Laravel 8) and associated PHP versions (<= 7.x)
WARNING: THIS PR IS BREAKING.
It introduces a whole new way of interacting with Slack, meaning this is a breaking change. However, it is worth it.
Put simple, this PR "upgrades" the Slack Notification Channel package from simple Webhook-based calls, to WebAPI based calls. This opens up a whole range of new options:
While this WebAPI works based on OAuth tokens, the tokens themselves by default do not have a refresh token, and therefore do not expire either. This essentially makes it technically work the same as a webhook, with the only distinction being that instead of an Unique URL being used, an Authentication Bearer token is used.
Installation
First, you'll want to create a new Slack app (or use an existing one): https://api.slack.com/apps?new_app=1 Example: https://user-images.githubusercontent.com/1752195/228922553-5301bcfd-4b3d-4407-8ad2-aa28bf82c662.png
Next, click on Permissions, and scroll down to "Scopes". There, add the following scopes: Example: ![CleanShot 2023-03-30 at 19 54 40]()
Finally, scroll back up and click "Install to Workspace": Example: https://user-images.githubusercontent.com/1752195/228922887-7091b1c5-24de-4667-815e-4c8036137b02.png
After approving the app to your Slack Workspace, you'll see a "Bot User OAuth Token". Example: https://user-images.githubusercontent.com/1752195/228923168-cc8b2f9c-a67a-4771-87f3-6bfa448ca688.png
Add this value, and optionally a fallback channel, to your
services.php
config file:I did not create a default config/publisher for this, as I don't want to override what the user already has. Not sure what the best approach would be, but (obviously) feel free to adjust how this works if you have a better idea :)
Usage
Write your notification:
Here's what this Notification will generate:
Then, there's a couple of ways to route the notification when using direct routes:
Using the config settings (or what's defined in the notification itself). This requires the OAuth token to be set in the config:
Using the OAuth token from the config, and a string-based channel. This overrides the channel defined in the notification:
Using A
SlackRoute
object:In the
SlackRoute
object example, either value is optional/nullable, but this effectively allows you to customize both the OAuth Token, as well as the channel.Extras
If you quickly want to see what blocks you've been building, you can chain the
dd()
call on the end of the SlackNotification. This will generate and dump an URL to the BlockKitBuilder, which then previews the payload + the notification itself in your browser. For example, here's the URL to the notification aboveIf you instead just want the original
dd()
method and dump the whole payload, you can passtrue
to thedd()
call.Notes