企业微信会话存档对接配置指南

📖 前言：写在开始之前

本功能用于将企业微信的聊天记录合规地同步至伙伴云。配置过程涉及域名解析、服务器证书及企业微信后台三方联调。

为了确保您一次性配置成功，请务必在动手前确认以下三条：

  1. 企微企业必须完成主体认证
    img

  2. 企微会话存档功能已开通：必须在企业微信后台购买或开启"会话内容存档"试用，并开启应用服务。

  3. 域名必须已备案：您准备使用的二级域名（如 qiwei.domain.com）的主域名(domain.com)必须已完成 ICP 备案且与企业微信的认证主体一致。

第一部分：基础知识加油站（非技术人员必读）

在操作前，建议花 1 分钟理解以下概念，这有助于您理解每一步操作的意义。

1. 什么是 CNAME 解析？

  • 通俗比喻：相当于设置"呼叫转移"
  • 原理：您在公司名下创建一个专属的二级域名（如 qiwei.domain.com），通过 CNAME 记录告诉互联网："访问这个地址时，请自动转接到伙伴云平台的服务器"
  • 为什么要做：这样既能使用您公司的自有域名，又能让数据准确流向我们的处理中心

2. 什么是 SSL 证书？

  • 通俗比喻：相当于给数据加装"防盗保险箱"
  • 原理：企业微信强制要求数据传输必须加密（HTTPS）。SSL 证书就是加密的密钥
  • 为什么选 Nginx 版：保险箱的锁芯有多种规格（如 IIS, Apache, Nginx），我们的平台服务器使用的是 Nginx 规格，所以下载证书时必须选对版本，否则钥匙插不进去

第二部分：详细配置步骤

步骤一：域名解析与证书准备

请登录您购买域名的云服务商后台（如腾讯云、阿里云、华为云等）。

1. 设置 CNAME 解析（指路牌）

  • 进入【DNS 解析 / 域名管理】
  • 找到您的主域名，点击"添加记录"，填写如下信息：

    • 记录类型：选择 CNAME（关键点）

    • 主机记录：自定义前缀，建议填 qiwei 或 chat

      • 示例：填 qiwei，完整域名即为 qiwei.域名.尾缀（一般是 .com / .cn）

    • 记录值：填写伙伴云提供的对接地址

      • 注意：通常为 hjpjtt.p.huobanbot.com，请以伙伴云企业后台-企业微信-会话存档配置页面提示为准
        img
        img

    • TTL：默认即可

  • 保存后，等待约几分钟生效

2. 获取 SSL 证书（安全锁）

  • 进入【SSL 证书 / 证书管理】控制台
  • 申请证书：
    • 若公司已有通配符证书（*.域名.尾缀），可直接使用
    • 若无，可申请一个单域名证书，绑定域名填写刚才设置的完整域名（如 qiwei.域名.尾缀）
    • 各云平台通常都有提供免费证书，3个月过期（需要更换），购买免费证书，然后创建证书即可
  • 下载证书：
    • 证书签发后，点击下载
    • 服务器类型选择：务必选择 Nginx 版本
  • 解压文件：
    • 解压后您将获得两个关键文件：
      • .key 文件（私钥）
      • .pem 文件（公钥/证书）
    • 操作提示：将文件上传至伙伴云企业后台对应位置

步骤二：企业微信后台配置（需企微管理员操作）

登录 企业微信管理后台

1. 开启功能（至关重要）

  • 路径：企业微信管理后台 → 高级功能 → 会话内容存档
  • 操作：点击购买或开启试用（通常有 30 天试用期）
  • 检查点：确保页面状态显示为"已开启"或"服务期内"，而非灰色的未开通状态

2. 获取对接凭证

  • Secret：在会话存档页面，点击查看 Secret，复制并保存
    • 检查点：在开通确认函审核中时，不支持获取Secret，此时无法完成配置，需等待审核通过
      img

步骤三：伙伴云企业后台配置

在伙伴云企业后台配置企业微信会话存档功能。

1. 填写企业信息

  • 企业ID：填入企业微信的企业 ID（在企微后台"我的企业"最下方查看）

2. 填写授权信息

  • Secret：填入企业微信-会话存档应用中获取的 Secret

3. 绑定域名与证书

  • 绑定域名：填入上面已经完成备案的完整域名（如 qiwei.域名.尾缀）
  • 上传证书：
    • 证书内容/公钥：上传步骤一中获取的 .pem 文件
    • 私钥：上传步骤一中获取的 .key 文件

4. 保存配置

  • 点击保存。保存后回调地址才能生效

步骤四：回到微信后台完成配置（需企微管理员操作）

完成回调和IP、公钥配置，将伙伴云企业后台的内容粘贴进来。

  • 设置接受事件服务器：点击设置将伙伴云企业后台提供的 URL、Token、EncodingAESKey 填入
  • 可信 IP 地址：点击设置，将伙伴云企业后台提供的服务器 IP 地址填入白名单
    • 注：如看到"1.117.102.251"无需填入
  • 加密公钥：填入伙伴云提供的消息加密公钥

第三部分：常见报错与排查指南 (Troubleshooting)

如果您在配置过程中遇到阻碍，请优先检查以下三个高频问题：

🔴 报错 1：域名主体校验不通过

  • 现象：配置域名时直接报错，无法保存
  • 原因：
    • 客户提供的域名未进行 ICP 备案，或者备案刚刚完成，数据尚未同步
    • 域名备案主体与企业微信认证主体不一致
  • 解决方案：
    1. 访问 工信部备案系统 查询该域名
    2. 若无记录，必须先备案（通常需 7-20 工作日），否则无法对接
    3. 若刚备案完，请等待 24 小时后再试
    4. 确认备案主体与企业微信认证主体一致

🔴 报错 2：会话授权 Secret 无效

  • 现象：Secret 明明是从后台复制的，但平台提示无效
  • 原因：企业微信后台的"会话内容存档"功能没有真正开启。仅生成 Secret 但不购买/开启服务，该 Secret 是无法被调用的
  • 解决方案：
    1. 回到企微后台 → 安全工具 → 会话内容存档
    2. 确认服务状态是否为"已开启"
    3. 如果已开启仍报错，尝试重置一个新的 Secret 再填入

🔴 报错 3：OpenApi调用失败 / 连接超时 / 证书错误

  • 现象：提示无法连接服务器或 SSL 握手失败
  • 原因：
    1. CNAME 解析未生效（或填了 A 记录）
    2. 证书上传错误（如上传了 Apache 版，或公私钥贴反了）
  • 解决方案：
    1. 在电脑终端输入 ping 您的二级域名，查看是否指向了网址
    2. 确认 Nginx 证书上传正确
    3. 企业微信后台刷新，尝试重新配置
2025-12-31 更新
7 次查看
Copyright © 伙伴云帮助中心 2025 版权所有
0