{"name":"slack-api","url":"https://skills.sh/slackapi/slack-skills-plugin/slack-api","install":"npx skills add slackapi/slack-skills-plugin","sdk":"slack","key":"slack/slack-api","description":"Discover, navigate, and call Slack Web API methods (the family.method endpoints at slack.com/api like chat.postMessage, conversations.history, users.info, views.open). Use this skill whenever the developer asks which Slack API method does something, needs a method's required OAuth scopes or token type, wants to call or test a Web API method, is handling cursor pagination (next_cursor), hitting rate limits (tier/ratelimited/Retry-After), or debugging API errors like missing_scope, invalid_auth, or channel_not_found. Also trigger when they paste a slack.com/api/ URL or a docs.slack.dev/reference/methods link, or ask how to list/fetch/post/update Slack resources via the API. This skill covers the Web API method layer: finding the right method, reading its contract (scopes, arguments, errors), and calling it over raw HTTP with curl or through a Slack SDK.","hasContent":true,"content":"---\nname: slack-api\ndescription: \"Discover, navigate, and call Slack Web API methods (the family.method endpoints at slack.com/api like chat.postMessage, conversations.history, users.info, views.open). Use this skill whenever the developer asks which Slack API method does something, needs a method's required OAuth scopes or token type, wants to call or test a Web API method, is handling cursor pagination (next_cursor), hitting rate limits (tier/ratelimited/Retry-After), or debugging API errors like missing_scope, invalid_auth, or channel_not_found. Also trigger when they paste a slack.com/api/ URL or a docs.slack.dev/reference/methods link, or ask how to list/fetch/post/update Slack resources via the API. This skill covers the Web API method layer: finding the right method, reading its contract (scopes, arguments, errors), and calling it over raw HTTP with curl or through a Slack SDK.\"\nargument-hint: \"[method.name | family]\"\n---\n\n# Slack Web API\n\nHelp the developer **discover** the right Web API method, **read its contract**, and **call** it correctly. Slack exposes hundreds of methods named in `family.method` dot notation (e.g. `chat.postMessage`, `conversations.history`) at `https://slack.com/api/<method>`. Every method's doc page follows a fixed URL pattern, so the contract for any method is always one fetch away.\n\nIf `$0` is provided, it is either a full `method.name` (jump to Step 2 to read its contract) or a `family` name (go to Step 1 and find it in the index).\n\n> **Critical rules:**\n>\n> - Verify a method name and its required scopes against its doc page **before** calling it — never invent method names or guess scopes. Method names use `family.method` dot notation.\n> - Every response has a top-level `ok` boolean. **Always check `ok`** before using the result; on `ok: false`, read the `error` string.\n> - Method names, scopes, rate tiers, and arguments come from the **live doc page** (`https://docs.slack.dev/reference/methods/<method-lowercased>.md`). The docs are the source of truth — discover from the live index, read the contract from the method's own page.\n\n> **DO NOT rules:**\n>\n> - DO NOT assume a method is GET — many are POST. Check the doc page.\n> - DO NOT hardcode bearer tokens into committed code or share them in plain text.\n> - DO NOT use deprecated methods (`files.upload`, `dialog.open`, `rtm.*`, `oauth.access`, `search.*`, `stars.*`, `reminders.*`) without checking the replacement — a deprecated method's own doc page names what supersedes it; prefer the replacement for new apps.\n> - DO NOT paginate by incrementing a page number — Slack uses opaque cursors (see Step 5).\n\n> **Execution posture — run reads, confirm writes:**\n>\n> - **Read-only methods** (`*.list`, `*.info`, `*.history`, `conversations.members`, `auth.test`, etc.) may be run directly to help the developer.\n> - **State-changing or destructive methods** (`chat.postMessage`/`update`/`delete`, any `*.delete`/`*.remove`/`*.kick`/`*.archive`, and all `admin.*`) — prepare the exact command and **confirm with the developer before running it**.\n\n---\n\n## Fast Path (for clear, specific requests)\n\nIf the developer already knows the method — they named it, pasted a `https://slack.com/api/<method>` URL or a `docs.slack.dev/reference/methods/<method>` link, or gave a `family.method` — skip discovery:\n\n1. Go to **Step 2** to read the method's contract.\n2. Go to **Step 4** to call it (honoring the execution posture above).\n\n**Full-workflow indicators** (start at Step 1):\n\n- \"Which method does X?\" / \"How do I list/fetch/post … via the API?\"\n- The capability is known but the method name is not.\n- Exploratory questions about what the API can do.\n\n---\n\n## Step 1: Identify the Method (Discover)\n\nMap the developer's intent to a family, then to a candidate method.\n\n### Browsing the index\n\nWebFetch the live method index:\n\n```text\nhttps://docs.slack.dev/reference/methods.md\n```\n\nIt lists every Web API method in `family.method` notation with a one-line description and a link to that method's own doc page. It is complete and always current — scan it for a candidate, then follow the method's link into Step 2 to read the contract (the index has descriptions only; rate tier, scopes, token type, and pagination all live on the per-method page).\n\nNever publish or call a method name you have not seen on a live page.\n\n### Searching the docs\n\nWhen you would rather search by keyword than scan the index, and the Slack CLI is available, use the `slack:slack-cli` skill — **Step 3: Searching Documentation (`slack docs search`)** — to query Slack's docs from the terminal. That step covers the command and flags; results will point you to the method's reference page, which you then read in Step 2. Without the CLI, WebFetch the index (`https://docs.slack.dev/reference/methods.md`) and scan it instead.\n\n---\n\n## Step 2: Read the Method Contract (Navigate)\n\nFetch the method's doc page with WebFetch. Either follow the method's link from the index (Step 1) or construct the URL — the path segment is **all-lowercase** and ends in `.md`:\n\n```text\nhttps://docs.slack.dev/reference/methods/<method-lowercased>.md\n```\n\nFor example, `conversations.members` → `https://docs.slack.dev/reference/methods/conversations.members.md`, and `chat.postMessage` → `https://docs.slack.dev/reference/methods/chat.postmessage.md`. When in doubt about casing, follow the index link rather than building the URL by hand.\n\nEvery method page documents, consistently:\n\n- **HTTP method** (GET / POST) and the endpoint `https://slack.com/api/<method>`\n- **Required OAuth scopes** and the **token type** (bot `xoxb-` vs user `xoxp-`)\n- **Arguments** — required vs optional, with types\n- An **example request and response**\n- An **errors table** (method-specific codes)\n- The **rate-limit tier**\n\nExtract the **required arguments** and **required scopes** before calling. For what these cross-cutting concepts _mean_ in general — beyond what the method page states — the canonical references are: the response envelope, POST bodies, and auth at `https://docs.slack.dev/apis/web-api.md`; pagination at `https://docs.slack.dev/apis/web-api/pagination.md`; and rate-limit tiers at `https://docs.slack.dev/apis/web-api/rate-limits.md`.\n\n---\n\n## Step 3: Authenticate and Scope\n\nCalling any non-public method requires a token with the right scopes and type. This skill's job here is to determine, from the contract you read in Step 2, **which token type and scopes** the method needs — independent of how you ultimately send the token.\n\nFrom the contract you read in Step 2:\n\n- Confirm the **token type** — a bot token cannot call a user-only method (the method's doc page states which token types it accepts), and vice versa. For what each token prefix (`xoxb-`, `xoxp-`, `xapp-`) is and when to use it, see `https://docs.slack.dev/authentication/tokens.md`.\n- Note the **required scopes**. If a call later fails with `missing_scope`, the response's `needed` and `provided` fields name the gap — add the `needed` scope to the app manifest and reinstall the app.\n- `admin.*` methods require an Enterprise Grid **org-level** token.\n\nA couple of methods need no auth: `api.test` (connectivity), `auth.test` (validates whatever token you do send) and `blocks.validate`.\n\nYou need a token only when the method requires one. There are two ways to get one — pick whichever fits the developer's setup. **The Slack CLI is optional**: if the developer does not have it and prefers not to install it, take Path B rather than forcing an install.\n\n### Path A: Use the Slack CLI (if installed or wanted)\n\nThe CLI supplies an authenticated session, so once the developer is logged in you can call methods without handling a token yourself (Step 4, \"Via the Slack CLI\").\n\nUse the `slack:slack-cli` skill — **Step 1: Detect the Slack CLI** — to check whether the public Slack CLI is installed and resolve its command name. That step also proposes installing the CLI when it is absent. The fingerprint check, alias fallback, and install instructions all live there; do not duplicate them here.\n\nOnce resolved, use the detected command name for **all** CLI commands in this skill. We refer to it as `SLACK_CMD` — substitute the actual resolved command name everywhere you see `SLACK_CMD`.\n\nUse the `slack:slack-cli` skill — **Step 5: Authentication (`slack auth`)** — to check the developer's login state and, if needed, walk them through `slack login`. Authentication mechanics live there.\n\n### Path B: No CLI — bring your own token\n\nYou do not need the CLI to call a method. Get a token of the type you determined above from the app's **OAuth & Permissions** page in the Slack app config (`https://api.slack.com/apps` → your app → **OAuth & Permissions** → **OAuth Tokens**): the **Bot User OAuth Token** (`xoxb-…`) or the **User OAuth Token** (`xoxp-…`). That page also lists the scopes currently granted — confirm the ones from Step 2 are present. Then send that token with curl or an SDK in Step 4 (\"Via raw HTTP\" / \"Via an SDK\").\n\n---\n\n## Step 4: Call the Method (Manage)\n\nFirst apply the **execution posture**: if the method changes state (post/update/delete/archive/kick, or any `admin.*`), show the developer the exact command and get a yes before running it. Read-only calls can be run directly.\n\n### Via the Slack CLI (if installed)\n\nTo call a method from the terminal, use the `slack:slack-cli` skill — **Step 4: Calling Web API Methods (`slack api`)**. That step covers the `SLACK_CMD api <method> key=value …` syntax so that it is not repeated here. Pass the required arguments you gathered from the method's doc page in Step 2.\n\nThe CLI uses the developer's authenticated session, so it is the simplest path once they are logged in (Step 3).\n\n### Via raw HTTP (curl)\n\nUse the **Bash tool** when the developer wants a raw request or isn't using the CLI. Send the token in the `Authorization` header — the bot or user token from Step 3 (Path B, or the CLI session).\n\n**Form-encoded** (the default for most methods):\n\n```bash\ncurl -s -X POST 'https://slack.com/api/conversations.list' \\\n  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \\\n  -d 'types=public_channel&limit=200'\n```\n\n**JSON body** (for methods taking complex arguments like `blocks`, `view`, `attachments`, `metadata`):\n\n```bash\ncurl -s -X POST 'https://slack.com/api/chat.postMessage' \\\n  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"channel\":\"C0123456789\",\"text\":\"Hello from the API\"}'\n```\n\nCheck the method's page for which content type it expects. With form encoding, a structured argument is passed as a JSON-encoded string value (e.g. `blocks=[...]`).\n\n### Via an SDK\n\nIn Bolt and the Slack SDKs, each method is a client function whose arguments match the doc page's argument table:\n\n- **JavaScript:** `await client.chat.postMessage({ channel, text, blocks })`\n- **Python:** `client.chat_postMessage(channel=channel, text=text, blocks=blocks)`\n\n(Note the JS dot form `chat.postMessage` vs the Python underscore form `chat_postMessage`.) To construct the `blocks`/`view` payload these calls take, use the `slack:block-kit` skill — this skill treats that payload as an opaque argument and focuses on the method call around it.\n\n---\n\n## Step 5: Handle Pagination\n\nMethods that return collections use **cursor pagination**, not page numbers. A method's doc page states whether it paginates, and the full list of cursor-paginated methods is under _Methods supporting cursor-based pagination_ at `https://docs.slack.dev/apis/web-api/pagination.md`:\n\n1. Call with a `limit` (page size — check the method's max).\n2. Read `response_metadata.next_cursor` from the response.\n3. If it is **non-empty**, call again with `cursor=<next_cursor>`.\n4. Repeat until `next_cursor` comes back empty.\n\n```bash\n# First page\ncurl -s -X POST 'https://slack.com/api/conversations.history' \\\n  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \\\n  -d 'channel=C0123456789&limit=200'\n\n# Next page — pass the cursor from response_metadata.next_cursor\ncurl -s -X POST 'https://slack.com/api/conversations.history' \\\n  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \\\n  -d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI='\n```\n\nCursors are opaque — never construct, parse, or reuse an old one.\n\n---\n\n## Step 6: Handle Rate Limits and Errors\n\nWhen `ok` is `false`, branch on the `error` string:\n\n- For method-specific codes, read the **errors table** on the method's doc page (Step 2) — it lists every error that method returns, including cross-cutting ones like `not_authed`, `invalid_auth`, `missing_scope`, `channel_not_found`, and `invalid_arguments`.\n- For what the envelope itself means (`ok`, `error`, `warning`, `response_metadata`), see _Evaluating responses_ at `https://docs.slack.dev/apis/web-api.md`.\n- `response_metadata.messages` often pinpoints a malformed argument.\n\n**Rate limits:** on HTTP `429` / `error: \"ratelimited\"`, honor the `Retry-After` response header (seconds) — wait, then retry. Do not retry in a tight loop. Each method's tier (1–4 or special) caps calls per minute; the tier table is at `https://docs.slack.dev/apis/web-api/rate-limits.md`, and newer non-Marketplace apps face stricter caps on some methods, so trust the method's own page for the exact number.\n\n---\n\n## Notes\n\n- **Slack Lists** methods use the `slackLists.*` prefix — a bare `lists.*` name does not exist.\n- **Scope:** this skill owns the method layer — which method, its contract, and the call around it. CLI auth and calls are delegated to `slack:slack-cli`; Block Kit payloads to `slack:block-kit`.\n","contentSource":"https://raw.githubusercontent.com/slackapi/slack-skills-plugin/main/skills/slack-api/SKILL.md","contentFetchedAt":"2026-07-27T09:00:54.187Z"}