Slack Web API
Help the developer
discover the right Web API method,
read its contract, and
call it correctly. Slack exposes hundreds of methods named in
dot notation (e.g.
,
) 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.
If
is provided, it is either a full
(jump to Step 2 to read its contract) or a
name (go to Step 1 and find it in the index).
Critical rules:
- 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 dot notation.
- Every response has a top-level boolean. Always check before using the result; on , read the string.
- Method names, scopes, rate tiers, and arguments come from the live doc page (
https://docs.slack.dev/reference/methods/<method-lowercased>.md
DO NOT rules:
- DO NOT assume a method is GET — many are POST. Check the doc page.
- DO NOT hardcode bearer tokens into committed code or share them in plain text.
- DO NOT use deprecated methods (, , , , , , ) without checking the replacement — a deprecated method's own doc page names what supersedes it; prefer the replacement for new apps.
- DO NOT paginate by incrementing a page number — Slack uses opaque cursors (see Step 5).
Execution posture — run reads, confirm writes:
- Read-only methods (, , , , , etc.) may be run directly to help the developer.
- State-changing or destructive methods (//, any ///, and all ) — prepare the exact command and confirm with the developer before running it.
Fast Path (for clear, specific requests)
If 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
— skip discovery:
- Go to Step 2 to read the method's contract.
- Go to Step 4 to call it (honoring the execution posture above).
Full-workflow indicators (start at Step 1):
- "Which method does X?" / "How do I list/fetch/post … via the API?"
- The capability is known but the method name is not.
- Exploratory questions about what the API can do.
Step 1: Identify the Method (Discover)
Map the developer's intent to a family, then to a candidate method.
Browsing the index
WebFetch the live method index:
text
https://docs.slack.dev/reference/methods.md
It lists every Web API method in
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).
Never publish or call a method name you have not seen on a live page.
Searching the docs
When you would rather search by keyword than scan the index, and the Slack CLI is available, use the
skill —
Step 3: Searching Documentation () — 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.
Step 2: Read the Method Contract (Navigate)
Fetch 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
:
text
https://docs.slack.dev/reference/methods/<method-lowercased>.md
For example,
→
https://docs.slack.dev/reference/methods/conversations.members.md
, and
→
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.
Every method page documents, consistently:
- HTTP method (GET / POST) and the endpoint
https://slack.com/api/<method>
- Required OAuth scopes and the token type (bot vs user )
- Arguments — required vs optional, with types
- An example request and response
- An errors table (method-specific codes)
- The rate-limit tier
Extract 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
.
Step 3: Authenticate and Scope
Calling 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.
From the contract you read in Step 2:
- 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 (, , ) is and when to use it, see
https://docs.slack.dev/authentication/tokens.md
- Note the required scopes. If a call later fails with , the response's and fields name the gap — add the scope to the app manifest and reinstall the app.
- methods require an Enterprise Grid org-level token.
A couple of methods need no auth:
(connectivity),
(validates whatever token you do send) and
.
You 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.
Path A: Use the Slack CLI (if installed or wanted)
The 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").
Use the
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.
Once resolved, use the detected command name for
all CLI commands in this skill. We refer to it as
— substitute the actual resolved command name everywhere you see
.
Use the
skill —
Step 5: Authentication () — to check the developer's login state and, if needed, walk them through
. Authentication mechanics live there.
Path B: No CLI — bring your own token
You 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 (
) or the
User OAuth Token (
). 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").
Step 4: Call the Method (Manage)
First apply the
execution posture: if the method changes state (post/update/delete/archive/kick, or any
), show the developer the exact command and get a yes before running it. Read-only calls can be run directly.
Via the Slack CLI (if installed)
To call a method from the terminal, use the
skill —
Step 4: Calling Web API Methods (). 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.
The CLI uses the developer's authenticated session, so it is the simplest path once they are logged in (Step 3).
Via raw HTTP (curl)
Use the
Bash tool when the developer wants a raw request or isn't using the CLI. Send the token in the
header — the bot or user token from Step 3 (Path B, or the CLI session).
Form-encoded (the default for most methods):
bash
curl -s -X POST 'https://slack.com/api/conversations.list' \
-H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
-d 'types=public_channel&limit=200'
JSON body (for methods taking complex arguments like
,
,
,
):
bash
curl -s -X POST 'https://slack.com/api/chat.postMessage' \
-H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
-H 'Content-Type: application/json' \
-d '{"channel":"C0123456789","text":"Hello from the API"}'
Check 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.
).
Via an SDK
In Bolt and the Slack SDKs, each method is a client function whose arguments match the doc page's argument table:
- JavaScript:
await client.chat.postMessage({ channel, text, blocks })
- Python:
client.chat_postMessage(channel=channel, text=text, blocks=blocks)
(Note the JS dot form
vs the Python underscore form
.) To construct the
/
payload these calls take, use the
skill — this skill treats that payload as an opaque argument and focuses on the method call around it.
Step 5: Handle Pagination
Methods 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
:
- Call with a (page size — check the method's max).
- Read
response_metadata.next_cursor
- If it is non-empty, call again with .
- Repeat until comes back empty.
bash
# First page
curl -s -X POST 'https://slack.com/api/conversations.history' \
-H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
-d 'channel=C0123456789&limit=200'
# Next page — pass the cursor from response_metadata.next_cursor
curl -s -X POST 'https://slack.com/api/conversations.history' \
-H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
-d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI='
Cursors are opaque — never construct, parse, or reuse an old one.
Step 6: Handle Rate Limits and Errors
When
is
, branch on the
string:
- 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 , , , , and .
- For what the envelope itself means (, , , ), see Evaluating responses at
https://docs.slack.dev/apis/web-api.md
response_metadata.messages
Rate limits: on HTTP
/
, honor the
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.
Notes
- Slack Lists methods use the prefix — a bare name does not exist.
- Scope: this skill owns the method layer — which method, its contract, and the call around it. CLI auth and calls are delegated to ; Block Kit payloads to .