Slack Channel

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​

Features

• App mentions - @YourBot in any channel
• Direct messages - DM the bot directly
• Thread support - Conversations tracked via Slack’s native threading
• Signature validation - HMAC-based request verification
• DM pairing - Approve unknown users with pairing codes

​

Prerequisites

• Slack workspace admin access
• Public HTTPS URL for webhooks (ngrok, Cloudflare Tunnel, etc.)
• IronClaw installed and configured

​

Setup

​

1. Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App → From scratch
3. Name your app (e.g., “IronClaw Agent”) and select your workspace

​

2. Configure Bot Token Scopes

• app_mentions:read - Detect @mentions
• chat:write - Send messages
• im:history - Read DM history
• im:read - Access DM channels
• im:write - Send DMs

​

3. Install App to Workspace

1. Click Install to Workspace
2. Copy the Bot User OAuth Token (starts with xoxb-)

​

4. Enable Event Subscriptions

1. Go to Event Subscriptions → Enable Events
2. Set Request URL to https://your-tunnel-url/webhook/slack
3. Under Subscribe to bot events, add:
   • app_mention - Bot is mentioned
   • message.im - DM received
4. Save Changes

​

5. Get Signing Secret

1. Go to Basic Information → App Credentials
2. Copy the Signing Secret

​

6. Configure IronClaw

export SLACK_BOT_TOKEN=xoxb-your-token
export SLACK_SIGNING_SECRET=your-signing-secret

ironclaw onboard

​

7. Start IronClaw with Tunnel

# Start tunnel
ngrok http 8080

# Set tunnel URL
export TUNNEL_URL=https://abc123.ngrok-free.app

# Run IronClaw
ironclaw run

​

Configuration

{
  "config": {
    "signing_secret_name": "slack_signing_secret",
    "owner_id": null,
    "dm_policy": "pairing",
    "allow_from": []
  }
}

​

Configuration Options

​

DM Pairing

​

Flow

1. Unknown user sends a DM
2. Bot replies: To pair with this bot, run: ironclaw pairing approve slack ABC12345
3. You run: ironclaw pairing approve slack ABC12345
4. User is added to the allow list; future messages are delivered

​

Commands

# List pending pairing requests
ironclaw pairing list slack

# Approve a user by code
ironclaw pairing approve slack ABC12345

​

Usage

​

App Mentions (Channel)

You: @IronClaw what's the current sprint status?
Bot: Let me check the project board...
     [reads workspace data]
     Current sprint: 5 tasks in progress, 3 blocked.

​

Direct Messages

You: Help me debug this error
Bot: Sure! Can you share the error message?

You: TypeError: Cannot read property 'map' of undefined
Bot: This error means you're calling .map() on a variable that is undefined.
     Let me check your code...

​

Threaded Conversations

You: @IronClaw summarize this channel's history
Bot: [in thread] Here's a summary of the last 50 messages...

You: [in thread] What were the main action items?
Bot: [in thread] Main action items:
     1. Fix deployment pipeline
     2. Update documentation
     3. Schedule team sync

​

Secrets

​

Bot Token

export SLACK_BOT_TOKEN=xoxb-123-456-abc

ironclaw secrets set slack_bot_token

​

Signing Secret

export SLACK_SIGNING_SECRET=your-signing-secret

​

Events

​

URL Verification

{
  "type": "url_verification",
  "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"
}

​

Event Callback

{
  "type": "event_callback",
  "event": {
    "type": "app_mention",
    "user": "U123ABC",
    "text": "<@U987XYZ> hello",
    "channel": "C456DEF",
    "ts": "1234567890.123456"
  }
}

​

Message Metadata

{
  "channel": "C456DEF",
  "thread_ts": "1234567890.123456",
  "message_ts": "1234567890.123456",
  "team_id": "T789GHI"
}

​

Permissions

​

Owner Restriction

{
  "config": {
    "owner_id": "U123ABC"
  }
}

​

DM Policy

{"dm_policy": "open"}

{
  "dm_policy": "allowlist",
  "allow_from": ["U123ABC", "U456DEF"]
}

{
  "dm_policy": "pairing",
  "allow_from": ["U123ABC"]
}

​

Rate Limiting

​

Manual Installation

# Build the Slack channel (requires wasm32-wasip2 target)
rustup target add wasm32-wasip2
cd ~/workspace/source/channels-src/slack
./build.sh

# Install
mkdir -p ~/.ironclaw/channels
cp slack.wasm slack.capabilities.json ~/.ironclaw/channels/

​

Troubleshooting

​

Events not received

1. Check Request URL - Verify the URL in Slack’s Event Subscriptions matches your tunnel
2. Tunnel running - Ensure ngrok/Cloudflare tunnel is active
3. Logs - Check ironclaw run logs for “Slack event” messages
4. Signature validation - Ensure SLACK_SIGNING_SECRET is correct

​

Bot not responding

1. Bot is a member - Add the bot to the channel (/invite @YourBot)
2. Permissions - Verify bot has chat:write scope
3. Token valid - Check SLACK_BOT_TOKEN starts with xoxb-
4. Logs - Look for “Slack API error” in logs

​

Pairing not working

1. DM policy - Ensure dm_policy is "pairing"
2. Signing secret - Verify signature validation passes
3. Logs - Check for “Pairing request” or “Pairing upsert failed”

​

Signature validation fails

• Ensure SLACK_SIGNING_SECRET matches the value in Slack App Credentials
• Check system clock is accurate (HMAC uses timestamp)
• Verify webhook requests are coming from Slack (not a proxy/firewall rewriting headers)

​

Source Code

• Implementation: ~/workspace/source/channels-src/slack/src/lib.rs
• Capabilities: ~/workspace/source/channels-src/slack/slack.capabilities.json

​

Example App Manifest

display_information:
  name: IronClaw Agent
features:
  bot_user:
    display_name: IronClaw
    always_online: true
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - im:history
      - im:read
      - im:write
settings:
  event_subscriptions:
    request_url: https://your-tunnel-url/webhook/slack
    bot_events:
      - app_mention
      - message.im
  org_deploy_enabled: false
  socket_mode_enabled: false

1. Go to api.slack.com/apps
2. Click Create New App → From an app manifest
3. Paste the manifest above
4. Update request_url with your tunnel URL
5. Install to workspace