IM 集成与用户同步

钉钉、飞书、企业微信、微信服务号的企业关联、凭证配置与通讯录同步

IM 集成与用户同步

Knodo 支持与钉钉、飞书、企业微信、微信服务号集成，实现企业关联、工作台免密登录、通讯录用户同步和 AI 机器人消息收发。

功能概览

通用流程

关联企业

1. 进入 组织设置 页面
2. 找到对应 IM 的集成卡片
3. 填写企业标识和名称（必填）
4. （可选）填写应用凭证，解锁通讯录同步能力
5. 点击"关联"完成绑定

凭证配置对比

用户同步策略

配置应用凭证后，点击"同步用户"将主动拉取企业通讯录，按以下优先级匹配系统用户：

1. 平台 ID 匹配：已通过该 IM 登录过的用户（unionId / userid）
2. 邮箱匹配：通过邮箱注册的存量用户，自动补全 IM 信息
3. 未匹配：跳过，不创建新账号

匹配成功的用户自动加入组织，后续可使用工作台免密登录。

未配置凭证时，仅匹配已通过该 IM 登录过且企业标识一致的用户。

解除关联

1. 在集成卡片点击"解除关联"
2. 确认操作

解除关联会清除已配置的应用凭证，已同步的成员不会被删除。

钉钉集成

企业信息

获取凭证

1. 登录 钉钉开放平台
2. 进入企业内部应用
3. 在「凭证与基础信息」页面获取 AppKey 和 AppSecret

所需设置

在钉钉开放平台完成以下配置：

• 应用可见范围设置为「全部员工」
• 通讯录部门信息读权限
• 通讯录部门成员读权限
• 成员信息读权限

自动加入

关联后，钉钉用户通过工作台免密登录时，系统根据 corpId 自动匹配组织凭证，完成身份认证后自动成为组织成员。

图片与文件收发

钉钉机器人支持接收和发送图片、文件消息，需在 IM 机器人配置中填写 App Key 和 App Secret（即企业内部应用的凭证，与组织级关联凭证相同）。

限制：

• 图片大小限制：10MB
• 文件大小限制：50MB
• 图片上传失败时自动回退为文本消息

详细配置步骤请参考 IM 机器人集成 - 图片和文件支持。

飞书集成

企业信息

获取凭证

1. 登录 飞书开放平台
2. 进入企业自建应用
3. 在「凭证与基础信息」页面获取 App ID 和 App Secret

所需设置

在飞书开放平台完成以下配置：

• 应用可用范围设置为「全部员工」
• 获取部门基础信息（contact:department.base:readonly）
• 获取用户基本信息（contact:user.base:readonly）

注意：飞书登录不需要组织级凭证（tenant_key 从 token exchange 返回），只有通讯录同步需要组织级凭证。

自动加入

关联后，飞书用户通过工作台免密登录时，系统根据 tenant_key 自动匹配组织，用户自动成为组织成员。

企业微信集成

企业信息

获取凭证

1. 登录 企业微信管理后台
2. 进入自建应用
3. 获取 AgentId 和 Secret

所需设置

在企业微信管理后台完成以下配置：

• 应用可见范围设置为「全部员工」
• 通讯录读取权限

自动加入

关联后，企微用户通过工作台免密登录时，系统根据 corpId 自动匹配组织凭证，完成身份认证后自动成为组织成员。

微信服务号集成

微信服务号支持 AI 机器人消息收发和模板消息主动推送功能，适用于告警通知、任务提醒等场景。

配置信息

获取凭证

1. 登录 微信公众平台
2. 进入「开发 → 基本配置」
3. 获取 AppID 和 AppSecret
4. 设置「服务器配置」中的 Token 和 EncodingAESKey

所需设置

1. 在微信公众平台进入「设置与开发 → 基本配置 → 服务器配置」
2. 填写服务器地址（URL）：https://<your-domain>/api/v1/im-webhook/wechatmp/<callbackToken>
3. 填写 Token 和 EncodingAESKey（与系统配置保持一致）
4. 消息加解密方式选择「安全模式」（推荐）
5. 点击提交验证，验证通过后即生效

消息收发

配置完成后，用户在微信服务号中发送的消息会自动转发到系统，AI 处理后通过客服消息 API 回复。

支持的消息类型：

• 文本消息：直接 AI 回复
• 语音消息：语音识别转文字后 AI 回复（需在微信后台开启语音识别）
• 图片/视频/文件：回复提示「暂不支持该消息类型」

模板消息推送

系统支持通过 API 主动向用户发送微信模板消息，适用于告警通知、任务提醒等场景。

权限说明：

使用方式：

• 通过 API 调用 POST /api/v1/wechat-mp/send-template（单发）或 POST /api/v1/wechat-mp/send-batch-template（批量）
• 通过 Javis Skill wechat-mp-notification 在对话中触发发送
• 目标用户必须已关注服务号且绑定系统账号

用户绑定

用户通过以下方式绑定微信服务号：

1. H5 网页授权登录：在微信内打开系统页面，授权后自动绑定服务号 OpenID
2. 消息补录：用户给服务号发消息时，系统自动通过 UnionID 关联已注册用户
3. 扫码登录：扫码登录用户需给服务号发一条消息触发补录

注意：微信 OpenID 按 AppID 隔离，扫码登录（开放平台）和 H5 登录（服务号）的 OpenID 不同。系统通过 UnionID 统一关联用户，wechatOpenId 字段仅存储服务号 OpenID。

常见问题

Q：不配置应用凭证也能同步用户吗？

A：可以，但只能匹配已通过该 IM 登录过的用户。配置凭证后可主动拉取通讯录，覆盖更多用户。

Q：同步会创建新用户吗？

A：不会。同步只匹配系统中已存在的用户，未匹配到的通讯录成员会被跳过。

Q：同步耗时多久？

A：取决于企业规模。部门较多时可能需要几十秒，系统会递归遍历所有部门并拉取用户。

Q：解除关联后已同步的成员会被移除吗？

A：不会。解除关联只清除企业绑定和凭证，已同步的成员保持不变。

Q：同步报 403 权限错误怎么办？

A：请检查两点：1）应用可见范围是否设置为全部员工；2）所需的通讯录权限是否已开通并发布。

Q：钉钉机器人发送/接收图片文件失败怎么办？

A：请检查：1）IM 机器人配置中是否已填写 App Key 和 App Secret；2）App Key 是否与企业内部应用凭证一致；3）图片是否超过 10MB、文件是否超过 50MB。

Q：微信服务号验证 URL 失败怎么办？

A：请检查：1）服务器地址 URL 是否可公网访问；2）Token 和 EncodingAESKey 是否与系统配置一致；3）是否选择了正确的加解密方式（推荐安全模式）。

Q：扫码登录的用户收不到模板消息？

A：扫码登录（开放平台）的 OpenID 与服务号 OpenID 不同。该用户需要给服务号发一条消息，系统会自动通过 UnionID 补录服务号 OpenID，之后即可正常接收模板消息。

Q：配置了服务号回调后，微信后台的自动回复失效了？

A：是的。开启回调 URL 后，微信平台的自动回复设置会失效，关注欢迎语需在系统侧的 IM 机器人配置中设置。

相关文档

• 组织管理
• 组织成员与架构
• IM 工作台免密登录
• IM 机器人集成
• 登录方式