​

Slack Channel

​

Overview

• Channel Name: slack
• Transport: Socket Mode (WebSocket) or REST API polling
• Authentication: Bot token (xoxb-) + optional App token (xapp-)
• Public Port Required: No
• Supports: Text messages, threads, channel discovery, display names

​

Configuration

​

Required Settings

[channels_config.slack]
bot_token = "xoxb-YOUR-BOT-TOKEN"
allowed_users = ["*"]  # User IDs

​

Complete Configuration

[channels_config.slack]
bot_token = "xoxb-YOUR-BOT-TOKEN"
app_token = "xapp-YOUR-APP-TOKEN"  # Optional: enables Socket Mode
channel_id = "C1234567890"  # Optional: single channel or "*" for all
allowed_users = ["U123456789"]  # Slack user IDs

[channels_config.slack.group_reply]
mode = "all_messages"  # all_messages | mention_only
allowed_sender_ids = []  # IDs that bypass mention gate

​

Environment Variables

ZEROCLAW_SLACK_BOT_TOKEN=xoxb-your-token
ZEROCLAW_SLACK_APP_TOKEN=xapp-your-token

​

Authentication

​

Creating a Slack App

1. Go to Slack API
2. Click “Create New App” → “From scratch”
3. Name your app and select workspace
4. Navigate to “OAuth & Permissions”
5. Add Bot Token Scopes:
   • channels:history
   • channels:read
   • chat:write
   • groups:history
   • groups:read
   • im:history
   • im:read
   • im:write
   • mpim:history
   • mpim:read
   • users:read (for display names)
6. Install app to workspace
7. Copy “Bot User OAuth Token” (starts with xoxb-)

​

Socket Mode Setup (Recommended)

1. In your Slack app, go to “Socket Mode”
2. Enable Socket Mode
3. Generate App-Level Token:
   • Name: “ZeroClaw Socket”
   • Scopes: connections:write
4. Copy token (starts with xapp-)
5. Add to config:

app_token = "xapp-YOUR-APP-TOKEN"

6. Subscribe to Bot Events:
   • message.channels
   • message.groups
   • message.im
   • message.mpim

​

User Authorization

allowed_users = [
    "U123ABC456",  # Specific user
    "*"            # All users (testing only)
]

1. Click user’s profile in Slack
2. Click ”⋯ More” → “Copy member ID”

curl -H "Authorization: Bearer xoxb-..." \
  https://slack.com/api/users.list

​

Features

​

Transport Modes

​

Socket Mode (WebSocket)

app_token = "xapp-1-..."

• Real-time message delivery
• No polling overhead
• Instant acknowledgments
• Lower latency

1. Opens WebSocket connection via apps.connections.open
2. Receives events in real-time
3. Sends acknowledgment for each envelope
4. Auto-reconnects on disconnect
5. Handles ping/pong for keepalive

​

Polling Mode

• Polls conversations.history every 3 seconds
• Tracks last seen timestamp per channel
• Discovers new channels every 60 seconds (when channel_id not set)
• Rate limit aware with exponential backoff

​

Channel Scope

​

Single Channel

channel_id = "C1234567890"

​

Multiple Channels

channel_ids = ["C123", "C456", "D789"]

​

All Accessible Channels

# Omit channel_id or set to "*"

• Public channels (bot is member)
• Private channels (bot is invited)
• DMs
• Multi-person DMs

​

Display Name Resolution

U123ABC456 → "Alice Johnson"

1. profile.display_name
2. profile.display_name_normalized
3. profile.real_name_normalized
4. profile.real_name
5. user.real_name
6. user.name
7. Falls back to user ID if all fail

• Cached for 6 hours
• Reduces API calls
• Automatic expiration

​

Thread Support

• thread_ts extracted from messages
• Top-level messages use ts as thread identifier
• Replies include thread_ts from original message

# Automatically sent to correct thread

​

Group Chat Control

​

Mention-Only Mode

[channels_config.slack.group_reply]
mode = "mention_only"

• Explicitly mentioned: <@BOT_USER_ID> hello
• In DMs
• Sender is in allowed_sender_ids

​

VIP Senders

[channels_config.slack.group_reply]
mode = "mention_only"
allowed_sender_ids = ["U123ABC456"]

​

Rate Limit Handling

• HTTP 429 status
• error: "rate_limited" in response

1. Parse Retry-After header (seconds or decimal)
2. Exponential backoff: retry_after * 2^attempt
3. Cap at 120 seconds
4. Add jitter (0-500ms) derived from system time
5. Max 3 retries before giving up

Slack conversations.history rate limited for channel C123.
Retry-After: 30s. Attempt 1/3. Next retry at 2024-01-15T10:30:00Z.

​

Implementation Details

​

Source Location

​

Key Components

​

SlackChannel Struct

pub struct SlackChannel {
    bot_token: String,
    app_token: Option<String>,
    channel_id: Option<String>,
    channel_ids: Vec<String>,
    allowed_users: Vec<String>,
    mention_only: bool,
    group_reply_allowed_sender_ids: Vec<String>,
    user_display_name_cache: Mutex<HashMap<String, CachedSlackDisplayName>>,
}

​

Socket Mode Flow

1. Call apps.connections.open → get WebSocket URL
2. Connect to WebSocket
3. For each envelope:
   • Parse envelope_id and type
   • Handle event (if type = "events_api")
   • Send acknowledgment: {"envelope_id": "..."}
4. Handle disconnect type → reconnect
5. On error or close → wait 3s and restart

​

Polling Mode Flow

1. Get bot user ID via auth.test
2. List accessible channels via conversations.list (if wildcard)
3. For each channel:
   • Track cursor timestamp (bootstrap to current time)
   • Fetch conversations.history with oldest=cursor
   • Process messages (newest-first, reverse to oldest-first)
   • Update cursor to newest message ts
   • Skip subtypes (system messages)
4. Sleep 3 seconds
5. Repeat

​

API Endpoints Used

​

Channel ID Prefixes

• C... - Public channel
• G... - Private channel (group)
• D... - Direct message

​

Message Deduplication

• Tracks last_ts per channel
• Skips messages with ts <= last_ts
• Bootstrap cursor to current time on first poll

• Tracks last_ts per channel
• Skips messages with ts <= last_ts
• Persistent across WebSocket reconnects

​

Error Handling

​

Common Errors

Slack: auth.test failed: invalid_auth

Slack: conversations.list failed: missing_scope

Slack: apps.connections.open failed: feature_not_enabled

Slack conversations.history rate limited for channel C123.
Retry-After: 60s. Attempt 2/3.

Slack: conversations.history failed: channel_not_found

​

Error Sanitization

crate::providers::sanitize_api_error(&error)

• Authorization headers
• Token values
• Internal details

​

Runtime Commands

• /new - Start new conversation
• /model - Show/switch current model
• /models - Show/switch provider

​

Best Practices

1. Use Socket Mode: Better performance and lower latency
2. Scope Channels: Use channel_id if possible
3. User IDs: More stable than usernames
4. Allowlist: Start specific, expand as needed
5. Display Names: Cached automatically for 6 hours
6. Mention Mode: Use in public channels to reduce noise

​

Troubleshooting

​

Bot Doesn’t Respond

# Get user ID from Slack profile or API
curl -H "Authorization: Bearer xoxb-..." \
  https://slack.com/api/users.list | jq '.members[] | select(.name=="alice") | .id'

allowed_users = ["U123ABC456"]

RUST_LOG=info zeroclaw daemon 2>&1 | grep Slack

• Slack channel listening on #channel-name
• Slack: ignoring message from unauthorized user:
• Slack poll error:

• Invite bot to channel: /invite @YourBot
• Verify bot appears in channel members

​

Socket Mode Not Working

app_token = "xapp-1-..."

• message.channels
• message.groups
• message.im
• message.mpim

​

Polling Mode Too Slow

​

Display Names Not Resolving

​

Performance

​

Message Throughput

• Real-time delivery (<100ms)
• No polling overhead

• 3-second poll interval
• Per-channel sequential processing

​

Optimization Tips

1. Socket Mode: Use when available
2. Channel Scope: Reduce with channel_id
3. Display Name Cache: 6-hour TTL reduces API calls
4. Rate Limit Backoff: Automatic, no tuning needed

​

Security

​

Token Protection

• Bot tokens: Never logged
• App tokens: Never logged
• Sanitized from error messages

​

User Verification

• Allowlist checked before processing
• Bot self-messages always ignored
• Channel scope enforced

​

Channel Filtering

​

See Also

• Channels Reference
• Slack API Documentation
• Socket Mode Guide
• Tool Approval