Slack调用手册
分页读取授权频道的消息历史
读取机器人已加入的公开频道,以 cursor 获取后续页,并按应用分发类别限制调用频率。
← 返回平台功能接入准备
- 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 的终端。按调用步骤保存代码文件,再在同一终端执行。
调用步骤
- 01
在 OAuth & Permissions 添加 channels:history 并完成重新安装,保存 SLACK_BOT_TOKEN。
- 02
把机器人加入目标频道,将频道详情中的 ID 设置为 SLACK_CHANNEL_ID。
- 03
先请求 limit=15 的第一页,检查 ok 和 response_metadata.next_cursor;有非空 cursor 才继续翻页。
- 04
下一页在原请求 URL 增加 URL 编码后的 cursor 参数,保持同一频道和筛选条件;每次请求前遵守下述分发限流。
调用 01
取得频道历史第一页
此代码仅演示第一页,后续页按返回 cursor 获取;请求不会修改消息。
GET
https://slack.com/api/conversations.history?channel=${SLACK_CHANNEL_ID}&limit=15请求头
AuthorizationBearer ${SLACK_BOT_TOKEN}
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
channelQuery | string必填 | 需要读取的会话 ID,Bot 必须已加入。 |
limitQuery | integer可选 | 本例 15,适合新商业分发限额。商业分发且未经 Marketplace 批准的新应用及新安装,默认及最大值都是 15;其他适用 Tier 3 的应用限制不同。 |
cursorQuery | string可选 | 上一页 response_metadata.next_cursor,URL 编码后发送;为空时无需继续。 |
oldest / latestQuery | string可选 | 用 Slack 消息时间戳限定读取边界,保持为字符串;本例未指定。 |
inclusiveQuery | boolean可选 | 是否包含时间边界消息,仅在提供 oldest 或 latest 时生效。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
# 执行后核对返回 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}"
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 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 表示继续翻页,第一页不是完整导出。 以下为结构示意,非本站实测结果。
{
"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 字段;未在本站读取真实工作区内容。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01OAuth 安装与权限核验日期 2026-10-15
- 02conversations.history 读取范围、分页与分发限流核验日期 2026-10-15
- 03Web API 限流与新商业分发条件核验日期 2026-10-15
- 04免费版历史记录与应用安装限制核验日期 2026-10-15
