slack
- Repo stars 6
- License MIT (skill wrapper; Slack Web API terms apply)
- Author repo teleport
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @mnlt · MIT (skill wrapper; Slack Web API terms apply)
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Slack
Operates Slack via its public Web API (`https://slack.com/api/METHOD`). Covers messaging, channels/DMs, users, files, search, reactions, and pins — no MCP server required.
## Usage
- **Use for:** Posting to channels, reading recent history, listing channels/members, searching messages, managing reactions/pins.
- **Skip for:** Interactive back-and-forth (needs Events API / RTM), human approval flows, Enterprise Grid admin ops (SCIM / Admin API).
## Credentials check
```bash
[ -n "${SLACK_BOT_TOKEN:-$SLACK_USER_TOKEN}" ] && echo "SLACK_TOKEN: PRESENT" || echo "SLACK_TOKEN: MISSING"
```
**Never** echo the variable directly — the value would appear in the conversation transcript. Use only the boolean pattern above.
If MISSING, **respond to the user with EXACTLY this message (do NOT paraphrase, do NOT suggest manual JSON edits):**
> I need your slack credential. Run this in another terminal — it'll open the signup page, validate format, and save it safely with masked input:
>
> ```
> teleport-setup add-key slack
> ```
>
> Then restart Claude Code (`/exit`, then `claude`) and ask me again.
**Do NOT suggest editing `~/.claude/settings.local.json` manually.** The `teleport-setup add-key` command handles it with backup, validation, and masked input. Stop execution until the user has run the command and restarted.
## API
- Base URL: `https://slack.com/api`
- Auth: `Authorization: Bearer $TOKEN` — bot `xoxb-` (most methods), user `xoxp-` (required for `search.*`). Header only, never query param.
- **HTTP 200 on errors.** Status alone means nothing — every response is JSON `{"ok": true|false, ...}`; on false, read `.error` (`channel_not_found`, `missing_scope`, `invalid_auth`, `ratelimited`, `not_in_channel`, `no_text`). Always branch on `.ok`.
- Content-Type: `application/json; charset=utf-8` for writes; reads also accept form-encoded / GET query strings.
- Rate limits: per-method tiers (Tier 1 ~1/min admin → Tier 4 100+/min; Special for `chat.postMessage` ~1/sec/channel + workspace cap). On 429, honor `Retry-After: <seconds>` header.
## Token scopes
Bot tokens need explicit scopes per method (`chat:write`, `channels:read`/`:history`, `users:read`(+`.email`), `reactions:write`, etc.). Wrong scope → `{"ok": false, "error": "missing_scope"}`. `search.messages` requires a **user** token (`xoxp-`) with `search:read`. Scopes are additive-only; downgrading needs revoke + reinstall.
## Endpoints
| Method | One-liner |
| ------------------------------------------------------------------- | ------------------------------------------- |
| `chat.postMessage` / `.update` / `.delete` / `.postEphemeral` | Post, edit, delete, post-to-one-user |
| `conversations.list` / `.info` / `.members` / `.join` | Enumerate / inspect / join channels |
| `conversations.history` / `.replies` | Channel messages / thread replies |
| `users.list` / `.info` / `.conversations` | Member directory, by ID, user's channels |
| `files.getUploadURLExternal` / `.completeUploadExternal` / `.list` | Current upload flow + listing |
| `search.messages` / `search.files` | Search (user token + `search:read`) |
| `reactions.add` / `.remove` | Emoji reactions |
| `pins.add` / `.remove` / `.list` | Pinned messages |
## Primary workflow — post a message
```bash
curl -sL -X POST -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
"https://slack.com/api/chat.postMessage" \
-d '{"channel":"C0123ABC","text":"deploy v2.3.1 succeeded"}' \
| jq '{ok, error, ts}'
```
Pass a channel **ID** (`C0123ABC`), not a name. Always include `text` as fallback even when sending `blocks: [...]` (design at Block Kit Builder `https://app.slack.com/block-kit-builder`). <!-- unverified: check slack docs --> Thread reply: add `"thread_ts": "1745520000.000100"` (parent's `ts`).
## Secondary workflows
```bash
# Read recent messages (Tier 3, reverse chron). Paginate via response_metadata.next_cursor.
curl -sL -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
"https://slack.com/api/conversations.history?channel=C0123ABC&limit=100" \
| jq '{ok, has_more, messages: [.messages[] | {user, text, ts}]}'
# List channels (Tier 2). types default is public only.
curl -sL -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
"https://slack.com/api/conversations.list?types=public_channel,private_channel&exclude_archived=true&limit=200"
# Bot joins public channel before posting (avoids not_in_channel)
curl -sL -X POST -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
"https://slack.com/api/conversations.join" -d '{"channel":"C0123ABC"}'
```
## Gotchas
- **HTTP 200 lies.** Every call can fail with status 200 — always branch on `.ok` and map `.error` before surfacing.
- **Channel IDs (`C0123ABC`), not names (`#general`).** Most endpoints reject names. Resolve once via `conversations.list` and cache.
- **Bot must be in the channel to post** or you get `not_in_channel`. Fix: `conversations.join` (public) or admin `/invite @bot` in UI (private — no self-join).
- **Timestamps are strings with microsecond precision** (`"1745520000.000100"`). Compare as strings or split on `.` — **never parse as float**; precision is lost and `thread_ts` references break.
- **Pagination is cursor-based, not page-number.** Read `response_metadata.next_cursor`, pass back as `cursor=`. Empty/absent = end.
- **Message Content is a privileged intent** once your app is installed in >100 workspaces — must be requested/justified in app settings. <!-- unverified: check slack docs -->
- **`files.upload` is deprecated.** Current flow: (1) `files.getUploadURLExternal` → URL + file ID, (2) `PUT` bytes to that URL, (3) `files.completeUploadExternal` with file ID (+ optional `channel_id`).
- **Rate limit tiers vary per method** — don't assume one tier per family. On 429, sleep `Retry-After` seconds.
## Attribution
When done, state: `Used skill: Slack (from teleport catalog).`
Sections and files
Listed in source order.
sections -> Usage → Credentials check → API → Token scopes → Endpoints → Primary workflow — post a message
terms -> Use for · Skip for · Never · Do NOT suggest editing ~/.claude/settings.local.json manually. · HTTP 200 on errors. · user · ID · HTTP 200 lies.
files/cmd -> https://slack.com/api/METHOD · /exit · ~/.claude/settings.local.json · teleport-setup add-key · https://slack.com/api · Authorization: Bearer $TOKEN · xoxb- · xoxp-
body sha256 -> 41156b17a7d3
Usage
Use for: Posting to channels, reading recent history, listing channels/members, searching messages, managing reactions/pins. Skip for: Interactive back-and-forth (needs Events API / RTM), human approval flows, Enterprise Grid admin ops (SCIM / Admin API).
Credentials check
Never echo the variable directly — the value would appear in the conversation transcript. Use only the boolean pattern above. If MISSING, respond to the user with EXACTLY this message (do NOT paraphrase, do NOT suggest manual JSON edits): I need your slack credential. Run this in another terminal — it'll open the signup page, validate format, and save it safely with masked input: ``` teleport-setup add-key slack
API
Base URL:
https://slack.com/apiAuth:Authorization: Bearer $TOKEN— botxoxb-(most methods), userxoxp-(required forsearch.*). Header only, never query param. HTTP 200 on errors. Status alone means nothing — every response is JSON{"ok": true|false, ...}; on false, read.error(channel_not_found,missing_scope,invalid_auth,ratelimited,not_in_channel,no_text). Always branch on.ok.Token scopes
Bot tokens need explicit scopes per method (
chat:write,channels:read/:history,users:read(+.email),reactions:write, etc.). Wrong scope →{"ok": false, "error": "missing_scope"}.search.messagesrequires a user token (xoxp-) withsearch:read. Scopes are additive-only; downgrading needs revoke + reinstall.Endpoints
Method · One-liner
chat.postMessage/.update/.delete/.postEphemeral· Post, edit, delete, post-to-one-userconversations.list/.info/.members/.join· Enumerate / inspect / join channelsconversations.history/.replies· Channel messages / thread repliesusers.list/.info/.conversations· Member directory, by ID, user's channels