agentic-govbot/SLACK_SETUP.md

Slack Setup Guide

This guide walks through setting up Govbot for a Slack channel with channel-scoped governance.

Overview

The Slack adapter enables channel-scoped governance where the bot manages a single channel without requiring workspace admin permissions. This makes it ideal for:

• Department or team governance within larger organizations
• Project-specific decision-making channels
• Community spaces within company Slack workspaces
• Testing governance patterns before workspace-wide deployment

Prerequisites

• Slack workspace (free or paid tier)
• Permission to create Slack apps in the workspace
• Python 3.11+ installed
• Ollama (for local models) or API keys for cloud models

Capabilities

The Slack adapter provides 16 governance skills across 5 categories:

Channel Access Control

• Invite/remove users from the governance channel
• Control who participates in governance

Channel Management

• Create new channels for working groups
• Archive/unarchive channels
• Set channel topic and purpose
• Rename channels

User Group Management (Channel "Roles")

• Create user groups as governance roles
• Add/remove users from groups
• Enable/disable groups
• Use groups to tag teams (e.g., @moderators, @council)

Message Management

• Pin important governance decisions
• Unpin outdated information

Content Moderation

• Delete messages (requires user:write scope)

Platform Limitations

Workspace Admin Only (not available via channel bot):

• User account management (deactivate, invite new users)
• Workspace settings
• Emoji management
• Billing and plans

Not Possible via API:

• Role/permission management (owners, admins)
• Slack Connect (external organizations)
• Enterprise Grid features
• Workflow management

The bot is aware of these limitations and will explain them to users when requested.

Step 1: Create Slack App

1.1 Create App

1. Go to Slack API Dashboard
2. Click "Create New App"
3. Choose "From scratch"
4. Enter:
   • App Name: Govbot
   • Workspace: Select your workspace
5. Click "Create App"

1.2 Configure Bot Token Scopes

Navigate to OAuth & Permissions → Scopes → Bot Token Scopes

Add these scopes:

Essential (Required):

• app_mentions:read - Receive mentions of the bot
• chat:write - Post messages
• channels:read - View basic channel info
• channels:manage - Manage channels (rename, archive, etc.)
• channels:history - Read message history
• users:read - Get user information
• usergroups:read - View user groups
• usergroups:write - Create and manage user groups
• pins:write - Pin/unpin messages

Optional (Enhanced Features):

• channels:write - Create new channels
• chat:write.public - Post to channels bot isn't in
• im:read - Read direct messages
• im:write - Send direct messages
• im:history - Read DM history

Moderation (If Needed):

• chat:write.customize - Post as other users (for announcements)
• users:write - Modify user accounts (requires admin)

1.3 Enable Socket Mode

1. Navigate to Socket Mode in the sidebar
2. Click "Enable Socket Mode"
3. When prompted, create an app-level token:
   • Token Name: govbot-socket
   • Scopes: connections:write
4. Save the app token (starts with xapp-) - you'll need this

1.4 Enable Events

1. Navigate to Event Subscriptions
2. Toggle "Enable Events" to On
3. Under Subscribe to bot events, add:
   • app_mention - When someone mentions the bot
   • message.im - Direct messages to the bot
4. Click "Save Changes"

1.5 Install App to Workspace

1. Navigate to Install App
2. Click "Install to Workspace"
3. Review permissions and click "Allow"
4. Save the Bot User OAuth Token (starts with xoxb-) - you'll need this

Step 2: Add Bot to Channel

2.1 Create or Select Governance Channel

1. Create a new channel (e.g., #governance) or select existing channel
2. Invite the bot to the channel:

   /invite @Govbot
   

2.2 Get Channel ID

Method 1: Via Channel Details

1. Right-click the channel name
2. Click "View channel details"
3. Scroll to bottom - Channel ID is shown
4. Copy the ID (format: C0123456789)

Method 2: Via URL

• When viewing the channel, the URL contains the ID: https://app.slack.com/client/T.../C0123456789 (The part after the last / starting with C)

Step 3: Configure Govbot

3.1 Update Configuration File

1. Copy the example config:

   cp config/config.example.yaml config/config.yaml
   

2. Edit config/config.yaml:

   platform:
     type: slack
   
     slack:
       bot_token: xoxb-your-bot-oauth-token-here
       app_token: xapp-your-app-level-token-here
       channel_id: C0123456789  # Your governance channel ID
   
   ai:
     # For local models:
     default_model: llama3.2
   
     # For cloud models:
     # default_model: gpt-4o-mini
     # openai_api_key: your-key-here
     # (or configure with: llm keys set openai)
   
   governance:
     constitution_path: constitution.md
     db_path: govbot.db
     default_veto_threshold: 0.67
     enable_auto_execution: true
     require_confirmation_for:
       - admin_action
       - moderation
   
   debug: false
   log_level: INFO
   

3. Test LLM configuration:

   # Activate virtual environment
   source .venv/bin/activate
   
   # Test that llm works
   llm "Hello, test message"
   
   # If using local models, verify Ollama is running
   ollama list
   

Step 4: Initialize Database

# Activate virtual environment
source .venv/bin/activate

# Create the database
python -c "from src.govbot.db.models import init_db; init_db('govbot.db'); print('Database initialized!')"

Step 5: Test with CLI

Before connecting to Slack, test the bot logic:

# Run the CLI
python -m src.govbot

# Try these commands:
query What are the rules for proposals?
propose We should have weekly team meetings
processes
exit

Step 6: Install Dependencies

# Activate virtual environment
source .venv/bin/activate

# Install/update dependencies (includes slack-sdk)
uv pip install -e .
# Or: pip install -e .

Step 7: Run the Bot

# Activate virtual environment
source .venv/bin/activate

# Start the bot
python -m src.govbot.bot

# You should see:
# INFO - Creating slack platform adapter...
# INFO - Connected to platform successfully
# INFO - Started listening for messages
# INFO - Bot is running. Press Ctrl+C to stop.

Step 8: Test on Slack

Basic Test

In your governance channel, type:

@Govbot help

The bot should respond with information about governance commands.

Create a Proposal

@Govbot I propose we add a weekly team retrospective on Fridays

The bot should:

• Acknowledge the proposal
• Cite constitutional authority
• Explain voting period and threshold
• Provide voting instructions

Vote on Proposal

In a thread reply or new message:

@Govbot agree

Check Status

@Govbot status 1

Test Platform Skills

@Govbot what actions can you perform in this channel?

Create a User Group (Role)

@Govbot create a user group called "council" for governance leadership

Platform Skills Reference

Channel Access

• invite_to_channel: Add user to governance channel
• remove_from_channel: Remove user from channel

Channel Management

• create_channel: Create new channel for working groups
• archive_channel: Archive a channel
• unarchive_channel: Restore archived channel
• set_channel_topic: Update channel topic
• set_channel_purpose: Update channel description
• rename_channel: Change channel name

User Groups (Roles)

• create_user_group: Create governance role (e.g., @moderators)
• add_to_user_group: Add user to role
• remove_from_user_group: Remove user from role
• disable_user_group: Disable a role

Message Management

• pin_message: Pin important decisions
• unpin_message: Unpin messages
• delete_message: Remove inappropriate content

Troubleshooting

Bot Not Responding

Check:

• Bot is invited to the channel (/invite @Govbot)
• Bot token (xoxb-...) is correct
• App token (xapp-...) is correct
• Socket Mode is enabled
• Events are subscribed (app_mention, message.im)
• Bot process is running (check logs)

Test manually:

from slack_sdk import WebClient

client = WebClient(token="xoxb-your-token")
response = client.auth_test()
print(f"Bot ID: {response['user_id']}")
print(f"Bot Name: {response['user']}")

Socket Mode Connection Errors

Check:

• App token has connections:write scope
• No firewall blocking WebSocket connections
• Correct app token (not bot token)

Enable debug logging:

debug: true
log_level: DEBUG

Permission Errors

Common issues:

• Missing bot token scopes (check OAuth & Permissions)
• Bot not invited to channel
• User attempting action they don't have permission for

Verify scopes:

from slack_sdk import WebClient

client = WebClient(token="xoxb-your-token")
response = client.auth_test()
print(response)  # Shows which scopes are active

Channel ID Issues

Symptoms: Bot responds but actions fail

Fix: Verify channel ID

from slack_sdk import WebClient

client = WebClient(token="xoxb-your-token")
response = client.conversations_list()
for channel in response['channels']:
    print(f"{channel['name']}: {channel['id']}")

LLM Errors

For local models:

# Check Ollama is running
ollama list
ollama ps

# Test the model
llm -m llama3.2 "test"

For cloud models:

# Check API keys
llm keys list

# Test the model
llm -m gpt-4o-mini "test"

Database Errors

Reset database:

# Backup first!
cp govbot.db govbot.db.backup

# Delete and reinitialize
rm govbot.db
python -c "from src.govbot.db.models import init_db; init_db('govbot.db')"

Security Considerations

📖 See SECURITY.md for the complete security guide.

Credentials

• Never commit config/config.yaml to version control (it's in .gitignore)
• Store tokens securely
• Use environment variables for production:

  export GOVBOT_PLATFORM__SLACK__BOT_TOKEN="xoxb-..."
  export GOVBOT_PLATFORM__SLACK__APP_TOKEN="xapp-..."
  export GOVBOT_PLATFORM__SLACK__CHANNEL_ID="C0123456789"
  

• Rotate tokens periodically via Slack App dashboard
• Use separate apps for development and production

Access Control

• Limit bot scopes to minimum required
• Don't grant unnecessary permissions
• Monitor bot actions through Slack audit logs
• Review user group membership regularly
• Use channel-specific governance (not workspace-wide)

Rate Limiting

Slack has rate limits for API calls:

• Tier 1: 1 request per second (most methods)
• Tier 2: 20 requests per minute (sending messages)
• Tier 3: 50 requests per minute (most read operations)

The bot handles rate limits automatically with retries, but be aware for high-volume governance.

Production Deployment

Systemd Service

Create /etc/systemd/system/govbot.service:

[Unit]
Description=Govbot Governance Bot (Slack)
After=network.target

[Service]
Type=simple
User=govbot
WorkingDirectory=/home/govbot/agentic-govbot
ExecStart=/usr/bin/python3 -m src.govbot.bot
Restart=always
RestartSec=10

Environment="GOVBOT_PLATFORM__SLACK__BOT_TOKEN=xoxb-..."
Environment="GOVBOT_PLATFORM__SLACK__APP_TOKEN=xapp-..."
Environment="GOVBOT_PLATFORM__SLACK__CHANNEL_ID=C0123456789"
Environment="GOVBOT_LOG_LEVEL=INFO"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable govbot
sudo systemctl start govbot
sudo systemctl status govbot

# View logs
sudo journalctl -u govbot -f

Docker Deployment

Create Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

CMD ["python", "-m", "src.govbot.bot"]

Build and run:

docker build -t govbot .
docker run \
  -e GOVBOT_PLATFORM__SLACK__BOT_TOKEN=xoxb-... \
  -e GOVBOT_PLATFORM__SLACK__APP_TOKEN=xapp-... \
  -e GOVBOT_PLATFORM__SLACK__CHANNEL_ID=C0123456789 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/govbot.db:/app/govbot.db \
  govbot

Monitoring

• Monitor Socket Mode connection health
• Track API rate limit usage
• Log all governance actions
• Alert on connection failures
• Monitor database growth
• Track user group membership changes

Advanced Configuration

Multiple Channels

To manage multiple governance channels, run multiple bot instances:

# config/governance-channel-1.yaml
platform:
  type: slack
  slack:
    bot_token: xoxb-same-token
    app_token: xapp-same-token
    channel_id: C0111111111  # Different channel

governance:
  db_path: govbot-channel1.db  # Separate database

User Groups as Roles

User groups act as channel "roles":

# Create governance roles
@Govbot create user group "moderators"
@Govbot create user group "council"
@Govbot create user group "working-group-a"

# Assign members
@Govbot add @alice to moderators
@Govbot add @bob to council

# Use in governance
"Only @moderators can approve reports"
"@council members have veto power"

Custom Constitution

Edit constitution.md to define Slack-specific governance:

## Slack Governance

### Channel Roles
- **@moderators**: Handle reports and moderation
- **@council**: Make policy decisions
- **Members**: All channel participants

### Channel Management
New channels require:
1. Proposal with clear purpose
2. 2/3 approval from @council
3. Assignment of channel owner

### User Groups
- Creation requires council approval
- Membership changes logged publicly
- Groups reviewed quarterly

Next Steps

• Customize the constitution for your team/department
• Test governance workflows with your team
• Create initial user groups (roles)
• Set up announcement patterns
• Document your Slack governance process
• Gather feedback and iterate

Getting Help

• Check README.md for general architecture
• Review PLATFORMS.md for platform details
• See MASTODON_SETUP.md for comparison
• Review Slack API Documentation
• Open an issue on GitHub for bugs or questions

Comparison: Slack vs Mastodon

Feature	Slack	Mastodon
Scope	Channel-scoped	Instance-wide
Admin Powers	Limited to channel	Full instance admin
Setup	OAuth app + tokens	OAuth + instance admin
User Management	User groups only	Full account management
Moderation	Message deletion	Suspend, silence, ban
Federation	No	Yes (block domains)
Rate Limits	Tiered, generous	Per instance config
Best For	Team/dept governance	Community instance governance

---

Important: This is governance infrastructure for your team. Test thoroughly with a small group before deploying to larger channels!