Slack Module

Purpose

This module allows you to send direct message notifications to Slack users.
It relies on the Laravel package slack-notification-channel package to send messages and makes use of the Slack API to retrieve the user's Slack ID from their email address.

Usage

Configuration

  1. Setup a new Slack app to connect to your Slack workspace, following the guide at https://api.slack.com/authentication/basics.

  2. Add the following environment variables to your .env file:

# SLACK_API_KEY Must match app's bot token for the slack app,
SLACK_API_KEY=
# Optional - default channel to send messages to if no channel is provided in the notification.
SLACK_NOTIFICATIONS_DEFAULT_CHANNEL=

Sending a direct message to a user.

Send your notification by instantiating DirectSlackMessageNotification with the required message information.

$user->notify(new DirectSlackMessageNotification(
    'Hello, this is a test message',
    'Some context for end users',
    'Optional header block text for the message',
));

The message will be sent to your user's Slack account using the slack_id field saved against the user model. If missing, the Slack ID will be retrieved from the Slack API using the user's email address.

Optional You can change the default notification content and format by creating a custom notification class that extends the DirectSlackMessageNotification class.

  • Set $defaultHeaderBlockText property for the top part of the Slack message sent if standard.
  • Alter the toSlack method to change the message format. Ensure to finish your message with ->to($this->retrieveSlackUserId($notifiable->email)); to send a direct message to a user.

Sending a message to a slack channel.

Send your notification by instantiating SlackChannelNotification with the required message information.

$user->notify(new SlackChannelNotification(
    'Hello, this is a test message',
    'Some context for end users',
    '#optional-channel-name',
));

If you ommit the channel name, the message will be sent to the configured channel in your services config.

Optional You can change the default notification content and format by creating a custom notification class that extends the SlackChannelNotification class.

  • Alter the toSlack method to change the message format. Ensure to add support for channel name override:
    $slackMessage = ... // Define your message here.
   
    if ($this->slackChannel) {
        return $slackMessage->to($this->slackChannel);
    }

Under the hood

The Laravel slack notification channel package can only send messages to known slack user ids or channel names.

To send a message to a user, you need to know their Slack ID. This module provides a way to retrieve the Slack ID from the Slack API using their user's email address.

The Slack API is called using the SlackConnector class that extends the standard BaseApiConnector class.
Thus testing and mocking follow the same pattern as other District API connectors.

The connector has been built using a custom SDK defined under SlackWebApiSdk. This SDK is minimal and may be extended in the future to support more Slack API endpoints. Consider generating SDK classes for the Slack API using https://docs.saloon.dev/installable-plugins/sdk-generator