跳到主要内容

IM 通道集成指南

IM 通道集成允许您将 Wegent 智能体连接到即时通讯平台，让用户可以在熟悉的聊天工具中直接与 AI 智能体对话。

📋 目录​

🎯 概述​

什么是 IM 通道集成？​

IM 通道集成将 Wegent 智能体连接到即时通讯平台，让用户无需访问 Wegent 网页界面，即可在日常使用的聊天软件中直接与 AI 智能体对话。

核心价值​

价值描述
熟悉的环境在您每天使用的聊天工具中使用 AI 智能体
实时响应通过平台支持的卡片或消息更新获得流式 AI 响应
多轮对话在多条消息之间保持上下文连贯
团队协作与整个组织共享 AI 能力

支持的平台​

平台状态功能
钉钉✅ 已支持流模式、AI 卡片流式响应、多轮对话
Telegram✅ 已支持私聊、命令式交互、Chat/Task 模式、流式消息更新
Discord✅ 已支持私聊、命令式交互、Chat/Task 模式
微博私信✅ 已支持私聊、WebSocket 接入、流式消息累加、Wework 本地任务续接
飞书🔜 规划中即将推出
企业微信🔜 规划中即将推出

🏗 架构说明​

消息流转​

下图展示了消息在 IM 集成系统中的流转过程：

关键组件​

组件用途
通道管理器 (Channel Manager)管理所有 IM 通道连接的生命周期
通道提供者 (Channel Provider)平台特定的连接处理器（钉钉、Telegram、Discord 等）
消息处理器 (Message Handler)处理传入消息并路由到智能体
响应发射器 (Response Emitter)将 AI 响应发送回 IM 平台（同步或流式）

💬 使用说明​

基本对话​

像在任何聊天中一样向机器人发送消息：

用户：你能帮我做什么？
机器人：我是由 Wegent 驱动的 AI 助手。我可以帮助您...

多轮对话​

机器人在同一聊天会话中保持对话上下文：

用户：我正在开发一个 React 项目
机器人：很好！我很乐意帮助您的 React 项目...

用户：如何优化性能？
机器人：对于您的 React 项目，这里有一些性能优化建议...

开始新对话​

要清除上下文并重新开始，使用 /new 命令：

用户：/new
机器人：已开始新对话。有什么可以帮助您的？

流式响应​

启用平台支持的流式响应后，您将看到响应实时出现：

  1. 机器人显示"思考中..."指示器
  2. 响应文本逐步流式显示
  3. 最终响应以格式化形式呈现

钉钉使用 AI 卡片更新流式内容；Telegram 使用消息更新展示流式内容和思考摘要。

微博私信使用同一条消息进行流式累加：后端先创建稳定的微博 messageId，后续内容片段和完成事件都会更新同一条私信消息。系统状态（例如“正在分析问题”）由运行时事件显示，微博通道不会额外插入“正在思考”占位文本。

私聊任务模式​

在支持私聊的 IM 通道中，可以使用命令选择对话模式或任务模式：

命令说明
/new新建 Chat、Task，或继续最近 Task
/chat切换到 Chat 模式
/task切换到 Task 模式并选择最近任务
/switch重新选择当前任务
/bind将当前私聊绑定到任务
/status查看当前私聊状态
/cancel取消当前选择流程

微博私信的 Task 模式仅支持 Wework 绑定的本地运行时任务。请先在 Wework 本地任务中点击“继续到私聊”，选择微博私聊后再在微博中继续发送消息；直接在微博中使用 /task 或 /switch 时，如果未绑定本地任务，系统会提示回到 Wework 选择。

⚙️ 管理功能​

通道状态监控​

在管理面板中查看通道健康状态：

状态指示器描述
已连接🟢 绿色通道活跃并正在接收消息
已断开🔴 红色通道离线或遇到错误
已禁用⚪ 灰色通道被手动禁用

通道操作​

操作描述
启用/禁用在不删除配置的情况下切换通道状态
重启重新连接到 IM 平台（网络问题后有用）
编辑修改通道设置（密钥留空保持现有值）
删除移除通道配置

更新配置​

编辑通道时：

  • 敏感字段（Client Secret）以 *** 显示
  • 留空敏感字段以保留现有值
  • 输入新值以更新凭证

微博私信配置​

创建微博私信通道时：

  1. 在 管理后台 → IM 通道 中选择 微博。
  2. 私信微博龙虾助手获取 App ID 和 App Secret。
  3. 将 App ID 和 App Secret 填入 Wegent。
  4. WebSocket 地址和 Token 地址通常保持为空，系统会使用默认微博开放私信地址；只有使用代理或测试环境时才需要覆盖。
  5. 选择默认智能体并启用通道。

App Secret 编辑时留空表示保持原值不变。

监控指标​

每个通道可用的指标：

  • 运行时长：通道已连接的时间
  • 最近错误：最近的错误消息（如有）
  • 连接时间：通道最后连接的时间

👥 用户映射机制​

自动用户创建​

当 IM 平台用户首次与机器人交互时：

  1. 系统尝试查找现有的 Wegent 用户
  2. 如果未找到，自动创建新用户账号
  3. 用户与其 IM 平台身份关联

默认用户创建：

  • 用户名：IM 平台用户 ID
  • 邮箱：{user_id}@im-platform.com
  • 认证来源：对应的 IM 平台名称

企业用户映射​

对于拥有现有用户目录（ERP、LDAP）的组织，可以配置自定义用户映射器：

请联系您的系统管理员配置企业用户映射。

🔗 平台集成指南​

以下平台有详细的集成配置指南：

平台链接
钉钉钉钉集成配置指南

❓ 常见问题​

连接问题​

通道显示"已断开"​

可能原因：

  1. Client ID 或 Client Secret 无效
  2. 网络连接问题
  3. IM 平台 API 服务中断

解决方案：

  1. 在开放平台验证凭证
  2. 检查 Wegent 服务器的网络连接
  3. 尝试重启通道
  4. 检查 IM 平台服务状态

消息未被接收​

可能原因：

  1. IM 平台未启用所需的接收消息或流式能力
  2. 机器人权限未配置
  3. Wegent 中通道未启用

解决方案：

  1. 验证 IM 应用设置中已启用接收消息或流式能力
  2. 检查所有必需权限已授予
  3. 确保通道已启用（开关已打开）

响应问题​

机器人无响应​

可能原因：

  1. 默认智能体未配置
  2. 智能体未分配模型
  3. 速率限制

解决方案：

  1. 验证通道已选择默认智能体
  2. 确保智能体有可用的模型配置
  3. 检查通道状态中的速率限制错误

响应缓慢或不完整​

可能原因：

  1. 平台流式传输或消息更新问题
  2. 网络延迟
  3. 响应内容过大

解决方案：

  1. 尝试临时禁用对应平台的流式传输
  2. 检查网络连接
  3. 系统会在流式传输失败时回退到同步模式

用户问题​

用户未被识别​

可能原因：

  1. 用户映射配置问题
  2. IM 平台用户信息不可访问

解决方案：

  1. 检查 IM 应用中的用户权限
  2. 验证用户映射配置
  3. 联系管理员配置企业用户映射

🔗 相关资源​

文档​

外部资源​

💬 获取帮助​

需要帮助？

将您的 AI 智能体连接到 IM 平台，赋能您的团队！ 🚀