slack-bot

What this skill does

# Slack Bot

Send messages and rich content to Slack channels using Incoming Webhooks or the Slack Web API.
Build formatted announcements, marketing reports, metrics dashboards, and community updates
with Block Kit.

## Prerequisites

Requires either `SLACK_WEBHOOK_URL` or `SLACK_BOT_TOKEN` set in `.env`, `.env.local`, or
`~/.claude/.env.global`.

```bash
source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

if [ -n "$SLACK_WEBHOOK_URL" ]; then
  echo "SLACK_WEBHOOK_URL is set. Webhook mode available."
elif [ -n "$SLACK_BOT_TOKEN" ]; then
  echo "SLACK_BOT_TOKEN is set. Web API mode available."
else
  echo "Neither SLACK_WEBHOOK_URL nor SLACK_BOT_TOKEN is set."
  echo "See the Setup Guide below to configure Slack credentials."
fi
```

If neither variable is set, instruct the user to follow the Setup Guide section below.

---

## Setup Guide

### Option A: Incoming Webhook (Simple)

Incoming Webhooks are the fastest way to post messages. They require no OAuth scopes and are
scoped to a single channel.

1. Go to https://api.slack.com/apps and click **Create New App** > **From scratch**.
2. Name the app (e.g., "Marketing Bot") and select your workspace.
3. In the left sidebar, click **Incoming Webhooks** and toggle it **On**.
4. Click **Add New Webhook to Workspace** at the bottom.
5. Select the channel to post to and click **Allow**.
6. Copy the Webhook URL (starts with `https://hooks.slack.com/services/...`).
7. Add it to your environment:

```bash
echo 'SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxxx' >> .env
```

**Limitations:** One webhook per channel. Cannot read messages, list channels, or reply to
threads programmatically (you must know the `thread_ts` from a prior API response).

### Option B: Bot Token (Full Featured)

Bot tokens give access to the full Slack Web API: post to any channel the bot is in, reply to
threads, list channels, upload files, and more.

1. Go to https://api.slack.com/apps and click **Create New App** > **From scratch**.
2. Name the app and select your workspace.
3. In the left sidebar, click **OAuth & Permissions**.
4. Under **Bot Token Scopes**, add these scopes:
   - `chat:write` - Post messages
   - `chat:write.public` - Post to channels without joining
   - `channels:read` - List public channels
   - `files:write` - Upload files (optional, for images/reports)
   - `reactions:write` - Add emoji reactions (optional)
5. Click **Install to Workspace** at the top and authorize.
6. Copy the **Bot User OAuth Token** (starts with `xoxb-`).
7. Add it to your environment:

```bash
echo 'SLACK_BOT_TOKEN=xoxb-your-token-here' >> .env
```

8. Invite the bot to the channels it should post in: type `/invite @YourBotName` in each channel.

**Optional:** Set a default channel for convenience:

```bash
echo 'SLACK_DEFAULT_CHANNEL=#marketing' >> .env
```

---

## Method 1: Incoming Webhooks

### Send a Simple Text Message

```bash
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from the marketing bot!"
  }'
```

### Send a Message with Username and Icon Override

```bash
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "New blog post published!",
    "username": "Marketing Bot",
    "icon_emoji": ":mega:"
  }'
```

### Send a Message with Block Kit (Webhook)

```bash
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [
      {
        "type": "header",
        "text": {
          "type": "plain_text",
          "text": "New Product Launch"
        }
      },
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "*Product X* is now live! Check out the announcement."
        }
      },
      {
        "type": "divider"
      },
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Read the full announcement on our blog."
        },
        "accessory": {
          "type": "button",
          "text": {
            "type": "plain_text",
            "text": "Read More"
          },
          "url": "https://example.com/blog/launch"
        }
      }
    ]
  }'
```

---

## Method 2: Slack Web API (Bot Token)

The Web API provides full control over message delivery, threading, channel management, and more.

### API Base

All requests go to `https://slack.com/api/` with the header `Authorization: Bearer {SLACK_BOT_TOKEN}`.

### Post a Message to a Channel

```bash
curl -s -X POST "https://slack.com/api/chat.postMessage" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "#marketing",
    "text": "Weekly metrics report is ready!",
    "blocks": [
      {
        "type": "header",
        "text": {
          "type": "plain_text",
          "text": "Weekly Marketing Metrics"
        }
      },
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Here are the numbers for this week."
        }
      }
    ]
  }'
```

The response includes a `ts` (timestamp) field which identifies the message. Save this value
for threading replies:

```bash
# Post and capture the message timestamp for threading
RESPONSE=$(curl -s -X POST "https://slack.com/api/chat.postMessage" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "#marketing",
    "text": "Thread parent message"
  }')

MESSAGE_TS=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin).get('ts',''))")
echo "Message timestamp: $MESSAGE_TS"
```

### Reply to a Thread

Use the `thread_ts` parameter to reply inside an existing thread:

```bash
curl -s -X POST "https://slack.com/api/chat.postMessage" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"channel\": \"#marketing\",
    \"thread_ts\": \"${MESSAGE_TS}\",
    \"text\": \"This is a threaded reply with additional details.\"
  }"
```

To also broadcast the reply to the channel (so it appears in the main conversation as well),
add `"reply_broadcast": true`.

### Update an Existing Message

```bash
curl -s -X POST "https://slack.com/api/chat.update" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"channel\": \"#marketing\",
    \"ts\": \"${MESSAGE_TS}\",
    \"text\": \"Updated message content.\",
    \"blocks\": []
  }"
```

### Delete a Message

```bash
curl -s -X POST "https://slack.com/api/chat.delete" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"channel\": \"#marketing\",
    \"ts\": \"${MESSAGE_TS}\"
  }"
```

### List Public Channels

Useful for discovering which channel to post to:

```bash
curl -s "https://slack.com/api/conversations.list?types=public_channel&limit=100" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
for ch in data.get('channels', []):
    members = ch.get('num_members', 0)
    print(f\"#{ch['name']}  |  Members: {members}  |  ID: {ch['id']}\")
"
```

### Upload a File to a Channel

```bash
curl -s -X POST "https://slack.com/api/files.uploadV2" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -F "[email protected]" \
  -F "filename=weekly-report.pdf" \
  -F "channel_id=C0123456789" \
  -F "initial_comment=Here is this week's marketing report."
```

### Add an Emoji Reaction

```bash
curl -s -X POST "https://slack.com/api/reactions.add" \
  -H "Authorization: Bearer ${SLACK_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"channel\": \"C0123456789\",
    \"timestamp\": \"${MESSAGE_TS}\",
    \"name\": \"white_check_mark\"
  }"
```

---

## Slack Block Kit Reference

Block Kit is Slack's UI framework for building rich, interactive messages. Messages are composed
of an array