3.14 在 IM 里和员工对话

IM 通道让你不打开工作台，也能在飞书、Lark（飞书国际版）、Telegram 或 Slack 里和主助手、指定员工对话；在已绑定的 IM 群里 @员工派活；收到审批卡片时直接批准或拒绝。会话、群消息和审批都走 Teloa 本身的服务，工作台里看到的是同一份记录。接入真实平台前，先用测试机器人核对一次私聊、群 @ 和审批卡片。

启用 IM 通道

IM 通道随 Teloa 内置，不需要另行安装，也不需要在市场启用。在 设置 > IM 通道 添加并启用具体渠道即可；不再使用某个渠道时，也在这里停用或移除该渠道。整个 IM 通道不能停用。

准备

• Teloa 运行在 Node.js 22 或更高版本上，本机需要能访问所选 IM 平台。
• 在平台上自建一个机器人（Telegram bot、Slack 内部 App、飞书或 Lark 的企业自建应用），拿到它的密钥。
• 一个渠道只绑定一位本人账号。IM 里其他人发的消息不会被当成指令执行。

各平台需要的密钥：

渠道	密钥	平台侧要求
Telegram	Bot Token	用 BotFather 创建机器人
Slack	Bot Token（xoxb-）与 App Token（xapp-）	开启 Socket Mode；授予 connections:write、chat:write、app_mentions:read、im:history、channels:history
飞书	App ID、App Secret，Encrypt Key 可选	事件订阅用长连接；开通 im:message、im:message.group_at_msg 与卡片回调
Lark（飞书国际版）	App ID、App Secret，Encrypt Key 可选	在 Lark 开发者后台建应用，要求与飞书相同，见下文

添加渠道并绑定

1. 打开 设置 > IM 通道，在「添加渠道」选择渠道类型，填入密钥后保存。页面只显示「密钥已保存」，不会再显示密钥内容。
2. 打开该渠道的开关。状态变为「已连接」后，点「生成配对码」。
3. 在 IM 里私聊机器人，发送 /pair 配对码。配对码 10 分钟内有效、只能用一次，在群里发送无效。
4. 机器人回复「已绑定」后，刷新设置页，「已绑定的账号」里会出现你的账号。可在这里把默认对话对象从「主助手」改成某位员工。

首次保存飞书或 Lark 渠道时，Teloa 会下载并核对锁定版本的飞书开发包（两者共用同一份，已下载过就不再下载），可能要等一分钟左右。

渠道密钥只能在设置页保存。在环境变量里设置 SLACK_BOT_TOKEN、FEISHU_APP_SECRET、LARK_APP_SECRET 等不会生效，_FILE 形式同样不生效；启动器会把这类变量从启动环境里剔除，并在启动日志里提示一次（只列变量名）。

Lark（飞书国际版）的准备

Lark 与飞书是两套独立的平台：开发者后台、账号和企业（租户）互不相通。在飞书开放平台建的应用装不进 Lark 企业，反过来也一样，所以 Lark 要单独建应用，在 Teloa 里也是单独的「Lark（飞书国际版）」渠道。两个渠道可以同时启用，互不影响；已有的飞书渠道不需要改动。

1. 用 Lark 企业账号登录 Lark 开发者后台，新建企业自建应用。
2. 在应用的「添加应用能力」里打开机器人。
3. 在「权限管理」开通 im:message、im:message.group_at_msg。
4. 在「事件与回调」里，事件订阅方式选使用长连接接收事件，添加「接收消息」事件（im.message.receive_v1）；回调订阅方式同样选长连接，添加「卡片回传交互」（card.action.trigger）。长连接只支持企业自建应用。
5. 创建版本并发布，等企业管理员审核通过。
6. 在「凭证与基础信息」复制 App ID（cli_ 开头）和 App Secret；如设置了 Encrypt Key 也一并复制。
7. 回到 Teloa 的 设置 > IM 通道，渠道类型选「Lark（飞书国际版）」，填入后保存，再打开开关并按上文完成配对。

Lark 渠道只连接 Lark 官方开放平台地址 open.larksuite.com，这个地址由渠道类型决定，不能手动填写。运行 Teloa 的机器需要能访问该地址。

私聊与命令

私聊里直接发文字，就会进入与默认对象的会话；回复完成后发回同一私聊。可用命令：

命令	作用
/new	新开一个会话
/status	查看当前对话对象
/stop	停止当前回复
/同事 名字（/colleague）	切换到某位员工；/同事 助理 切回助理
/任务（/tasks）	查看最近任务
/需要你（/attention）	查看待你处理的事项
/help	命令说明

密钥、付款、账号与安全设置只能在工作台完成，IM 里会收到引导链接。

在群里派活

在设置页的「群绑定」把 IM 群绑定到 Teloa 的某个协作群。之后在该 IM 群里 @机器人 或 @员工名，你的这条消息会连同之前最多 10 条他人发言（作为资料，不作为指令）一起发到协作群，由员工接手；员工的回复会发回原 IM 群。未 @ 的发言只在内存里暂存，不写入记录。

审批

员工执行需要授权的操作时，工作台和你的 IM 私聊会同时出现审批卡片，先处理的一方生效；在工作台先处理时，IM 卡片随即改为「已在网页处理」并撤下按钮。只有绑定者本人能在 IM 里处理；卡片 30 分钟无人处理会过期，请回到工作台处理。IM 只能批准或拒绝本次调用，不能改动授权规则。

已知限制

• 在 IM 里先处理了审批后，工作台上同一张卡片会停留到本轮结束，再点它不会产生效果。
• Teloa 重启后，重启前发出的 IM 审批卡片会过期，点击只会提示「已处理或已过期」。
• 同一台电脑上只允许一个 Teloa 连接同一组 IM 渠道；另一个会显示「连接出错 · 另一台 Teloa 已连接该渠道」。
• 暂不支持在 IM 里收发文件或流式显示回复。在已绑定 IM 群的话题里 @ 员工，消息进入协作群主消息流，回复发回原话题。

部署时的网络与数据位置说明见运行配置与数据位置。