Download the PHP package nwilging/laravel-slack-bot without Composer

Laravel Slack Bot

A robust Slack messaging integration for Laravel

About

While Slack Incoming Webhooks are powerful, direct API interaction is powerful-er - or something like that.

This package leverages Slack bot tokens to interact with the Slack API. This allows the integration to do things such as search channels and post messages - both plain and rich text - to any channel* in a workspace.

* any public channel, or private channel that the Slack App bot is a member of

Installation

Pre Requisites

1. Laravel v8+
2. PHP 7.4+

Install with Composer

Usage with laravel/slack-notification-channel

If your app uses the default first-party Laravel package, laravel/slack-notification-channel, this package will conflict with the first-party one. This package is configured by default to use the channel slack in your via() method.

If you wish to use this package alongside laravel/slack-notification-channel, simply add the following to your .env:

You may replace slackBot with any driver name you'd like. The driver will be instantiated with that name and you can provide it to your via() method. This will allow you to use both this package and laravel/slack-notification-channel at the same time.

Example:

Configure

Use this guide to create your Slack App. Most integrations will use the following scopes. You may add additional OAuth scopes if needed.

• channels:read
• chat:write
• chat:write.customize
• groups:read
• groups:write
• im:read
• mpim:read

To configure your .env, simply add the following variable:

Basic Usage

Message Examples

The SlackApiNotificationContract

Your notification must implement the interface Nwilging\LaravelSlackBot\Contracts\Notifications\SlackApiNotificationContract.

Basic Usage

This package can be used automatically with Laravel notifications. Add slack to the via() array of your notification and a toSlack() method that returns an array:

The channelId here is the ID or name of the channel you wish to send to.

Read more on Usage for information on the SlackApiService which can provide you channel data (including ID) by a channel name.

Using alongside laravel/slack-notification-channel

Advanced Usage

This package also provides a SlackApiService and a handful of supporting classes such as layout builders, layout blocks, elements, and composition objects. The most common usage outside of sending plain text messages would be to send rich text messages using the layout builders and related components. You can also go further to make use of the SlackApiService.

Slack API Service

Contract: Nwilging\LaravelSlackBot\Contracts\SlackApiServiceContract

Methods:

• listConversations - Returns a paginated list of channels and groups
  • int $limit = 100 - Page limit (default 100)
  • ?string $cursor = null - Page cursor, used to fetch a new page
  • bool $excludeArchived = false - Flag to exclude archived channels and groups
  • ?string $teamId = null - The team ID to list conversations for (required if token belongs to an org-wide app)
  • bool $includePrivate = true - Flag to include private channels and groups (will only show channels the app is a member of)
• getChannelByName - Retrieves channel data using a given name
  • string $name - The name of the channel to retrieve
• sendTextMessage - Send a plain text message
  • string $channelId - The ID of the channel to send to
  • string $message - The message text to send (may include markdown)
  • array $options = [] - Message options
• sendBlocksMessage - Send a message using layout blocks
  • string $channelId - The ID of the channel to send to
  • array $blocks - Array of Blocks
  • array $options = [] - Message options

Message Options

Message options should be passed as an array with the following schema:

These options are essentially the optional arguments from chat.postMessage.

There is a SlackOptionsBuilder support class that makes building this array more expressive:

Layout Blocks

The layout blocks implementation generally follows Slack's layout blocks design.

Layout Builder

There is a layout Builder located at Nwilging\LaravelSlackBot\Support\LayoutBuilder\Builder, implementing contract Nwilging\LaravelSlackBot\Contracts\Support\LayoutBuilder\BuilderContract.

The builder aims to provide expressive methods to build basic, yet robust, messages. This is a useful tool for building your notification in its toSlack() method.

Handling Slash Commands

Slack Slash Commands can be handled via this package and command handlers that are configured in your application.

The Nwilging\LaravelSlackBot\Services\SlackCommandHandlerService has a handle method which accepts a Request object. This service will validate the incoming message using the request headers and your supplied signing secret, and will then attempt to handle the command request with a registered command handler.

Creating Command Handlers

Command handlers should implement the interface Nwilging\LaravelSlackBot\Contracts\SlackCommandHandlerContract. An example handler:

Registering Command Handlers

Command handlers should be registered in a service provider so that they are available once the application boots. You may do this in any service provider that is already registered in your application. Place the command handler registrations inside the register method of your service provider.