Slack

---
name: slack
description: 'Interact with Slack — read channels, search messages, check unreads, send messages, manage reactions, and look up users. Use this skill whenever the user mentions Slack, wants to read Slack messages, check unread channels, search Slack conversations, send a Slack message, add reactions, or look up Slack users. Also trigger when the user pastes a Slack message URL, mentions a Slack channel (#channel), or asks about Slack notifications.'
---

# Slack

Read channels, search messages, check unreads, send messages, manage reactions, and look up users via Slack.

## Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip this step.

```bash
sig status app-slack 2>&1
```

Check the JSON output fields `configured` and `valid`:

- **`configured: false`** → run Provider Setup below. Do NOT proceed without completing it.
- **`valid: false` (but configured: true)** → run `sig login app-slack`, then re-check.
- **`valid: true`** → detect proxy (see below), then execute the user's request.

### Provider Setup

1. Read `<SKILL_DIR>/references/provider-config.yaml`
2. Append the provider block to `~/.sig/config.yaml` under `providers:`
3. Ask the user: "Do you need a proxy to access this site?" — if yes, add `networkProxy: <url>` under the provider in config.yaml
4. Run `sig login app-slack` (with `--network-proxy <url>` if proxy was specified)
5. Verify: run `sig status app-slack` again — must show `valid: true` before proceeding

### Proxy Detection (after provider is valid)

```bash
grep -A15 "^\s*app-slack:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}'
```

If this outputs a URL, prefix ALL python3 commands with `HTTPS_PROXY=<url> HTTP_PROXY=<url>`.
If using socks5, convert to socks5h for python (e.g. `socks5://...` → `socks5h://...`).
If empty, no proxy needed.

## Running Scripts

All scripts require setup to be completed first (see above).

## Scripts Reference

All scripts are in this skill's `scripts/` directory. Run via Bash tool.

| Script               | Purpose                             |
| -------------------- | ----------------------------------- |
| `slack_channels.py`  | List/filter channels                |
| `slack_history.py`   | Get channel/DM message history      |
| `slack_threads.py`   | Get thread replies                  |
| `slack_search.py`    | Search messages with filters        |
| `slack_send.py`      | Send message or threaded reply      |
| `slack_unreads.py`   | Get unread messages across channels |
| `slack_users.py`     | Search users by name/email          |
| `slack_reactions.py` | Add or remove emoji reactions       |

### slack_channels.py

```
--type TYPE           Channel types: public_channel,private_channel,im,mpim (default: public_channel,private_channel)
--sort SORT           Sort by: popularity
--limit N             Max channels (default: 100)
--cursor CURSOR       Pagination cursor from previous response
```

### slack_history.py

```
--channel ID          Channel ID (#name or @user also work) (required)
--limit LIMIT         Time range (1d, 7d, 30d) or message count (50) (default: 1d)
--cursor CURSOR       Pagination cursor
--include-activity    Include join/leave activity messages
```

### slack_threads.py

```
--channel ID          Channel ID or #name (required)
--thread-ts TS        Thread parent timestamp (required)
--limit LIMIT         Time range or count (default: 1d)
--cursor CURSOR       Pagination cursor
```

### slack_search.py

```
--query TEXT          Search query (optional if other filters provided)
--channel ID          Filter to channel
--from USER           Filter by sender (user ID or @name)
--before DATE         Before date (YYYY-MM-DD)
--after DATE          After date (YYYY-MM-DD)
--on DATE             On specific date
--threads-only        Only thread messages
--limit N             Max results (default: 20)
--cursor CURSOR       Pagination cursor
```

### slack_send.py

```
--channel ID          Channel ID, #name, or @user (required)
--message TEXT        Message content (required)
--thread-ts TS        Reply to thread (optional)
--format FORMAT       text/markdown (default) or text/plain
```

### slack_unreads.py

```
--type TYPE           Filter: all, dm, group_dm, partner, internal (default: all)
--max-channels N      Max channels to check (default: 50)
--max-messages N      Max messages per channel (default: 10)
--mentions-only       Only channels with @mentions
--summary-only        Channel list without messages
```

### slack_users.py

```
--query TEXT          Search by name, email, or display name (required)
--limit N             Max results (default: 10)
```

### slack_reactions.py

```
--action ACTION       "add" or "remove" (required)
--channel ID          Channel ID (required)
--timestamp TS        Message timestamp 1234567890.123456 (required)
--emoji NAME          Emoji name without colons, e.g. thumbsup (required)
```

## Key Concepts

**Channel IDs** — Format `Cxxxxxxxxxx`, but scripts also accept `#channel-name` or `@username` for convenience.

**Thread timestamps** — Format `1234567890.123456`. Used to identify specific messages and as parent references for threaded replies.

**Pagination** — All list endpoints use cursor-based pagination. Pass the `--cursor` value from the previous response to get the next page.

**Team ID** — Some edge APIs require your Slack team ID. To find it: open Slack in a browser, go to `<your-workspace>.slack.com`, open DevTools → Network, and look for requests with `team_id` in the response. Alternatively, run `sig run app-slack -- bash -c 'python -c "import scripts.slack_client as c; import json; client = c.SlackClient.create(); print(client.team_id)"'`.

## Error Handling

| Error               | Cause                    | Fix                                                           |
| ------------------- | ------------------------ | ------------------------------------------------------------- |
| Auth error / 401    | Session expired          | Auto-run `sig login app-slack` (no user prompt needed), retry |
| `invalid_auth`      | xoxc/xoxd tokens invalid | Auto-run `sig login app-slack` (no user prompt needed), retry |
| `channel_not_found` | Invalid channel ID/name  | Check channel exists, use `slack_channels.py` to find it      |
| `not_in_channel`    | Not a member of channel  | Join the channel first                                        |

## Workflow Examples

### Check unread messages

1. `sig run app-slack -- python scripts/slack_unreads.py`
2. To see only DMs: `sig run app-slack -- python scripts/slack_unreads.py --type dm`
3. To see only @mentions: `sig run app-slack -- python scripts/slack_unreads.py --mentions-only`

### Search for messages about a topic

1. `sig run app-slack -- bash -c 'python scripts/slack_search.py --query "deployment issue"'`
2. Filter to a channel: `sig run app-slack -- bash -c 'python scripts/slack_search.py --query "deployment" --channel #ops'`
3. Filter by date: `sig run app-slack -- bash -c 'python scripts/slack_search.py --query "deployment" --after 2025-01-01 --before 2025-01-31'`

### Read recent channel history

1. Find the channel: `sig run app-slack -- python scripts/slack_channels.py --limit 20`
2. Get messages: `sig run app-slack -- bash -c 'python scripts/slack_history.py --channel #general --limit 1d'`
3. Read a thread: `sig run app-slack -- bash -c 'python scripts/slack_threads.py --channel #general --thread-ts 1234567890.123456'`

### Send a message to someone

1. Find their DM: `sig run app-slack -- python scripts/slack_channels.py --type im`
2. Or send directly: `sig run app-slack -- bash -c 'python scripts/slack_send.py --channel @john.smith --message "Hello!"'`
3. Reply in a thread: `sig run app-slack -- bash -c 'python scripts/slack_send.py --channel #project --thread-ts 1234567890.123456 --message "Thanks!"'`

### React to a message

1. Get channel history to find the message timestamp: `sig run app-slack -- bash -c 'python scripts/slack_history.py --channel #general --limit 10'`
2. Add a reaction: `sig run app-slack -- bash -c 'python scripts/slack_reactions.py --action add --channel C0123456789 --timestamp 1234567890.123456 --emoji thumbsup'`
3. Remove a reaction: `sig run app-slack -- bash -c 'python scripts/slack_reactions.py --action remove --channel C0123456789 --timestamp 1234567890.123456 --emoji thumbsup'`