slack-api

Slack Web API

帮助开发者发现合适的 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。请查看文档页面。
• 切勿将不记名令牌硬编码到已提交的代码中，也不要以纯文本形式分享。
• 切勿在未确认替代方法的情况下使用已弃用的方法（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.*）——准备好准确的命令后，先与开发者确认，再运行。

---

快速路径（适用于明确、具体的请求）

如果开发者已经知道方法——例如提到了方法名称、粘贴了 https://slack.com/api/<method> URL 或 docs.slack.dev/reference/methods/<method> 链接，或给出了 family.method——则跳过发现步骤：

1. 转到步骤 2，阅读方法的契约。
2. 转到步骤 4，调用该方法（遵循上述执行原则）。

完整工作流的提示：（从步骤 1 开始）

• “哪个方法可以实现 X？”/“如何通过 API 列出/获取/发布……？”
• 已知要实现的功能，但不知道方法名称。
• 探索 API 功能的问题。

---

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

将开发者的意图映射到一个类别，再找到候选方法。

浏览索引

使用 WebFetch 获取实时方法索引：

https://docs.slack.dev/reference/methods.md

索引以 family.method 表示法列出所有 Web API 方法，附有一行说明和指向该方法自身文档页面的链接。索引内容完整且始终为最新——在其中查找候选方法，然后点击该方法的链接，进入步骤 2 阅读契约（索引仅提供说明；速率限制等级、权限范围、令牌类型和分页信息均位于各方法的独立页面上）。

切勿发布或调用从未在实时页面中见过的方法名称。

搜索文档

如果你更愿意按关键词搜索而不是浏览索引，且可以使用 Slack CLI，请使用 slack:slack-cli 技能中的步骤 3：搜索文档（slack docs search），从终端查询 Slack 文档。该步骤介绍了命令和标志；搜索结果会指向方法的参考页面，然后你需要在步骤 2 阅读该页面。如果无法使用 CLI，请使用 WebFetch 获取索引（https://docs.slack.dev/reference/methods.md）并浏览查找。

---

第 2 步：阅读方法契约（导航）

使用 WebFetch 获取方法的文档页面。可以从索引（第 1 步）进入该方法的链接，也可以自行构造 URL——路径部分全部使用小写，并以 .md 结尾：

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- 与用户 xoxp-）
• 参数——必需参数与可选参数及其类型
• 请求和响应示例
• 错误表（特定于方法的代码）
• 速率限制等级

调用前，先提取必需参数和必需作用域。有关这些跨领域概念的常规含义——超出方法页面的说明范围——请参阅权威文档：https://docs.slack.dev/apis/web-api.md 中的响应封装、POST 请求体和身份验证；https://docs.slack.dev/apis/web-api/pagination.md 中的分页；以及 https://docs.slack.dev/apis/web-api/rate-limits.md 中的速率限制等级。

---

第 3 步：进行身份验证并确认作用域

调用任何非公开方法，都需要使用具备正确作用域和类型的令牌。本技能在此处的任务是根据你在第 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，而不要强制其安装。

路径 A：使用 Slack CLI（如果已安装或有意安装）

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。身份验证操作说明请参阅该步骤。

路径 B：不使用 CLI — 自备令牌

调用方法不需要 CLI。前往 Slack 应用配置中的 OAuth & Permissions 页面（https://api.slack.com/apps → 你的应用 → OAuth & Permissions → OAuth Tokens），获取上面确定的类型的令牌：Bot User OAuth Token（xoxb-…）或 User OAuth Token（xoxp-…）。该页面还会列出当前已授予的范围 — 确认其中包含第 2 步所需的范围。然后在第 4 步（“通过原始 HTTP”／“通过 SDK”）中，使用 curl 或 SDK 发送该令牌。

---

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

首先应用执行原则：如果该方法会更改状态（发布／更新／删除／归档／移出，或任何 admin.* 方法），请向开发者展示确切的命令，并在执行前征得同意。只读调用可以直接执行。

通过 Slack CLI（如果已安装）

要从终端调用方法，请使用 slack:slack-cli 技能 — 第 4 步：调用 Web API 方法（slack api）。该步骤介绍了 SLACK_CMD api <method> key=value … 语法，因此这里不再重复。传入你在第 2 步从方法文档页面获取的必需参数。

CLI 使用开发者已通过身份验证的会话，因此登录后（第 3 步）这是最简单的方式。

通过原始 HTTP（curl）

开发者需要发送原始请求或不使用 CLI 时，请使用 Bash 工具。在 Authorization 标头中发送令牌 — 即第 3 步中的机器人或用户令牌（路径 B 或 CLI 会话）。

表单编码（大多数方法的默认方式）：

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 等复杂参数的方法）：

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=[...]）。

通过 SDK

在 Bolt 和 Slack SDK 中，每个方法都是客户端函数，其参数与文档页面中的参数表一致：

• JavaScript： await client.chat.postMessage({ channel, text, blocks })
• Python： client.chat_postMessage(channel=channel, text=text, blocks=blocks)

（注意，JS 使用点号形式 chat.postMessage，Python 使用下划线形式 chat_postMessage。）要构造这些调用所需的 blocks／view 负载，请使用 slack:block-kit 技能 — 该技能将此负载视为不透明参数，重点讲解其外围的方法调用。

---

第 5 步：处理分页

返回集合的方法使用游标分页，而非页码。方法文档页面会说明该方法是否支持分页；支持游标分页的方法完整列表见 https://docs.slack.dev/apis/web-api/pagination.md 中的 支持基于游标分页的方法：

1. 使用 limit（页面大小）调用 — 请查看该方法的上限。
2. 从响应中读取 response_metadata.next_cursor。
3. 如果该值非空，则使用 cursor=<next_cursor> 再次调用。
4. 重复上述步骤，直到 next_cursor 返回空值。

# 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='

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

---

第 6 步：处理速率限制和错误

当 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 中的 评估响应。
• response_metadata.messages 通常会指出格式错误的参数。

**速率限制：**遇到 HTTP 429 / error: "ratelimited" 时，请遵循 Retry-After 响应标头（秒）——等待后再重试。不要在短时间内循环重试。每种方法的等级（1–4 或特殊）都会限制每分钟调用次数；等级表见 https://docs.slack.dev/apis/web-api/rate-limits.md。较新的非 Marketplace 应用在部分方法上面临更严格的限制，因此具体次数应以该方法自身的文档页面为准。

---

备注

• Slack Lists 方法使用 slackLists.* 前缀——不存在名为 lists.* 的方法。
• **范围：**此技能负责方法层——使用哪个方法、方法的约定以及围绕它的调用。CLI 身份验证和调用交由 slack:slack-cli 处理；Block Kit 负载交由 slack:block-kit 处理。