Slack调用手册

分页读取授权频道的消息历史

读取机器人已加入的公开频道,以 cursor 获取后续页,并按应用分发类别限制调用频率。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • Bot Token Scopes 添加 channels:history 并重新安装授权;机器人已加入目标公开频道。
  • 本例只读公开频道历史;私有频道、私信和群私信分别需要 groups:history、im:history、mpim:history。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

SLACK_BOT_TOKEN
OAuth & Permissions 中已安装应用的 Bot User OAuth Token,保存在本机或服务端。
SLACK_CHANNEL_ID
自己测试频道的会话 ID,可从 Slack 频道详情查看;示例 ID 为虚构值。
终端
export SLACK_BOT_TOKEN='xoxb_replace_with_your_bot_token'
export SLACK_CHANNEL_ID='C0123456789'

以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件,再在同一终端执行。

调用步骤

  1. 01

    在 OAuth & Permissions 添加 channels:history 并完成重新安装,保存 SLACK_BOT_TOKEN。

  2. 02

    把机器人加入目标频道,将频道详情中的 ID 设置为 SLACK_CHANNEL_ID。

  3. 03

    先请求 limit=15 的第一页,检查 ok 和 response_metadata.next_cursor;有非空 cursor 才继续翻页。

  4. 04

    下一页在原请求 URL 增加 URL 编码后的 cursor 参数,保持同一频道和筛选条件;每次请求前遵守下述分发限流。

调用 01

取得频道历史第一页

此代码仅演示第一页,后续页按返回 cursor 获取;请求不会修改消息。

GEThttps://slack.com/api/conversations.history?channel=${SLACK_CHANNEL_ID}&limit=15

请求头

Authorization
Bearer ${SLACK_BOT_TOKEN}

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
channelQuerystring必填需要读取的会话 ID,Bot 必须已加入。
limitQueryinteger可选本例 15,适合新商业分发限额。商业分发且未经 Marketplace 批准的新应用及新安装,默认及最大值都是 15;其他适用 Tier 3 的应用限制不同。
cursorQuerystring可选上一页 response_metadata.next_cursor,URL 编码后发送;为空时无需继续。
oldest / latestQuerystring可选用 Slack 消息时间戳限定读取边界,保持为字符串;本例未指定。
inclusiveQueryboolean可选是否包含时间边界消息,仅在提供 oldest 或 latest 时生效。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://slack.com/api/conversations.history?channel=${SLACK_CHANNEL_ID}&limit=15" \
  --header "Authorization: Bearer ${SLACK_BOT_TOKEN}"
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://slack.com/api/conversations.history?channel=${SLACK_CHANNEL_ID}&limit=15")
headers = {
    "Authorization": expand("Bearer ${SLACK_BOT_TOKEN}"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "ok" in result and result["ok"] != True:
    raise SystemExit("平台返回业务错误,请结合下方排错说明检查响应")
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://slack.com/api/conversations.history?channel=${SLACK_CHANNEL_ID}&limit=15");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${SLACK_BOT_TOKEN}"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "ok") && result["ok"] !== true) {
  throw new Error('平台返回业务错误,请结合下方排错说明检查响应');
}

返回示例

官方字段的节选结构示意,消息与游标均为虚构。messages 为消息数组;非空 next_cursor 表示继续翻页,第一页不是完整导出。 以下为结构示意,非本站实测结果。

JSON
{
  "ok": true,
  "messages": [
    {
      "type": "message",
      "user": "U0123456789",
      "text": "示例消息",
      "ts": "1735689600.000001"
    }
  ],
  "has_more": true,
  "response_metadata": {
    "next_cursor": "example_cursor_replace_with_actual_value"
  }
}

常见错误与排查

invalid_auth / token_revoked令牌失效或已撤销。
核对应用所在工作区和 token 状态;必要时重新安装授权,不要把 Signing Secret 当 Bot Token。
missing_scope令牌没有方法所需权限。
在 OAuth & Permissions 增加本场景 scope 并重新安装授权,不能只修改后台配置后继续用旧权限。
HTTP 429 / ratelimited方法调用触发限流。
遵守 Retry-After 响应头暂停,再按方法和工作区排队;不要立即循环重试。
channel_not_found / not_in_channel频道不存在或 Bot 不能访问。
确认工作区、频道 ID 和机器人加入状态;历史 scope 不会自动把 Bot 加入频道。
invalid_cursor游标无效。
使用上一次实际返回的游标并正确 URL 编码;不要把本页示意游标当作真实值。

调用注意

  • 自 2025 年 5 月 29 日起,商业分发且未经 Marketplace 批准的新应用及新安装限每分钟 1 次且 limit 最大 15;已批准的 Marketplace 应用及客户自建内部应用按 Tier 3。当前官方页说明既有安装不受这项新限流影响。
  • 线程回复另用 conversations.replies,不能把 history 数组当作线程全部内容;分页期间消息可能变化,应用应按频道 ID 与 ts 去重。
  • 免费工作区的历史可见范围及保留政策仍然适用;API 不提供读取已删除消息的权限。

注意事项

  • 当前代码只演示单页读取;生产同步需实现分页、限流退避和可恢复检查点。
  • 通用示例打印 HTTP 200 返回,仍需检查 ok:false 以及 error 字段;未在本站读取真实工作区内容。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
    OAuth 安装与权限核验日期 2026-10-15
  2. 02
  3. 03
  4. 04

Slack的其他调用手册

← 返回Slack的全部功能