Composio Slackbot Toolkit 完整指南Bot 令牌模型、触发器配置与消息文件操作【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读本文以 Composio 开源仓库中的 Slackbot 公共知识文档docs/kb/source/toolkits/slackbot/public.md为主体系统讲解如何在 Composio 中使用 Slackbot 工具包构建以机器人bot身份运行的 Slack 自动化如何区分并选型slack与slackbot两套令牌模型、如何配置认证与私有会话所需的 scopes、如何配置触发器与验证令牌、以及如何用SLACKBOT_SEND_MESSAGE与SLACK_DOWNLOAD_SLACK_FILE完成发消息与下载文件的实操。读完本文你将掌握一套可直接落地的 Slack bot 接入方案并能结合仓库内的真实示例代码docs/lib/slack-bot-build.ts、docs/lib/slack-bot-source.json快速构建自己的机器人。一、Slack 与 Slackbot两种令牌模型的正确选型1.1 用户令牌与 Bot 令牌的分工Composio 提供两个不同的 Slack 工具包二者服务于完全不同的令牌模型slack工具包以真实 Slack 用户身份执行操作走用户令牌user token / user OAuth token。适合以某个人名义读取其日历、发私信、查看其私有数据等场景。slackbot工具包以 Slack 应用机器人身份执行操作走 Bot 令牌bot token专门用于channels:join之类的 bot scopes 或基于 bot 令牌的工作流。对应的知识文档可参见 docs/kb/source/toolkits/slack/public.md其中明确指出 Slack 工具的scopes字段指 bot-user scopes而若要以真实用户身份操作必须把权限放在credentials.user_scopes中——Slack is special because it separates bot scopes from user scopes。1.2 混合场景拆分认证配置不要混用 scopes原文档强调对于既要 bot 身份又要用户身份的混合场景不要把用户 scopes 和 bot scopes 塞进同一个连接connection而应分别创建独立的slack与slackbotauth config各自建立连接。仓库中的 Standup Bot 示例docs/content/examples/standup-slackbot.mdx正是这一原则的完整落地slackbot认证一个 Slack应用以bot身份发提醒和草稿如 Daily Standup Botslack认证单个用户以他们自己的身份把最终站会内容发进线程、并读取其活动上下文。该示例给出一条实用判断法则postingas the botusesslackbot; doing somethingas a personusesslack以 bot 身份发言用 slackbot以个人身份办事用 slack。在源码层面docs/lib/slack-bot-source.json 中routing-with-pi-provider.ts甚至会在 Agent 误用用户级 slack 工具时直接拒绝执行并提示Use the slackbot toolkit for Slack workspace actions in this bot. Search with toolkits [slackbot] and execute a SLACKBOT_* tool instead of using the user-scoped Slack toolkit.这说明Slack 工作区动作一律走 slackbot是仓库示例的硬性约束也印证了原文档的选型建议。二、Slackbot 认证配置bot scopes 与 user_scopes2.1 使用 Composio 托管认证创建 auth config仓库示例 docs/lib/slack-bot-source.json 的slackbot-setup.ts给出了创建 Slackbot auth config 的标准写法Composio 托管认证无需自建 Slack Appconst authConfig await composio.authConfigs.create(slackbot, { type: use_composio_managed_auth, name: workspace-bot, credentials: { scopes: [app_mentions:read, channels:history, chat:write, reactions:write, users:read], user_scopes: [search:read], }, });其中scopes为 bot 令牌的权限user_scopes为用户令牌的权限。仓库在同一文件中的实现会先authConfigs.list({ toolkit: slackbot, isComposioManaged: true })查找同名配置以做到幂等复用再决定是否新建。2.2 默认 bot scopes 清单源码实证slack-bot-source.json中src/config/env.ts定义了一组开箱即用的默认 bot scopes可通过环境变量SLACKBOT_BOT_SCOPES覆盖覆盖了消息、文件、会话、小组与 reactions 等常用能力app_mentions:read, assistant:write, channels:history, channels:read, chat:write, files:read, files:write, groups:history, groups:read, im:history, im:read, im:write, links:read, links:write, mpim:history, mpim:read, mpim:write, reactions:read, reactions:write, team:read, users:read对应的默认用户 scopesSLACKBOT_USER_SCOPES可覆盖还包括search:read、search:read.public、users.profile:read、users:read.email等。读者在自建 auth config 时可直接以此为基准按需裁剪。2.3 白标认证自带 Slack App 凭证如果希望机器人以自己品牌自己的 App 名称、头像出现可选用白标认证在 Composio 控制台创建 Auth Config 时选择OAuth 2.0 → Your Own Credentials填入自己在 Slack 创建的 App 的 Client ID 与 Client Secret并将team:read加入 user token scopes。详细操作步骤见 docs/content/examples/standup-slackbot.mdx 的 Auth the bot 一节对应示例的setup.ts会生成一次性 OAuth 链接批准后连接即生效脚本幂等可重复执行--reconnect可重跑。三、Slackbot 触发器验证令牌、事件订阅与私密会话 scopes3.1 自定义认证下必须配置 verification token原文档指出使用自定义认证custom auth配置 Slackbot 触发器时必须在 auth config 中配置 Slack App 的 verification token验证令牌并且在更新 auth config 之后重新创建一个全新的连接fresh connection。同时需要特别注意当前认证 schema并没有暴露独立的 subscription-ID 字段因此不要用其他值如订阅 ID去替代 verification token。这一约束的根源在于 Slack 事件订阅的合法性校验依赖验证令牌配置错误会导致触发器无法正常接收事件。补充排查建议如果 Slack 触发器事件突然停止还可检查 Slack App 的 Event Subscriptions 中的webhook_url是否被改动详见 docs/kb/source/toolkits/slack/public.md 的对应说明——订阅 URL 变更后 Slack 可能停止向 Composio 投递事件即使触发器实例本身看起来仍然存在。3.2 触发器实例的创建与负载标识仓库示例 docs/lib/slack-bot-source.json 的slackbot-setup.ts在安装流程中通过 upsert 接口创建两类 Slackbot 触发器await upsertTrigger(api, SLACKBOT_CHANNEL_MESSAGE_RECEIVED, connectedAccountId, ownerUserId, { is_bot_message: false, }); await upsertTrigger(api, SLACKBOT_DIRECT_MESSAGE_RECEIVED, connectedAccountId, ownerUserId, {});即SLACKBOT_CHANNEL_MESSAGE_RECEIVED频道消息事件可配置is_bot_message过滤是否包含机器人消息SLACKBOT_DIRECT_MESSAGE_RECEIVED私聊消息事件。Slackbot 触发器负载payload中会包含connection_id与trigger_id等标识符。原文档明确建议使用connection_id把事件映射回触发该事件的已连接账号connected account从而在事件处理函数中确定该用哪份凭证去响应。仓库的 webhook 处理器src/api/composio-webhook.ts正是基于这类 payload 做事件归一化、去重eventKey/ dedupe key与分发src/slack/events.ts中还会把connectedAccountId写入归一化事件供后续使用。3.3 私有频道与 DM 需要额外 history scopesSlack 的私有频道和私聊访问需要额外的历史记录 scopes场景所需 scope私有频道private channelgroups:history一对一直聊DMim:history多人私聊MPIMmpim:history这些 scope 并不总是默认包含且可能受 Slack 套餐/服务商限制例如部分 scope 需要付费套餐才可用因此客户可能需要自建 Slack App 并显式声明相应 scopes。仓库中 docs/lib/slack-bot-source.json 的默认 bot/user scope 清单恰好同时包含groups:history、im:history、mpim:history三组以及配套的groups:read、im:read、mpim:read可作为最小可运行集参考。四、文件下载先用 SLACK_LIST_FILES_WITH_FILTERS_IN_SLACK 解析文件 IDSlack 文件内容可通过SLACK_DOWNLOAD_SLACK_FILE工具下载核心参数是Slack 文件 ID通常以F开头例如F123ABCDEF0。据 docs/kb/source/toolkits/slack/public.md 说明该工具返回可下载的文件内容及元数据文件名 name、mimetype、大小 size 等。实操遵循两步走若没有文件 ID先调用SLACK_LIST_FILES_WITH_FILTERS_IN_SLACK列出可带过滤条件的文件列表将返回结果中的文件 ID 传入SLACK_DOWNLOAD_SLACK_FILE完成下载。第一步: SLACK_LIST_FILES_WITH_FILTERS_IN_SLACK → 得到 file_idF 开头 第二步: SLACK_DOWNLOAD_SLACK_FILE(file_id...) → 得到文件内容 name/mimetype/size 元数据注意不要把文件 ID与消息时间戳ts混用二者是不同体系文件 ID 一律以F前缀为特征。仓库的src/slack/transport.ts在拉取线程消息时会把消息中附带的文件以[file: 标题 URL]形式摘要进文本见messageTextWithFiles说明 Slack 文件信息常伴随消息事件出现Agent 可借此在触发器中感知到文件后再走下载工具。五、短认证链接不是 OAuth redirect URISlackbot 认证流程中常见形如/api/v3/s/...的短链接例如示例输出中的https://backend.composio.dev/s/AbC123xy。原文档特别澄清短链接只是缩短的连接发起 URL用于把浏览器重定向到 Slack 授权页它不是发送给 Slack 的redirect_uri。正确做法是在 Slack OAuth App 中配置Composio auth config 中展示的静态 redirect/callback URI。根据 auth config 的版本v1 或 v3 回调 URI 均可使用但必须与 Slack App 侧配置保持一致。仓库示例 docs/lib/slack-bot-build.ts 中的实现与此一致callbackUrl ${process.env.APP_URL}/connections/callback作为固定回调地址传给session.authorize与manageConnections而授权完成后拿到的request.redirectUrl才是一次性、给用户去点的认证链接并在示例中被专门提取出来通过私信发给用户而不是暴露在公共频道。六、发送 Bot 消息SLACKBOT_SEND_MESSAGE 的内容模式SLACKBOT_SEND_MESSAGE用于以 bot 身份向频道、私聊或私有群组发送消息是 Slackbot 工具包最核心的写入工具。原文档给出的参数纪律只能提供一种可见内容模式markdown_text普通 Markdown 内容blocks原始 Block Kit 布局JSON 结构。fallback_text只能与blocks搭配使用作为 Block Kit 不可渲染时的兜底纯文本不能单独使用也不能与markdown_text同时使用。6.1 仓库示例中的实际调用在 docs/lib/slack-bot-build.ts 的 bot 示例中回复 Slack 消息的标准调用形如await session.execute(SLACKBOT_SEND_MESSAGE, { channel: event.payload?.channel, thread_ts: event.payload?.thread_ts, text: reply, });其中channel为目标频道thread_ts可选填入则在指定线程内回复。同一文件还在重定向认证链接环节用SLACKBOT_SEND_MESSAGE给用户发私信channel 为打开的 DM 频道说明该工具同样适用于私聊场景。此外 docs/content/examples/standup-slackbot.mdx 还用到SLACKBOT_UPDATES_A_MESSAGE更新已发送的消息并演示了把交互式按钮Block Kitblocksaction_id通过消息工具下发——因此需要按钮、下拉菜单等交互元素时应使用blocks模式而非markdown_text。6.2 工具包之外的 Slack Web APIproxyExecute原文档聚焦 Slackbot 工具包内的既有工具。仓库示例进一步展示了工具未覆盖时的兜底方案通过session.proxyExecute({ toolkit: slackbot, endpoint: https://slack.com/api/..., method: POST, body })直接以已连接 Slackbot 账号的凭证调用任意 Slack Web API如conversations.open打开 DM、chat.postMessage发消息、assistant.threads.setStatus设置线程状态全程不接触原始令牌。这为读者提供了一条通用的扩展路径。七、触发器负载中的 connection_id 与 trigger_id原文档最后强调Slackbot 触发器负载payload data内包含connection_id和trigger_id等标识符。实践要点connection_id用于把事件映射回触发该事件的已连接账号。多租户场景下不同 Slack 团队/不同 bot 连接产生的同名事件靠connection_id区分归属从而选用正确的凭证与会话trigger_id标识触发实例本身可用于审计、去重与触发器维度的运维。仓库示例正是这一模式的工程化体现src/slack/events.ts把负载归一化为NormalizedSlackTriggerEvent其中保留connectedAccountId与triggerSlugsrc/api/composio-webhook.ts用eventKey 消息去重键做幂等避免重复消费src/composio/slackbot-setup.ts在 upsert 触发器时显式传入connected_account_id与user_id使触发实例与连接严格绑定routing-with-pi-provider.ts根据事件中的连接信息把共享的 Slackbot 连接钉进每个会话connectedAccounts: { slackbot: [slackbotConnectedAccountId] }。这些代码共同验证了以connection_id为中心的事件路由正是 Slackbot 触发器的标准用法。八、快速上手指引与相关文档关联知识文档docs/kb/source/toolkits/slackbot/public.md本文主体、docs/kb/source/toolkits/slack/public.md用户令牌模型的对照补充、docs/content/kb/guide/toolkits-slackbot.mdx公开版指南全文。可运行的完整示例docs/content/examples/standup-slackbot.mdx白标站会机器人含安装、交互按钮、手动执行与 proxy 兜底docs/lib/slack-bot-build.ts 与 docs/lib/slack-bot-source.json从最小 Agent逐步构建到完整 Slack bot 的分阶段源码含共享连接、认证链接重定向、webhook 验签等进阶实现。实践清单速记选对slack/slackbot令牌模型 → 私有会话补齐groups:history/im:history/mpim:history→ 自定义认证配好 verification token 并新建连接 → 发消息只选markdown_text或blocks之一、fallback_text仅限blocks→ 下载文件先 LIST 拿F开头文件 ID 再 DOWNLOAD → 短链接不当 redirect URI 用 → 触发器负载用connection_id回映射连接。遵循这套规范即可在 Composio 上稳定运行以 bot 身份驱动的 Slack 自动化工作流。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
