agent-slackbot

Original source / Raw SKILL.md

---
name: agent-slackbot
description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
version: 1.10.5
allowed-tools: Bash(agent-slackbot:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-slackbot
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-slackbot]
---

# Agent SlackBot

A TypeScript CLI tool that enables AI agents and humans to interact with Slack workspaces using bot tokens (xoxb-). Unlike agent-slack which extracts user tokens from the desktop app, agent-slackbot uses standard Slack Bot tokens for server-side and CI/CD integrations.

## Quick Start

```bash
# Set your bot token
agent-slackbot auth set xoxb-your-bot-token

# Or set with a custom bot identifier for multi-bot setups
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Verify authentication
agent-slackbot auth status

# Send a message
agent-slackbot message send C0ACZKTDDC0 "Hello from bot!"

# List channels
agent-slackbot channel list
```

## Authentication

### Bot Token Setup

agent-slackbot uses Slack Bot tokens (xoxb-) which you get from the Slack App configuration:

```bash
# Set bot token (validates against Slack API before saving)
agent-slackbot auth set xoxb-your-bot-token

# Set with a custom bot identifier
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Check auth status
agent-slackbot auth status

# Clear stored credentials
agent-slackbot auth clear
```

### Multi-Bot Management

Store multiple bot tokens and switch between them:

```bash
# Add multiple bots
agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot"
agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"

# List all stored bots
agent-slackbot auth list

# Switch active bot
agent-slackbot auth use deploy

# Use a specific bot for one command (without switching)
agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert

# Remove a stored bot
agent-slackbot auth remove deploy

# Disambiguate bots with same ID across workspaces
agent-slackbot auth use T123456/deploy
```

The `--bot <id>` flag is available on all commands to override the active bot for a single invocation.

### Getting a Bot Token

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Create New App (or select existing)
3. Go to **OAuth & Permissions**
4. Add required bot token scopes (see below)
5. Install app to workspace
6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)

### Required Bot Token Scopes

| Scope | Used For |
|-------|----------|
| `chat:write` | Sending messages |
| `channels:history` | Reading public channel messages |
| `channels:read` | Listing public channels |
| `channels:join` | Joining public channels |
| `groups:history` | Reading private channel messages |
| `groups:read` | Listing private channels |
| `users:read` | Listing users |
| `users:read.email` | Reading user email addresses |
| `reactions:write` | Adding/removing reactions |
| `reactions:read` | Listing reactions |

### Environment Variables (CI/CD)

For CI/CD pipelines, set these environment variables instead of using `auth set`:

```bash
export E2E_SLACKBOT_TOKEN=xoxb-your-bot-token
export E2E_SLACKBOT_WORKSPACE_ID=T123456
export E2E_SLACKBOT_WORKSPACE_NAME="My Workspace"
```

## Memory

The agent maintains a `~/.config/agent-messenger/MEMORY.md` file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the `Read` and `Write` tools to manage your memory file.

### Reading Memory

At the **start of every task**, read `~/.config/agent-messenger/MEMORY.md` using the `Read` tool to load any previously discovered workspace IDs, channel IDs, user IDs, and preferences.

- If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
- If the file can't be read (permissions, missing directory), proceed without memory — don't error out.

### Writing Memory

After discovering useful information, update `~/.config/agent-messenger/MEMORY.md` using the `Write` tool. Write triggers include:

- After discovering workspace IDs (from `auth status`)
- After discovering useful channel IDs and names (from `channel list`, etc.)
- After discovering user IDs and names (from `user list`, etc.)
- After the user gives you an alias or preference ("call this the alerts bot", "my main workspace is X")
- After setting up bot identifiers (from `auth list`)

When writing, include the **complete file content** — the `Write` tool overwrites the entire file.

### What to Store

- Workspace IDs with names
- Channel IDs with names and purpose
- User IDs with display names
- Bot identifiers and their purposes
- User-given aliases ("alerts bot", "deploys channel")
- Any user preference expressed during interaction

### What NOT to Store

Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and channel context). Never store file upload contents.

### Handling Stale Data

If a memorized ID returns an error (channel not found, user not found), remove it from `MEMORY.md`. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

### Format / Example

```markdown
# Agent Messenger Memory

## Slack Workspaces (Bot)

- `T0ABC1234` — Acme Corp

## Bots (Acme Corp)

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Channels (Acme Corp)

- `C012ABC` — #general (company-wide announcements)
- `C034DEF` — #engineering (team discussion)
- `C056GHI` — #deploys (CI/CD notifications)

## Users (Acme Corp)

- `U0ABC123` — Alice (engineering lead)
- `U0DEF456` — Bob (backend)

## Aliases

- "deploys" → `C056GHI` (#deploys in Acme Corp)

## Notes

- Deploy Bot is used for CI/CD notifications
- Alert Bot is used for error monitoring
```

> Memory lets you skip repeated `channel list` and `auth list` calls. When you already know an ID from a previous session, use it directly.

## Commands

### Message Commands

```bash
# Send a message
agent-slackbot message send <channel> <text>
agent-slackbot message send C0ACZKTDDC0 "Hello world"

# Send a threaded reply
agent-slackbot message send C0ACZKTDDC0 "Reply" --thread <ts>

# List messages
agent-slackbot message list <channel>
agent-slackbot message list C0ACZKTDDC0 --limit 50

# Get a single message by timestamp
agent-slackbot message get <channel> <ts>

# Get thread replies (includes parent message)
agent-slackbot message replies <channel> <thread_ts>
agent-slackbot message replies C0ACZKTDDC0 1234567890.123456 --limit 50

# Update a message (bot's own messages only)
agent-slackbot message update <channel> <ts> <new-text>

# Delete a message (bot's own messages only)
agent-slackbot message delete <channel> <ts> --force
```

### Channel Commands

```bash
# List channels the bot can see
agent-slackbot channel list
agent-slackbot channel list --limit 50

# Get channel info
agent-slackbot channel info <channel>
agent-slackbot channel info C0ACZKTDDC0
```

### User Commands

```bash
# List users
agent-slackbot user list
agent-slackbot user list --limit 50

# Get user info
agent-slackbot user info <user-id>
```

### Reaction Commands

```bash
# Add reaction
agent-slackbot reaction add <channel> <ts> <emoji>
agent-slackbot reaction add C0ACZKTDDC0 1234567890.123456 thumbsup

# Remove reaction
agent-slackbot reaction remove <channel> <ts> <emoji>
```

## Output Format

### JSON (Default)

All commands output JSON by default for AI consumption:

```json
{
  "ts": "1234567890.123456",
  "channel": "C0ACZKTDDC0",
  "text": "Hello world"
}
```

### Pretty (Human-Readable)

Use `--pretty` flag for formatted output:

```bash
agent-slackbot channel list --pretty
```

## Common Patterns

See `references/common-patterns.md` for typical AI agent workflows.

## Templates

See `templates/` directory for runnable examples:
- `post-message.sh` - Send messages with error handling
- `monitor-channel.sh` - Monitor channel for new messages
- `workspace-summary.sh` - Generate workspace summary

## Error Handling

All commands return consistent error format:

```json
{
  "error": "No credentials. Run \"auth set\" first."
}
```

Common errors:
- `missing_token`: No credentials configured
- `invalid_token_type`: Token is not a bot token (must start with xoxb-)
- `not_in_channel`: Bot needs to join the channel first
- `slack_webapi_rate_limited_error`: Hit rate limit (auto-retries with backoff)

## Configuration

Credentials stored in: `~/.config/agent-messenger/slackbot-credentials.json`

Format:
```json
{
  "current": {
    "workspace_id": "T123456",
    "bot_id": "deploy"
  },
  "workspaces": {
    "T123456": {
      "workspace_id": "T123456",
      "workspace_name": "My Workspace",
      "bots": {
        "deploy": {
          "bot_id": "deploy",
          "bot_name": "Deploy Bot",
          "token": "xoxb-..."
        },
        "alert": {
          "bot_id": "alert",
          "bot_name": "Alert Bot",
          "token": "xoxb-..."
        }
      }
    }
  }
}
```

**Security**: File permissions set to 0600 (owner read/write only)

## Key Differences from agent-slack

| Feature | agent-slack | agent-slackbot |
|---------|------------|----------------|
| Token type | User token (xoxc-) | Bot token (xoxb-) |
| Token source | Auto-extracted from desktop app | Manual from Slack App config |
| Message search | Yes | No (requires user token) |
| File operations | Yes | No |
| Snapshot | Yes | No |
| Edit/delete messages | Any message | Bot's own messages only |
| Workspace management | Multi-workspace | Multi-bot, multi-workspace |
| CI/CD friendly | Requires desktop app | Yes (just set token) |

## Limitations

- No real-time events / Socket Mode
- No message search (requires user token scope)
- No file upload/download
- No workspace snapshot
- Bot can only edit/delete its own messages
- Bot must be invited to private channels
- No scheduled messages
- Plain text messages only (no blocks/formatting)

## Troubleshooting

### `agent-slackbot: command not found`

**`agent-slackbot` is NOT the npm package name.** The npm package is `agent-messenger`.

If the package is installed globally, use `agent-slackbot` directly:

```bash
agent-slackbot message send general "Hello"
```

If the package is NOT installed, use `bunx agent-messenger slackbot`:

```bash
bunx agent-messenger slackbot message send general "Hello"
```

**NEVER run `bunx agent-slackbot`** — it will fail or install a wrong package since `agent-slackbot` is not the npm package name.

## References

- [Authentication Guide](references/authentication.md)
- [Common Patterns](references/common-patterns.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/authentication.md

```markdown
# Authentication Guide

## Overview

agent-slackbot uses Slack Bot tokens (xoxb-) obtained from the Slack App configuration page. Unlike agent-slack which extracts user tokens from the desktop app, bot tokens are explicitly created and managed through the Slack API portal.

## Bot Token Setup

### Creating a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App** > **From scratch**
3. Enter app name and select workspace
4. Go to **OAuth & Permissions**

### Required Scopes

Add these **Bot Token Scopes**:

| Scope | Purpose |
|-------|---------|
| `chat:write` | Send and update messages |
| `channels:history` | Read messages in public channels |
| `channels:read` | List and get info for public channels |
| `channels:join` | Join public channels |
| `groups:history` | Read messages in private channels |
| `groups:read` | List and get info for private channels |
| `users:read` | List workspace users |
| `users:read.email` | Access user email addresses |
| `reactions:write` | Add and remove emoji reactions |
| `reactions:read` | List reactions on messages |

### Installing the App

1. Click **Install to Workspace** on the OAuth & Permissions page
2. Review and **Allow** the requested permissions
3. Copy the **Bot User OAuth Token** (starts with `xoxb-`)

### Setting the Token

```bash
# Basic setup
agent-slackbot auth set xoxb-your-bot-token

# With a custom bot identifier (for multi-bot setups)
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"
```

This command:
1. Validates the token format (must start with `xoxb-`)
2. Calls `auth.test` to verify the token against Slack API
3. Stores the bot under the workspace with its bot ID and name
4. Sets this bot as the current active bot
5. Saves credentials to `~/.config/agent-messenger/slackbot-credentials.json`

## Credential Storage

### Location

```
~/.config/agent-messenger/slackbot-credentials.json
```

### Format

```json
{
  "current": {
    "workspace_id": "T123456",
    "bot_id": "deploy"
  },
  "workspaces": {
    "T123456": {
      "workspace_id": "T123456",
      "workspace_name": "My Workspace",
      "bots": {
        "deploy": {
          "bot_id": "deploy",
          "bot_name": "Deploy Bot",
          "token": "xoxb-1234567890-1234567890-abcdef..."
        }
      }
    }
  }
}
```

### Security

- File permissions: `0600` (owner read/write only)
- Token stored in plaintext (standard for CLI tools)
- Keep this file secure - it grants bot-level access to your workspace

## Environment Variables (CI/CD)

For automated environments, use environment variables instead of file-based credentials:

```bash
export E2E_SLACKBOT_TOKEN=xoxb-your-bot-token
export E2E_SLACKBOT_WORKSPACE_ID=T123456
export E2E_SLACKBOT_WORKSPACE_NAME="My Workspace"
```

Environment variables take precedence over file-based credentials.

## Multi-Bot Management

Store and switch between multiple bot tokens:

```bash
# Add multiple bots
agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot"
agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"

# List all stored bots
agent-slackbot auth list

# Switch active bot
agent-slackbot auth use deploy

# Use a specific bot for one command
agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert

# Remove a stored bot
agent-slackbot auth remove deploy

# Disambiguate across workspaces
agent-slackbot auth use T123456/deploy
```

## Authentication Status

Check current authentication state:

```bash
agent-slackbot auth status
```

Output when authenticated:
```json
{
  "valid": true,
  "workspace_id": "T123456",
  "workspace_name": "My Workspace",
  "bot_id": "deploy",
  "bot_name": "Deploy Bot",
  "user": "mybot",
  "team": "My Workspace"
}
```

Output when not authenticated:
```json
{
  "valid": false,
  "error": "No credentials configured. Run \"auth set <token>\" first."
}
```

## Clearing Credentials

Remove stored credentials:

```bash
agent-slackbot auth clear
```

## Token Lifecycle

### When Tokens Stop Working

Bot tokens can be invalidated when:
- App is uninstalled from workspace
- App is deleted from api.slack.com
- Token is manually revoked
- Required scopes change (need reinstall)

### Re-authentication

```bash
# Get a new token from api.slack.com/apps > OAuth & Permissions
agent-slackbot auth set xoxb-new-bot-token

# Verify
agent-slackbot auth status
```

## Troubleshooting

### "not_in_channel" Error

The bot must join a channel before posting messages to it:

```bash
# Bots auto-join public channels when posting via API if they have channels:join scope
# For private channels, manually invite the bot from Slack UI
```

### "invalid_auth" Error

Token is expired or revoked:
1. Go to api.slack.com/apps > your app > OAuth & Permissions
2. Check if the app is still installed
3. Reinstall if needed and copy the new token
4. Run `agent-slackbot auth set xoxb-new-token`

### "missing_scope" Error

The bot token lacks required permissions:
1. Go to api.slack.com/apps > your app > OAuth & Permissions
2. Add the missing scope under Bot Token Scopes
3. Reinstall the app to workspace
4. Copy the new token and run `agent-slackbot auth set xoxb-new-token`

## App Manifest

For quick setup, use this Slack App manifest:

```yaml
display_information:
  name: Agent Messenger Bot
  description: Bot for agent-messenger CLI integration
  background_color: "#1a1a2e"

features:
  bot_user:
    display_name: agent-messenger
    always_online: false

oauth_config:
  scopes:
    bot:
      - chat:write
      - channels:history
      - channels:read
      - channels:join
      - groups:history
      - groups:read
      - users:read
      - users:read.email
      - reactions:write
      - reactions:read

settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
```

1. Go to [api.slack.com/apps](https://api.slack.com/apps) > **Create New App** > **From an app manifest**
2. Select workspace, paste YAML, create
3. Install to workspace
4. Copy Bot User OAuth Token

```

### references/common-patterns.md

```markdown
# Common Patterns

## Overview

This guide covers typical workflows for AI agents interacting with Slack using agent-slackbot (bot tokens).

## Pattern 1: Send a Simple Message

**Use case**: Post a notification or update to a channel

```bash
#!/bin/bash

CHANNEL="C0ACZKTDDC0"

RESULT=$(agent-slackbot message send "$CHANNEL" "Deployment completed!")
TS=$(echo "$RESULT" | jq -r '.ts')

if [ -n "$TS" ] && [ "$TS" != "null" ]; then
  echo "Message sent: $TS"
else
  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
  exit 1
fi
```

**When to use**: Simple one-off messages, notifications, alerts.

## Pattern 2: Thread Conversation

**Use case**: Send progress updates in a thread

```bash
#!/bin/bash

CHANNEL="C0ACZKTDDC0"

# Send initial message
RESULT=$(agent-slackbot message send "$CHANNEL" "Starting deployment...")
THREAD_TS=$(echo "$RESULT" | jq -r '.ts')

# Send updates in thread
agent-slackbot message send "$CHANNEL" "Building application..." --thread "$THREAD_TS"
sleep 2
agent-slackbot message send "$CHANNEL" "Running tests..." --thread "$THREAD_TS"
sleep 2
agent-slackbot message send "$CHANNEL" "Deploying to production..." --thread "$THREAD_TS"
sleep 2

# Update parent with final status
agent-slackbot message update "$CHANNEL" "$THREAD_TS" "Deployment complete!"

# Add reaction
agent-slackbot reaction add "$CHANNEL" "$THREAD_TS" white_check_mark
```

**When to use**: Multi-step processes, CI/CD pipelines, progress tracking.

## Pattern 3: Monitor Channel for New Messages

**Use case**: Poll a channel and respond to new messages

```bash
#!/bin/bash

CHANNEL="C0ACZKTDDC0"
LAST_TS=""

while true; do
  MESSAGES=$(agent-slackbot message list "$CHANNEL" --limit 1)
  LATEST_TS=$(echo "$MESSAGES" | jq -r '.[0].ts // ""')

  if [ "$LATEST_TS" != "$LAST_TS" ] && [ -n "$LAST_TS" ]; then
    TEXT=$(echo "$MESSAGES" | jq -r '.[0].text // ""')
    echo "New message: $TEXT"

    # Respond if needed
    if echo "$TEXT" | grep -qi "help"; then
      agent-slackbot message send "$CHANNEL" "How can I help?" --thread "$LATEST_TS"
    fi
  fi

  LAST_TS="$LATEST_TS"
  sleep 10
done
```

**Limitations**: Polling-based, not real-time. For production bots, use Slack's Events API.

## Pattern 4: Reaction-Based Workflow

**Use case**: Use reactions as status indicators

```bash
#!/bin/bash

CHANNEL="C0ACZKTDDC0"

# Send task message
RESULT=$(agent-slackbot message send "$CHANNEL" "Processing request...")
MSG_TS=$(echo "$RESULT" | jq -r '.ts')

# Mark as in-progress
agent-slackbot reaction add "$CHANNEL" "$MSG_TS" hourglass_flowing_sand

# Do work...
sleep 5

# Remove in-progress, add success
agent-slackbot reaction remove "$CHANNEL" "$MSG_TS" hourglass_flowing_sand
agent-slackbot reaction add "$CHANNEL" "$MSG_TS" white_check_mark

# Update message with result
agent-slackbot message update "$CHANNEL" "$MSG_TS" "Request processed successfully!"
```

**When to use**: Visual status tracking, acknowledgments, workflow states.

## Pattern 5: Multi-Channel Broadcast

**Use case**: Send the same message to multiple channels

```bash
#!/bin/bash

MESSAGE="System maintenance in 30 minutes"
CHANNELS=("C0ACZKTDDC0" "C0AC1NCF8NR")

for channel in "${CHANNELS[@]}"; do
  RESULT=$(agent-slackbot message send "$channel" "$MESSAGE")
  TS=$(echo "$RESULT" | jq -r '.ts // "failed"')
  echo "Channel $channel: $TS"
  sleep 1
done
```

**When to use**: Announcements, alerts across multiple channels.

## Pattern 6: Error Handling and Retry

**Use case**: Robust message sending for production

```bash
#!/bin/bash

send_with_retry() {
  local channel=$1
  local message=$2
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    RESULT=$(agent-slackbot message send "$channel" "$message" 2>&1)
    TS=$(echo "$RESULT" | jq -r '.ts // ""')

    if [ -n "$TS" ] && [ "$TS" != "null" ]; then
      echo "Sent: $TS"
      return 0
    fi

    ERROR=$(echo "$RESULT" | jq -r '.error // "unknown"')
    echo "Attempt $attempt failed: $ERROR"

    # Don't retry on permanent errors
    case "$ERROR" in
      *"not_in_channel"*|*"channel_not_found"*)
        return 1 ;;
    esac

    sleep $((attempt * 2))
    attempt=$((attempt + 1))
  done

  echo "Failed after $max_attempts attempts"
  return 1
}

send_with_retry "C0ACZKTDDC0" "Important notification!"
```

## Best Practices

### 1. Use Channel IDs, Not Names

Bot tokens require channel IDs (e.g., `C0ACZKTDDC0`), not names:

```bash
# Get channel ID first
CHANNELS=$(agent-slackbot channel list)
CHANNEL_ID=$(echo "$CHANNELS" | jq -r '.[] | select(.name=="general") | .id')
agent-slackbot message send "$CHANNEL_ID" "Hello"
```

### 2. Rate Limit Your Requests

```bash
for channel in "${CHANNELS[@]}"; do
  agent-slackbot message send "$channel" "$MESSAGE"
  sleep 1
done
```

### 3. Use Threads for Related Messages

```bash
PARENT_TS=$(agent-slackbot message send "$CHANNEL" "Task started" | jq -r '.ts')
agent-slackbot message send "$CHANNEL" "Step 1 done" --thread "$PARENT_TS"
agent-slackbot message send "$CHANNEL" "Step 2 done" --thread "$PARENT_TS"
```

### 4. Handle the "not_in_channel" Error

Bots need to join channels before posting. With the `channels:join` scope, posting to a public channel auto-joins. For private channels, invite the bot from Slack UI.

## See Also

- [Authentication Guide](authentication.md) - Setting up bot tokens
- [Templates](../templates/) - Runnable example scripts

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "devxoul",
  "slug": "agent-slackbot",
  "displayName": "Agent Slackbot",
  "latest": {
    "version": "1.10.5",
    "publishedAt": 1772811621577,
    "commit": "https://github.com/openclaw/skills/commit/ddb76c08dbcb29efe9c60f58d99ce17ff1004935"
  },
  "history": [
    {
      "version": "1.8.1",
      "publishedAt": 1772601726049,
      "commit": "https://github.com/openclaw/skills/commit/7614f1f75df09056690c55a011e783a5fe926c9c"
    }
  ]
}

```