README

Work with Slack Events API as easily as with native Laravel 7 events and event listeners.

🔗 Reasons to use this package for the Slack Events API:

Based on native Laravel Events
Supports all Slack Event types (including events for new Workspace Apps!)
Supports token validation
Supports URL verification and "challenge" requests
PSR compatible code
Full documentation
Almost full test coverage
Lots of emoji in the documentation (even cats! 🐈)

🌎 Installation

1) Require the package with Composer

composer require lisennk/laravel-slack-events-api

2) If you're using Laravel version 5.5 or higher, the SlackEventsServiceProvider will be automatically discovered. Get started fast!

3) If you're using a version of Laravel lower than 5.5, you'll still have to register the service provider manually. Open config/app.php and add \Lisennk\LaravelSlackEvents\SlackEventsServiceProvider::class to the providers[] array.

For example:

// ...

'providers' => [
// ...
// A whole bunch of providers
// ...

\Lisennk\LaravelSlackEvents\SlackEventsServiceProvider::class,
],

// ...

If you are using Laravel 5.3 or higher, you will find a comment in config/app.php with text like /* Package Service Providers... */, which can help you find the right place.

4) Publish the config file

php artisan vendor:publish

Choose the option for the Service Provider, or find slack-events in the Tag: list at the bottom.

Next we'll configure some settings to use the Slack API.

5) Create an App or Open an Existing One If you want to work with Slack's new Workspace Apps, read over the information in the Developer Preview for Workspace Apps, and create a new workspace token App to get started.

If you're not using a Workspace App, open the Slack Apps page and create a new user token App.

If you want to modify an existing app to use with Slack-Events, you can find both Workspace Token Apps and User Token Apps on the Your Apps page.

6) Once you've created or opened your app you should see the Basic Information page. Scroll down to the "App Credentials" section, and copy the Verification Token at the bottom.

Open .env and paste your Verification Token under the 'SLACK_EVENT_TOKEN' key:

SLACK_EVENT_TOKEN=your-token

7) Now open the "Event Subscriptions" page. Here you must enable events, add events you wish to listen for and set Request URL. Request URL is the 'route' key in your config/slackEvents.php file:

return [
    /*
    |-------------------------------------------------------------
    | Your validation token from "App Credentials"
    |-------------------------------------------------------------
    */
    'token' => env('SLACK_EVENT_TOKEN', 'your-validation-token-here'),

    /*
    |-------------------------------------------------------------
    | Events Request URL — path, where events will be served
    |-------------------------------------------------------------
    */
    'route' => '/api/slack/event/fire', // <===== THIS IS YOUR REQUEST URL
];

'route' works just like built-in Laravel routes, so if your site URL is https://example.com and your 'route' is /api/slack/event/fire, then your full Request URL is https://example.com/api/slack/event/fire. You can leave it as-is or set your own route instead of the default /api/slack/event/fire.

This package will do all verification and "challenge" work for you, so you only need to set your Request URL — by default it's:

https://[your-site-url]/api/slack/event/fire

🍴 Usage

Also see: Quick Example.

Thanks to this package, working with Slack Events is the same as working with Laravel Events. So if you haven't read the Laravel Events documentation or Slack Events API documentation yet, it's highly recommended to read them before you start.

This package provides a separate Laravel Event class for every Slack event that has Slack Events API support. For example, the reaction_added event implementation is the Lisennk\LaravelSlackEvents\Events\ReactionAdded class.

Also see: Full list of supported events and their classes.

Each Event class has public fields representing the real Slack Event request:

For example, if you want to get the reaction name from reaction_added event, you can get it from the ReactionAdded event class like this:

$reactionAdded->event['reaction']; // reaction name, something like :thumbsup:

So, suppose we want to make a reaction_added Slack Event listener. What do we need to do?

Example

1) Open the App/Listeners directory (or create it if it doesn't exist). Now create a new file and call it ReactionAddedListener.php. Paste in this code:

<?php

namespace App\Listeners;

use \Lisennk\LaravelSlackEvents\Events\ReactionAdded;
use Illuminate\Support\Facades\Log;
use Illuminate\Contracts\Queue\ShouldQueue;

class ReactionAddedListener implements ShouldQueue
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        // Here you can setup something
    }

    /**
     * Handle the event.
     *
     * @param  ReactionAdded  $event
     * @return void
     */
    public function handle(ReactionAdded $reactionAdded)
    {
        // Do some magic with event data
        Log::info('New reaction added, reaction name is: ' . $reactionAdded->event['reaction']);
    }
}

As you can see, it's a normal event listener. You might notice that the listener implements ShouldQueue — it's useful because our app must respond to the request within three seconds in order to adhere to the Slack Events API terms. If you want some long-running stuff in your event listener, you need to configure a queue.

2) Now we add this listener to /App/Providers/EventServiceProvider.php like any other event listener:

// ...

protected $listen = [
        
        // ...

        \Lisennk\LaravelSlackEvents\Events\ReactionAdded::class => [
            \App\Listeners\ReactionAddedListener::class
        ]
    ];
    
// ...

3) Profit! You are ready to go.

🍒 Full list of supported events and their classes

🌺 Contributing

Feel free to star this repository, create pull requests or issues, and report typos.

📚 Reference

Read the Slack Events API official documentation
Read the Laravel Events documentation
To make Slack Web API calls we recommend the Laravel Slack API package

lisennk / laravel-slack-events-api

Maintainers

Details