Back to Details

slack-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Slack Web API

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 
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.
If 
$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).
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 
    family.method
    dot notation.
  • Every response has a top-level 
    ok
    boolean. Always check 
    ok
     before using the result; on 
    ok: false
    , read the 
    error
    string.
  • 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.
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 (
    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.
  • DO NOT paginate by incrementing a page number — Slack uses opaque cursors (see Step 5).
Execution posture — run reads, confirm writes:
  • Read-only methods (
    *.list
    , 
    *.info
    , 
    *.history
    , 
    conversations.members
    , 
    auth.test
    , etc.) may be run directly to help the developer.
  • 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.
帮助开发者发现合适的Web API方法、阅读其约定并正确调用它。Slack公开了数百个以
family.method
点符号命名的方法（例如
chat.postMessage
、
conversations.history
），端点为
https://slack.com/api/<method>
。每个方法的文档页面都遵循固定的URL模式，因此任何方法的约定都可通过一次获取得到。
如果提供了
$0
，它要么是完整的
method.name
（直接跳至步骤2阅读其约定），要么是
family
名称（进入步骤1并在索引中查找）。
关键规则：
  • 在调用方法之前，务必对照其文档页面验证方法名称及其所需的权限范围——切勿自行编造方法名称或猜测权限范围。方法名称采用
    family.method
    点符号格式。
  • 每个响应都包含顶层的
    ok
    布尔值。**务必先检查
    ok
    **再使用结果；当
    ok: false
    时，读取
    error
    字符串。
  • 方法名称、权限范围、速率层级和参数均来自实时文档页面（
    https://docs.slack.dev/reference/methods/<method-lowercased>.md
    ）。文档是唯一的权威来源——从实时索引中查找方法，从方法的专属页面读取约定。
禁止规则：
  • 请勿假设方法为GET请求——许多方法是POST请求。请查阅文档页面。
  • 请勿将Bearer令牌硬编码到已提交的代码中，或以明文形式共享。
  • 请勿使用已弃用的方法（
    files.upload
    、
    dialog.open
    、
    rtm.*
    、
    oauth.access
    、
    search.*
    、
    stars.*
    、
    reminders.*
    ）而不检查替代方案——已弃用方法的文档页面会注明替代方法；对于新应用，优先使用替代方法。
  • 请勿通过递增页码进行分页——Slack使用不透明游标（参见步骤5）。
执行准则——运行读取操作，确认写入操作：
  • 只读方法（
    *.list
    、
    *.info
    、
    *.history
    、
    conversations.members
    、
    auth.test
    等）可直接运行以协助开发者。
  • 更改状态或具有破坏性的方法（
    chat.postMessage
    /
    update
    /
    delete
    、任何
    *.delete
    /
    *.remove
    /
    *.kick
    /
    *.archive
    ，以及所有
    admin.*
    ）——准备好精确的命令，并在运行前征得开发者确认。

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 
family.method
— skip discovery:
  1. Go to Step 2 to read the method's contract.
  2. 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.
如果开发者已明确方法——他们指定了方法名称、粘贴了
https://slack.com/api/<method>
URL或
docs.slack.dev/reference/methods/<method>
链接，或是提供了
family.method
——可跳过发现步骤：
  1. 直接进入步骤2读取方法的约定。
  2. 进入步骤4调用方法（遵循上述执行准则）。
全流程触发条件（从步骤1开始）：
  • “哪个方法可以实现X功能？” / “如何通过API列出/获取/发布……？”
  • 已知功能需求但不知道方法名称。
  • 关于API能力的探索性问题。

Step 1: Identify the Method (Discover)

步骤1：确定方法（发现）

Map the developer's intent to a family, then to a candidate method.
将开发者的需求映射到对应的family，再找到候选方法。

Browsing the index

浏览索引

WebFetch the live method index:
text
https://docs.slack.dev/reference/methods.md
It 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).
Never publish or call a method name you have not seen on a live page.
通过WebFetch获取实时方法索引：
text
https://docs.slack.dev/reference/methods.md
该索引以
family.method
格式列出所有Web API方法，附带一行描述和指向该方法文档页面的链接。索引内容完整且实时更新——从中筛选候选方法，然后点击方法链接进入步骤2阅读约定（索引仅包含描述；速率层级、权限范围、令牌类型和分页信息均在方法专属页面）。
切勿使用或调用未在实时页面中出现的方法名称。

Searching the docs

搜索文档

When 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.
当你更倾向于通过关键词搜索而非扫描索引，且Slack CLI可用时，使用
slack:slack-cli
技能——步骤3：搜索文档（
slack docs search
）——从终端查询Slack文档。该步骤涵盖命令和参数；搜索结果会指向方法的参考页面，随后你可在步骤2中阅读该页面。若没有CLI，可通过WebFetch获取索引（
https://docs.slack.dev/reference/methods.md
）并扫描。

Step 2: Read the Method Contract (Navigate)

步骤2：阅读方法约定（浏览）

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 
.md
:
text
https://docs.slack.dev/reference/methods/<method-lowercased>.md
For 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.
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 
    xoxb-
    vs user 
    xoxp-
    )
  • 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
.
通过WebFetch获取方法的文档页面。可从索引（步骤1）中点击方法链接，或自行构造URL——路径段需全小写并以
.md
结尾：
text
https://docs.slack.dev/reference/methods/<method-lowercased>.md
例如，
conversations.members
对应
https://docs.slack.dev/reference/methods/conversations.members.md
，
chat.postMessage
对应
https://docs.slack.dev/reference/methods/chat.postmessage.md
。若对大小写存疑，请点击索引链接而非手动构造URL。
每个方法页面都会统一记录以下内容：
  • HTTP方法（GET / POST）和端点
    https://slack.com/api/<method>
  • 所需OAuth权限范围和令牌类型（机器人令牌
    xoxb-
    vs 用户令牌
    xoxp-
    ）
  • 参数——必填项与可选项，附带类型
  • 示例请求和响应
  • 错误表（方法专属错误码）
  • 速率限制层级
调用前请提取必填参数和所需权限范围。如需了解这些通用概念的含义（超出方法页面所述内容），权威参考为：响应包体、POST请求体和认证相关内容见
https://docs.slack.dev/apis/web-api.md
；分页相关见
https://docs.slack.dev/apis/web-api/pagination.md
；速率限制层级见
https://docs.slack.dev/apis/web-api/rate-limits.md
。

Step 3: Authenticate and Scope

步骤3：认证与权限范围

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 (
    xoxb-
    , 
    xoxp-
    , 
    xapp-
    ) is and when to use it, see 
    https://docs.slack.dev/authentication/tokens.md
    .
  • 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.
  • admin.*
    methods require an Enterprise Grid org-level token.
A couple of methods need no auth: 
api.test
(connectivity), 
auth.test
(validates whatever token you do send) and 
blocks.validate
.
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.
调用任何非公开方法都需要具备正确权限范围和类型的令牌。本技能在此环节的任务是，根据步骤2中读取的约定，确定方法所需的令牌类型和权限范围——与最终发送令牌的方式无关。
根据步骤2中读取的约定：
  • 确认令牌类型——机器人令牌无法调用仅支持用户令牌的方法（方法文档页面会注明支持的令牌类型），反之亦然。如需了解各令牌前缀（
    xoxb-
    、
    xoxp-
    、
    xapp-
    ）的含义及使用场景，请查阅
    https://docs.slack.dev/authentication/tokens.md
    。
  • 记录所需权限范围。若后续调用因
    missing_scope
    失败，响应中的
    needed
    和
    provided
    字段会指出缺失的权限——将
    needed
    权限添加到应用清单并重新安装应用。
  • admin.*
    方法需要Enterprise Grid组织级令牌。
有几个方法无需认证：
api.test
（连通性测试）、
auth.test
（验证发送的令牌）和
blocks.validate
。
仅当方法需要令牌时才需获取。有两种获取方式——选择适合开发者环境的方式。Slack CLI为可选工具：若开发者未安装且不愿安装，可选择路径B而非强制安装。

Path A: Use the Slack CLI (if installed or wanted)

路径A：使用Slack CLI（若已安装或需要）

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 
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.
Once 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
.
Use 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.
CLI提供已认证的会话，因此开发者登录后，你无需自行处理令牌即可调用方法（步骤4，“通过Slack CLI”）。
使用
slack:slack-cli
技能——步骤1：检测Slack CLI——检查公共Slack CLI是否已安装并确定其命令名称。该步骤还会在CLI未安装时建议安装；指纹检查、别名回退和安装说明均在此步骤，请勿在此处重复。
确定命令名称后，本技能中所有CLI命令均使用该名称。我们将其称为
SLACK_CMD
——请将所有
SLACK_CMD
替换为实际确定的命令名称。
使用
slack:slack-cli
技能——步骤5：认证（
slack auth
）——检查开发者的登录状态，必要时引导他们完成
slack login
。认证机制在此步骤，请勿在此处重复。

Path B: No CLI — bring your own token

路径B：不使用CLI——自行提供令牌

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 (
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").
调用方法无需依赖CLI。从Slack应用配置的OAuth & Permissions页面（
https://api.slack.com/apps
→ 你的应用 → OAuth & Permissions → OAuth Tokens）获取步骤3中确定类型的令牌：Bot User OAuth Token（
xoxb-…
）或User OAuth Token（
xoxp-…
）。该页面还会列出当前已授予的权限范围——请确认步骤2中的所需权限已包含在内。随后在步骤4中通过curl或SDK发送该令牌（“通过原生HTTP” / “通过SDK”）。

Step 4: Call the Method (Manage)

步骤4：调用方法（管理）

First 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.
首先遵循执行准则：若方法会更改状态（post/update/delete/archive/kick，或任何
admin.*
），请向开发者展示精确命令并征得同意后再运行。只读调用可直接运行。

Via the Slack CLI (if installed)

通过Slack CLI（若已安装）

To 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.
The CLI uses the developer's authenticated session, so it is the simplest path once they are logged in (Step 3).
如需从终端调用方法，使用
slack:slack-cli
技能——步骤4：调用Web API方法（
slack api
）。该步骤涵盖
SLACK_CMD api <method> key=value …
语法，此处不再重复。传入步骤2中从方法文档页面收集的必填参数。
CLI使用开发者的已认证会话，因此开发者登录后（步骤3），这是最简单的调用方式。

Via raw HTTP (curl)

通过原生HTTP（curl）

Use 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).
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 
blocks
, 
view
, 
attachments
, 
metadata
):
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. 
blocks=[...]
).
当开发者需要原生请求或未使用CLI时，使用Bash工具。在
Authorization
头中发送令牌——步骤3中获取的机器人或用户令牌（路径B，或CLI会话令牌）。
表单编码（大多数方法的默认方式）：
bash
curl -s -X POST 'https://slack.com/api/conversations.list' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'types=public_channel&limit=200'
JSON请求体（适用于接收复杂参数如
blocks
、
view
、
attachments
、
metadata
的方法）：
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"}'
请查阅方法页面确认其期望的内容类型。使用表单编码时，结构化参数需以JSON编码字符串形式传递（例如
blocks=[...]
）。

Via an SDK

通过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 
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.
在Bolt和Slack SDK中，每个方法都是一个客户端函数，其参数与文档页面的参数表一致：
  • JavaScript： 
    await client.chat.postMessage({ channel, text, blocks })
  • Python： 
    client.chat_postMessage(channel=channel, text=text, blocks=blocks)
（注意JavaScript使用点形式
chat.postMessage
，而Python使用下划线形式
chat_postMessage
。）如需构造这些调用所需的
blocks
/
view
负载，请使用
slack:block-kit
技能——本技能将该负载视为透明参数，专注于方法调用本身。

Step 5: Handle Pagination

步骤5：处理分页

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
:
  1. Call with a 
    limit
    (page size — check the method's max).
  2. Read 
    response_metadata.next_cursor
    from the response.
  3. If it is non-empty, call again with 
    cursor=<next_cursor>
    .
  4. Repeat until 
    next_cursor
    comes back empty.
bash
undefined
返回集合的方法使用游标分页，而非页码。方法文档页面会注明是否支持分页，支持游标分页的方法完整列表见
https://docs.slack.dev/apis/web-api/pagination.md
中的_Methods supporting cursor-based pagination_：
  1. 调用时传入
    limit
    （每页大小——请查阅方法的最大值）。
  2. 从响应中读取
    response_metadata.next_cursor
    。
  3. 若
    next_cursor
    非空，再次调用时传入
    cursor=<next_cursor>
    。
  4. 重复上述步骤，直到
    next_cursor
    为空。
bash
undefined

First page

第一页

curl -s -X POST 'https://slack.com/api/conversations.history'
-H 'Authorization: Bearer xoxb-YOUR-TOKEN'
-d 'channel=C0123456789&limit=200'
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

下一页——传入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.

---
curl -s -X POST 'https://slack.com/api/conversations.history'
-H 'Authorization: Bearer xoxb-YOUR-TOKEN'
-d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI='

游标是不透明的——切勿自行构造、解析或重用旧游标。

---

Step 6: Handle Rate Limits and Errors

步骤6：处理速率限制与错误

When 
ok
is 
false
, branch on the 
error
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 
    not_authed
    , 
    invalid_auth
    , 
    missing_scope
    , 
    channel_not_found
    , and 
    invalid_arguments
    .
  • For what the envelope itself means (
    ok
    , 
    error
    , 
    warning
    , 
    response_metadata
    ), see Evaluating responses at 
    https://docs.slack.dev/apis/web-api.md
    .
  • response_metadata.messages
    often pinpoints a malformed argument.
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.
当
ok
为
false
时，根据
error
字符串进行处理：
  • 对于方法专属错误码，请查阅方法文档页面（步骤2）的错误表——其中列出了该方法可能返回的所有错误，包括通用错误如
    not_authed
    、
    invalid_auth
    、
    missing_scope
    、
    channel_not_found
    和
    invalid_arguments
    。
  • 如需了解响应包体本身的含义（
    ok
    、
    error
    、
    warning
    、
    response_metadata
    ），请查阅
    https://docs.slack.dev/apis/web-api.md
    中的_Evaluating responses_。
  • response_metadata.messages
    通常会指出参数格式错误的具体位置。
**速率限制：**当出现HTTP 
429
/ 
error: "ratelimited"
时，请遵循
Retry-After
响应头（单位为秒）——等待指定时间后重试。请勿在循环中频繁重试。每个方法的层级（1–4或特殊层级）限制了每分钟的调用次数；层级表见
https://docs.slack.dev/apis/web-api/rate-limits.md
，且新的非市场应用在部分方法上会面临更严格的限制，因此请以方法专属页面的具体数值为准。

Notes

注意事项

  • Slack Lists methods use the 
    slackLists.*
    prefix — a bare 
    lists.*
    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 
    slack:slack-cli
    ; Block Kit payloads to 
    slack:block-kit
    .
  • Slack Lists方法使用
    slackLists.*
    前缀——不存在裸
    lists.*
    名称的方法。
  • **范围：**本技能负责方法层——查找方法、阅读其约定以及围绕方法的调用逻辑。CLI认证和调用委托给
    slack:slack-cli
    ；Block Kit负载委托给
    slack:block-kit
    。