对接Teams机器人

1.1 功能简介

本文档介绍如何完成 Teams 机器人的申请与配置，最终实现 Dora 平台中 Agent 通过 Microsoft Teams 接收用户消息、处理文件并主动推送消息。

1.2 前提条件

开始配置前，请确认以下条件已满足：

1）拥有可用的 Microsoft 365/Teams 租户。

2）拥有可访问 Azure 门户/Microsoft Entra 的账号。

3）该账号具备创建或管理以下资源的权限：

• App Registration

• Azure Bot

• Microsoft Teams Channel

4）Teams 租户允许上传自定义应用。

5）FineBI Java 服务具备公网 HTTPS 地址。

6）Java 服务可以访问内网 Python fine-im 服务。

1.3 效果演示

以在 Teams 客户端向机器人询问“25年销售总额”为例，效果如下所示：

2.1 申请Teams机器人

1）访问 Azure 门户，点击「Microsoft Entra ID > 管理 > 应用注册 > 新注册」，创建新应用程序，如下图所示：

2）填写应用配置项，完成后点击「注册」，配置说明如下：

3）创建完成后，在「概述」页面中找到并记录：

• 应用程序 (客户端) ID

• 目录 (租户) ID

2.2 增加新客户端密码

1）点击「管理 > 证书和机密 > 客户端密码 > 新客户端密码」，根据业务需求填写说明、调整截止时间后点击「添加」。

2）创建完成后，立即复制并保存密码值。

注：

1）必须保存客户端密码的「值」，而非机密 ID；

2）客户端密码的值仅创建时可复制，请立即获取，一旦关闭页面将无法再次获取。

2.3 创建 Azure 机器人

1）在 Azure 门户搜索并创建「Azure Bot」资源。

2）「Creating Type」选择「Using existing app registration」，填入本文【2.1 章节】中记录的「应用程序 (客户端) ID」与「目录 (租户) ID」，其余配置按需填写。

3）创建完成后自动跳转至机器人概述页，点击「转到资源 > 设置 > 配置」，填写消息端点后点击「应用」。

消息端点格式规范：https://{公网域名}/webroot/decision/ai/conversation/im/teams/messages/{Microsoft App ID}，其中 Microsoft App ID 为本页面展示的 Microsoft App ID。

注：

1）必须使用 HTTPS 协议，证书有效且未过期

2）URL 末尾占位符 {Microsoft App ID} 必须与 Dora 系统内配置的 App ID 完全一致

3）反向代理最终转发目标必须为 Java 服务，不可直接指向 Python 服务

4）反向代理转发请求时，需完整保留请求头中的 Authorization 字段

5）Java 服务需能正常访问内部 Pythonfine-im 服务

2.4 启用 Teams 渠道

1）进入「设置 > 渠道」，点击「Microsoft Teams」。

2）勾选协议 Agree 后点击「Apply」。

3.1 在Agent中配置Teams机器人

进入「目标 Agent>对接 IM 工具>新增/编辑 Microsoft Teams 机器人」，填写以下信息并保存：

• App ID：应用程序 (客户端) ID

• App Secret：客户端密码的值

• Tenant ID：目录 (租户) ID

3.2 获取App包并上载至Teams

3.2.1 获取App包

方式一：Agent中直接下载

进入「管理后台 > Agent 管理 > 选中目标 Agent > 对接 IM 工具 > 新增 / 编辑 Microsoft Teams 机器人」，直接下载对应应用包。

方式二：手动打包

1）准备 3 个文件：manifest.json 、color.png 、outline.png ，压缩为 ZIP 压缩包。

manifest.json 核心字段要求：

2）压缩包根目录直接存放上述 3 个文件，解压后第一层目录必须直接看到这三个文件。

3.2.2 Teams客户端上载自定义应用

登录 Teams 客户端，进入「应用>管理你的应用」，将上一步获取到的 App包上载至 Teams 客户端。

注：若无上传入口，代表租户策略未开放自定义应用权限，需联系 Teams 管理员开通。找到上传的应用，点击「添加」完成安装。

3.2.3 为客户端添加应用

上载成功后，页面将出现相应应用卡片，点击卡片内「添加」按钮唤起弹窗，再点击弹窗中的「添加」，即可将该机器人应用添加至 Teams 客户端，如下图所示：

3.3 配置 Teams 用户映射

进入「用户管理 > IM 用户映射 > Teams」，完成企业账号与 Teams 账号的匹配绑定。

在 Teams 内打开与机器人的私聊窗口，发送消息即可测试对话、文件处理、消息推送功能。

5.1 Teams 发送消息，系统未收到

请检查以下内容：

1）Azure 机器人的消息端点地址是否填写正确

2）端点是否指向 Java 服务

3）公网 HTTPS 地址能否正常访问 Java/FineBI 服务

4）Java 服务是否成功中转请求至 Pythonfine-im

5）反向代理是否完整透传 Authorization 请求头

6）Teams 应用 manifest 内 botId 是否等于 App ID

7）Azure 机器人是否已启用 Microsoft Teams 渠道

8）Dora 后台是否已绑定对应 Teams 机器人

5.2 App Secret 不可用

请检查以下内容

1）Dora 系统填写的是客户端密码「值」，而非密钥 ID

2）客户端密钥是否已过期

3）App ID 与密钥是否来自同一个应用注册

5.3 报错：CONNECTION_NOT_FOUND

常见原因：

• 回调路径中的 {AppID} 与 Dora 绑定的 App ID 不一致

• Teams 消息已转发至后端 AI，但 Dora 未完成 Teams 机器人绑定

• AI 服务重启后连接恢复失败

5.4 报错：CHANNEL_DELIVERY_FAILED

常见原因：

• Bot Framework 令牌校验失败

• Java 服务 / 反向代理未透传 Authorization 请求头

• Java 访问 Python 中转地址无法连通

• Teams 消息结构不符合解析器预期格式

5.5 报错：MISSING_REFERENCE

常见原因：

• 目标用户未私聊过机器人

• 用户映射配置的账号，与回调携带的外部身份 ID 不匹配

• 切换环境后，会话引用数据未迁移