Slack Web API Channel

Purpose and Scope

This document details the SlackWebApiChannel class, which delivers notifications to Slack using the official chat.postMessage API. This channel requires a Bot User OAuth Token for authentication and posts messages to specific Slack channels or users.

For information about routing between Web API and Webhook delivery methods, see Slack Routing. For webhook-based delivery, see Slack Webhook Channel. For constructing Slack message content, see Slack Messages.

Sources: src/Channels/SlackWebApiChannel.php1-98

Channel Overview

The SlackWebApiChannel is responsible for delivering notifications through Slack's REST API. Unlike the webhook-based channel which posts to a static URL, the Web API channel uses OAuth tokens and can dynamically target different channels, users, or conversations.

Property	Value
Class	Hypervel\Notifications\Channels\SlackWebApiChannel
API Endpoint	https://slack.com/api/chat.postMessage
Authentication	Bearer Token (Bot User OAuth Token)
Importance Score	0.66
Dependencies	GuzzleHttp\Client, Hyperf\Contract\ConfigInterface

Sources: src/Channels/SlackWebApiChannel.php16-27

System Integration

Diagram: Slack Web API Channel Data Flow

This diagram shows how the SlackWebApiChannel integrates with the broader notification system. The channel receives control from SlackNotificationRouterChannel, invokes the notification's toSlack() method to build a message, resolves routing information from the notifiable entity, constructs a JSON payload, and delivers it via HTTP client to Slack's API.

Sources: src/Channels/SlackWebApiChannel.php32-66

Authentication Mechanism

The SlackWebApiChannel uses OAuth Bearer Token authentication, as required by Slack's Web API. The token is a Bot User OAuth Token that must have chat:write permissions.

Token Resolution

The channel resolves the OAuth token through a cascading lookup:

Diagram: OAuth Token Resolution Flow

The token resolution logic is implemented in determineRoute() src/Channels/SlackWebApiChannel.php83-96:

1. Call routeNotificationFor('slack', $notification) on the notifiable entity
2. If the route is a string, treat it as a channel name and use the default token
3. If the route is a SlackRoute object, extract its token property or fall back to the default
4. The default token is always services.slack.notifications.bot_user_oauth_token from configuration

Sources: src/Channels/SlackWebApiChannel.php83-96

Token Validation

Before sending the request, the channel validates that a token is present src/Channels/SlackWebApiChannel.php49-51:

If no token can be resolved, a LogicException is thrown, preventing the HTTP request from being made.

Sources: src/Channels/SlackWebApiChannel.php49-51

Routing Configuration

The channel supports flexible routing through the notifiable entity's routeNotificationFor() method. This method determines both the target channel and the authentication token.

Channel Resolution

The target Slack channel (or user ID) is resolved with the following precedence:

Priority	Source	Description
1	SlackRoute->channel	Channel specified in route object
2	SlackMessage->channel	Channel set on message via to()
3	services.slack.notifications.channel	Default channel from configuration

The channel resolution logic is implemented in buildJsonPayload() src/Channels/SlackWebApiChannel.php71-78:

Routing Examples

Simple String Route (Channel Name Only):

SlackRoute Object (Custom Token):

Sources: src/Channels/SlackWebApiChannel.php71-96

Message Delivery Process

The complete delivery process is orchestrated by the send() method src/Channels/SlackWebApiChannel.php32-66

Diagram: Message Delivery Sequence

Sources: src/Channels/SlackWebApiChannel.php32-66

Validation Steps

The channel performs several validation checks before sending:

1. Method Existence src/Channels/SlackWebApiChannel.php34-36: Verifies the notification implements toSlack()
2. Channel Validation src/Channels/SlackWebApiChannel.php45-47: Ensures a target channel is configured
3. Token Validation src/Channels/SlackWebApiChannel.php49-51: Ensures an OAuth token is available

Payload Construction

The JSON payload sent to Slack's chat.postMessage endpoint is constructed in two stages:

Stage 1: Message Serialization

The SlackMessage object is converted to an array via toArray() src/Channels/SlackWebApiChannel.php73 This array contains:

• text: Fallback text for notifications
• blocks: Block Kit layout blocks (see Slack Block Kit)
• attachments: Legacy attachments (see Legacy Slack Attachments)
• username: Bot display name
• icon_emoji or icon_url: Bot avatar
• unfurl_links, unfurl_media: URL preview settings
• thread_ts: Thread identifier for replies
• Additional Slack API parameters

Stage 2: Channel Injection

The buildJsonPayload() method merges the channel into the payload src/Channels/SlackWebApiChannel.php71-78:

The channel value follows the precedence order described in the Routing Configuration section.

Sources: src/Channels/SlackWebApiChannel.php71-78

HTTP Request Details

The channel makes a POST request to https://slack.com/api/chat.postMessage src/Channels/SlackWebApiChannel.php18 with the following structure:

Component	Value
Method	POST
URL	SlackWebApiChannel::SLACK_API_URL
Body	JSON-encoded payload
Headers	Authorization: Bearer {token}

The HTTP client is configured via src/Channels/SlackWebApiChannel.php53-58:

Sources: src/Channels/SlackWebApiChannel.php18-58

Error Handling

The SlackWebApiChannel implements comprehensive error handling for both HTTP and Slack API errors.

HTTP-Level Errors

HTTP errors (4xx, 5xx status codes) are handled by GuzzleHttp and will throw exceptions automatically.

Slack API Errors

Even when the HTTP status is 200, Slack may return an error in the JSON response. The channel checks for this src/Channels/SlackWebApiChannel.php60-63:

Common Slack API errors include:

Error Code	Meaning
channel_not_found	The specified channel does not exist
not_in_channel	The bot is not a member of the channel
invalid_auth	Invalid authentication token
account_inactive	The token's associated account is inactive
missing_scope	Token lacks required permissions (e.g., chat:write)

Sources: src/Channels/SlackWebApiChannel.php60-63

Exception Types

Diagram: Exception Flow in send() Method

Sources: src/Channels/SlackWebApiChannel.php34-63

Configuration

The channel reads configuration from the services.slack.notifications namespace:

Configuration Key	Type	Description
services.slack.notifications.bot_user_oauth_token	string	Default Bot User OAuth Token
services.slack.notifications.channel	string	Default target channel (e.g., #general)

Example configuration:

Sources: src/Channels/SlackWebApiChannel.php76-94

Constructor Dependencies

The SlackWebApiChannel is instantiated by the dependency injection container with two dependencies src/Channels/SlackWebApiChannel.php23-27:

Dependency	Type	Purpose
$client	GuzzleHttp\Client	HTTP client for making API requests
$config	Hyperf\Contract\ConfigInterface	Configuration repository for reading settings

These dependencies are injected automatically when the channel is resolved from the container.

Sources: src/Channels/SlackWebApiChannel.php23-27