Driver Slack Laravel Package

Getting Started

Install the driver with Composer:

composer require botman/driver-slack

This pulls in botman/botman if it is not already present. In Laravel, make sure the BotMan service provider/facade are registered (auto-discovery on modern Laravel, or manually in config/app.php). Publish the BotMan config and set your Slack token:

php artisan vendor:publish --provider="BotMan\BotMan\BotManServiceProvider" --tag=config

// config/botman/slack.php
return [
    'token' => env('SLACK_TOKEN'), // xoxb-... bot token
];

Create a Slack app, add a bot user, grant messaging/history scopes such as chat:write, channels:history, im:history, and configure the Event Subscriptions, Slash Commands, and Interactivity request URLs to your Laravel endpoint. Add a POST route that is CSRF-exempt (api.php or VerifyCsrfToken::$except):

Route::post('/botman/slack', [BotManController::class, 'handle']);

Minimal controller:

public function handle()
{
    $botman = app('botman');

    $botman->hears('hello', function ($bot) {
        $bot->reply('Hello from Slack!');
    });

    $botman->listen();
}

First use case: mention the bot in a channel or DM it hello, and confirm the reply appears. Look first at SlackDriver and SlackSlashCommandDriver in the package source to see exactly how event, slash-command, and interactive payloads are parsed and matched. Then use BotMan core docs for hears, ask, conversations, attachments, and middleware.

Implementation Patterns

Simple message routing. Register handlers in the controller before listen(). Use hears() for text/command matching and reply() for responses:

$botman->hears('deploy {env}', function ($bot, $env) {
    $bot->reply("Deploying to {$env}...");
});

Slash commands. Enable the Slack slash-command driver in your BotMan setup, then treat the command text as the message to match. Reply quickly:

$botman->hears('/status', function ($bot) {
    $bot->reply('All systems operational.');
});

Interactive buttons. Use BotMan’s Question/Button classes; the Slack driver maps the clicked action value back into a message payload:

use BotMan\BotMan\Messages\Outgoing\Actions\Button;
use BotMan\BotMan\Messages\Outgoing\Question;

$question = Question::create('Approve this request?')
    ->addButtons([
        Button::create('Approve')->value('approve'),
        Button::create('Reject')->value('reject'),
    ]);

$bot->reply($question);

$botman->hears('approve', function ($bot) {
    $bot->reply('Approved.');
});

Slack attachments. Use the driver’s Slack-specific attachment helper for colored attachments, fields, images, and footers. For anything beyond legacy attachments, call the Slack Web API directly.

Conversations. Use $bot->ask() or dedicated Conversation classes for multi-step flows such as onboarding or approvals. BotMan stores conversation state in cache, so use a shared cache driver if you run multiple app servers.

Proactive messages. From queued jobs or scheduled commands, send notifications with $bot->say('...', $channelId). This is useful for alerts, CI results, and approval reminders.

Middleware. Add middleware for request verification, logging raw Slack payloads, allowlisting teams/channels, and rate limiting. Keep Slack signature verification in middleware so every webhook is checked before BotMan handles it.

Multiple endpoints. You can point Slack’s event, slash-command, and interactivity URLs at one BotMan endpoint if the loaded drivers match correctly. If you need different middleware or queue behavior, use separate routes/controllers for each Slack surface.

Testing. Exercise handlers by posting representative Slack payloads to your endpoint or by constructing a BotMan instance with a stub/fake driver and asserting the replies. Keep payload fixtures for message events, slash commands, and button callbacks.

Gotchas and Tips

Slack’s 3-second rule. Slack expects a fast HTTP 200 for events/interactions and retries on timeout. BotMan handles requests synchronously, so long-running work causes duplicate deliveries and duplicate replies. Acknowledge quickly, queue heavy work, and reply later with $bot->say() or use Slack’s response_url.

Security is your responsibility. This driver’s last release was 2019, before Slack’s signing-secret scheme became standard. Verify X-Slack-Signature and X-Slack-Request-Timestamp in middleware; do not rely only on the deprecated verification token. Also validate the team/channel/user if the bot is installed in multiple workspaces.

Slack URL verification. Slack sends a url_verification challenge when you save an Event Subscriptions URL. Make sure your endpoint returns the challenge value; if the driver does not handle it automatically, add a small branch or middleware before BotMan.

Bot loops. Configure the bot ID where supported and ignore messages with bot_id or bot message subtypes. Otherwise the bot can respond to its own messages. Be careful with event subscriptions: this older driver may only parse message events, so app_mention events may need separate handling.

Slash-command limitations. Slash commands often need response_url for ephemeral responses or delayed replies. The driver may send normal chat messages instead. If you need ephemeral messages, message replacement, or multiple follow-ups, handle response_url yourself. Remember response_url expires and allows a limited number of responses.

Interactive components. Button clicks must also be acknowledged within 3 seconds. Updating the original message requires response_url or chat.update; the driver likely sends a new message rather than replacing the original. Modals, Home tabs, shortcuts, and view_submission payloads are not covered by this legacy driver.

Legacy attachments vs Block Kit. The package predates Slack Block Kit. It supports classic attachments, but Slack now recommends Block Kit for rich layouts. For modern UIs, keep BotMan for routing/conversations and call chat.postMessage with Block Kit via Guzzle or Slack’s SDK.

API drift. Slack has deprecated many channels.* methods in favor of conversations.*. Check the driver’s API calls if you rely on channel management. Threaded replies (thread_ts) may not be supported by the driver; use the Slack Web API directly for threads.

Configuration quirks. Use a bot token (xoxb-...) with the correct scopes, not a user token. If you change .env or config, clear Laravel’s config cache. Ensure the webhook route bypasses CSRF. If messages are silently ignored, log the raw Slack payload and inspect the driver’s matchesRequest() and getMessages() behavior.

Duplicates and retries. Slack includes retry headers on repeated deliveries. Make handlers idempotent or deduplicate using X-Slack-Retry-Num and event IDs to avoid double-processing.

Extension points. For unsupported Slack features, subclass the driver, add middleware, or bypass BotMan for that specific API call while keeping BotMan for message routing. This is usually cleaner than fighting the driver’s legacy payload assumptions.