Slack Channel Integration

The Slack channel enables Weaver to interact in Slack workspaces using Socket Mode, supporting direct messages, channel mentions, slash commands, and file uploads.

Prerequisites

A Slack workspace where you have permission to install apps
Admin access to create Slack apps

Creating a Slack App

Create New App
- Go to https://api.slack.com/apps
- Click “Create New App”
- Choose “From scratch”
- Name your app (e.g., “Weaver Bot”)
- Select your workspace
Enable Socket Mode
- Navigate to “Socket Mode” in the left sidebar
- Toggle “Enable Socket Mode” to ON
- Generate an app-level token:
  - Name: weaver-socket
  - Scope: connections:write
- Save the token (starts with xapp-)
Configure OAuth & Permissions
- Go to “OAuth & Permissions”
- Under “Bot Token Scopes”, add:
  - app_mentions:read - See mentions
  - channels:history - View messages in public channels
  - channels:read - View basic channel info
  - chat:write - Send messages
  - files:read - Access file information
  - im:history - View messages in DMs
  - im:read - View basic DM info
  - im:write - Send DMs
  - reactions:write - Add emoji reactions
  - users:read - View user info
Install App to Workspace
- Scroll up and click “Install to Workspace”
- Review permissions and click “Allow”
- Save the Bot User OAuth Token (starts with xoxb-)
Enable Event Subscriptions
- Go to “Event Subscriptions”
- Toggle “Enable Events” to ON
- Under “Subscribe to bot events”, add:
  - app_mention - Bot was mentioned
  - message.im - Direct messages to bot
- Save Changes
Optional: Create Slash Commands
- Go to “Slash Commands”
- Click “Create New Command”
- Command: /weaver
- Description: “Interact with Weaver”
- Usage Hint: [your message]

Configuration

Add the Slack channel to your config.yaml:

channels:
  slack:
    enabled: true
    bot_token: "xoxb-YOUR-BOT-TOKEN"
    app_token: "xapp-YOUR-APP-TOKEN"
    allow_from:
      - "U01234ABCDE"  # Slack user IDs

Configuration Options

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable Slack channel
`bot_token`	string	Yes	Bot User OAuth Token (`xoxb-`)
`app_token`	string	Yes	App-Level Token (`xapp-`)
`allow_from`	array	No	Allowed Slack user IDs

User ID Format

Slack uses alphanumeric user IDs like U01234ABCDE. Finding User IDs:

Click on a user’s profile in Slack
Click “More” → “Copy member ID”
Or check Weaver logs after a message:
```
Received message sender_id=U01234ABCDE
```

Supported Features

Message Types

Direct Messages - Bot responds to all DMs
Channel Mentions - Responds when @mentioned in channels
Thread Replies - Maintains conversation threads
File Attachments - Downloads and processes files
Slash Commands - Custom /weaver commands (if configured)

Reactions & Indicators

👀 (eyes): Added when message is received
✅ (check mark): Added when response is sent
Threading: Replies maintain thread context

File Handling

File Types: All file types supported
Audio Files: Transcribed if Groq is enabled
Authentication: Uses bot token for private file downloads
Cleanup: Temporary files deleted after processing

Chat ID Format

Slack uses composite chat IDs:

Direct Messages: {channel_id} (e.g., D01234ABCDE)
Channel Threads: {channel_id}/{thread_ts} (e.g., C01234ABCDE/1234567890.123456)

Weaver automatically handles this format for threading.

Audio Transcription

Enable audio transcription in config.yaml:

voice:
  enabled: true
  groq_api_key: "your-groq-api-key"
  model: "whisper-large-v3"

channels:
  slack:
    enabled: true
    bot_token: "xoxb-..."
    app_token: "xapp-..."

When enabled, audio files are transcribed:

[voice transcription: Transcribed audio content here]

If transcription fails:

[audio: filename.mp3 (transcription failed)]

Bot Mention Handling

The bot automatically strips its own mention from messages: User sends:

@WeaverBot what is the weather?

Bot receives:

what is the weather?

Connection Mode: Socket Mode

Weaver uses Slack’s Socket Mode:

No webhook URL required - Bot connects via WebSocket
Works behind firewalls - Outbound connection only
Real-time events - Instant message delivery
Persistent connection - Auto-reconnects on disconnect

Why Socket Mode?

No need for public HTTPS endpoint
Simpler setup for development and self-hosting
Lower latency than HTTP webhooks
Built-in retry and reconnection logic

Error Handling

Common Issues

Invalid Tokens

slack auth test failed: invalid_auth

Verify bot_token starts with xoxb-
Verify app_token starts with xapp-
Regenerate tokens if needed

Missing Scopes

failed to send slack message: missing_scope

Add required scopes in OAuth & Permissions
Reinstall app to workspace

Socket Mode Not Enabled

Socket Mode connection error

Enable Socket Mode in app settings
Ensure app-level token has connections:write scope

User Not Allowed

Message rejected by allowlist user_id: U01234ABCDE

Add user ID to allow_from list
Or remove allow_from to allow all users

Security Considerations

Token Security: Keep bot and app tokens secret
Scope Minimization: Only request necessary OAuth scopes
Allowlist: Use allow_from to restrict access
File Access: Bot can only access files in channels it’s invited to

Metadata Captured

Each Slack message includes:

metadata:
  message_ts: "1234567890.123456"
  channel_id: "C01234ABCDE"
  thread_ts: "1234567890.123456"  # If in thread
  platform: "slack"
  is_mention: "true"  # If app was mentioned
  is_command: "true"  # If slash command

Example Configurations

Basic Setup

channels:
  slack:
    enabled: true
    bot_token: "xoxb-123456789012-1234567890123-AbCdEfGhIjKlMnOpQrStUvWx"
    app_token: "xapp-1-A01234ABCDE-1234567890123-abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"

With Allowlist & Transcription

channels:
  slack:
    enabled: true
    bot_token: "xoxb-..."
    app_token: "xapp-..."
    allow_from:
      - "U01234ABCDE"  # alice
      - "U56789FGHIJ"  # bob

voice:
  enabled: true
  groq_api_key: "gsk_..."

Logging

Monitor Slack activity:

# View Slack-specific logs
grep "slack" weaver.log

# Monitor connections and messages
tail -f weaver.log | grep slack

Log examples:

Starting Slack channel (Socket Mode)
Slack bot connected bot_user_id=U01234ABCDE team=YourTeam
Received message sender_id=U56789FGHIJ chat_id=C01234ABCDE/1234567890.123456
Message sent channel_id=C01234ABCDE thread_ts=1234567890.123456

Best Practices

Invite Bot to Channels: Use /invite @WeaverBot in channels where you want it active
Use Threads: Mention bot in threads to keep conversations organized
Set Display Info: Add bot description and icon in app settings
Monitor Reactions: Watch for 👀 and ✅ to track message flow
Test in Private Channel: Create a test channel for development

Slash Commands

If you created a /weaver slash command:

/weaver help
/weaver list agents
/weaver ask what is the weather?

Slash commands are processed like regular messages and can accept any text.

Thread Behavior

New conversations: Messages in channels start new threads
Existing threads: Replies stay in thread context
DMs: No threading (not supported in Slack DMs)

Next Steps

Configure Agents to respond in Slack
Set up Voice Transcription for audio files
Customize Bot Responses for workplace context

LLM Providers

Chat Channels

Slack Channel Integration

Prerequisites

Creating a Slack App

Configuration

Configuration Options

User ID Format

Supported Features

Message Types

Reactions & Indicators

File Handling

Chat ID Format

Audio Transcription

Bot Mention Handling

Connection Mode: Socket Mode

Why Socket Mode?

Error Handling

Common Issues

Security Considerations

Metadata Captured

Example Configurations

Basic Setup

With Allowlist & Transcription

Logging

Best Practices

Slash Commands

Thread Behavior

Next Steps

Build docs developers (and LLMs) love

LLM Providers

Chat Channels

​Prerequisites

​Creating a Slack App

​Configuration

​Configuration Options

​User ID Format

​Supported Features

​Message Types

​Reactions & Indicators

​File Handling

​Chat ID Format

​Audio Transcription

​Bot Mention Handling

​Connection Mode: Socket Mode

​Why Socket Mode?

​Error Handling

​Common Issues

​Security Considerations

​Metadata Captured

​Example Configurations

​Basic Setup

​With Allowlist & Transcription

​Logging

​Best Practices

​Slash Commands

​Thread Behavior

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Creating a Slack App

Configuration

Configuration Options

User ID Format

Supported Features

Message Types

Reactions & Indicators

File Handling

Chat ID Format

Audio Transcription

Bot Mention Handling

Connection Mode: Socket Mode

Why Socket Mode?

Error Handling

Common Issues

Security Considerations

Metadata Captured

Example Configurations

Basic Setup

With Allowlist & Transcription

Logging

Best Practices

Slash Commands

Thread Behavior

Next Steps