企微配置
加载中...
同步管理
-
加载中...
消息通知平台
加载中...
企微 API 调用日志
每次调用企微开放平台接口均会记录。失败时会给出诊断说明，便于定位 Secret 类型错误、48002 无权限、可见范围等问题。
-
| 时间 | 配置 | 接口 | 状态 | 诊断说明 | 请求 | 响应 | 耗时 |
|---|---|---|---|---|---|---|---|
| 切换到本 Tab 或点击刷新加载 | |||||||
企微对接配置说明
功能概览：本系统通过企业微信实现学员加微追踪、客户同步、获客链接管理及自建应用消息通知。
- 企微配置：凭证、回调、客户同步（手动 + 每 15 分钟自动）
- 企微客户：外部联系人列表与学员匹配
- 获客助手链接：同步并回填老师获客链接
- 企微员工：从通讯录拉取员工信息到本地，自动关联老师
- 消息通知平台：自建应用收发消息
配置流程总览
- 企微管理后台开通「客户联系」并获取 Secret
- 创建自建应用，获取 AgentId + Secret，配置 API 权限
- 在本系统「企微配置」填写凭证并保存
- 配置回调 URL（客户联系 + 自建应用，Token/AESKey 保持一致）
- 「老师管理」填写每位老师的企微 UserID
- 执行同步，在「企微客户 / 获客链接 / 企微员工」查看结果
一、企微管理后台准备（需管理员权限）
登录 企业微信管理后台，按顺序完成以下配置：
1.1 获取企业 ID（Corp ID）
- 管理后台 → 我的企业 → 企业信息
- 复制 企业 ID，填入本系统「Corp ID」
1.2 开通客户联系并获取 Secret（重要）
常见错误：把「自建应用 Secret」填进「客户联系 Secret」——gettoken 可能成功，但同步/测试会报
48002 api forbidden。
两个 Secret 来源不同，不可混用。
新版企微：部分企业不再单独提供「客户联系 Secret」。只需配置自建应用 Secret + AgentId，
并在「客户联系 → 客户 → API → 可调用接口的应用」中添加该应用。本系统会在客户联系 Secret 无效时自动改用自建应用 Secret。
- 管理后台 → 客户联系 → 客户
- 若未开通，按引导开通「客户联系」功能
- 进入 API 页面 → 复制该页专用的 Secret（通常约 43 字符）
- 复制 Secret，填入本系统「客户联系 Secret」
- 确认 API 权限包含：外部联系人读取、获客链接、联系客户统计
Secret 对照表：
| 字段 | 正确来源 | 错误来源（会 48002） |
|---|---|---|
| 客户联系 Secret | 客户联系 → 客户 → API → Secret | 应用管理 → 自建应用 → Secret |
| 自建应用 Secret | 应用管理 → 自建应用 → Secret | 填到客户联系 Secret 字段 |
1.3 创建自建应用（消息通知用）
- 管理后台 → 应用管理 → 应用 → 创建应用
- 填写应用名称、Logo，选择可见范围（需包含相关老师成员）
- 进入应用详情，记录 AgentId 和 Secret
- 在应用权限中勾选：客户联系（只读即可）、通讯录（只读，用于拉取员工）、发送消息到成员
1.4 准备回调参数
Token 和 EncodingAESKey 由你自行设定（与企微后台、本系统三处保持一致）：
- Token：英文/数字，建议 32 位
- EncodingAESKey：43 位，可在企微后台点「随机生成」
| 能力 | 用途 | 获取凭证 |
|---|---|---|
| 客户联系 | 同步外部联系人、获客链接 | 客户联系 Secret |
| 自建应用 | 拉取通讯录员工、接收/发送应用消息 | AgentId + 应用 Secret |
| 回调配置 | 接收加微/删微/消息事件 | Token + EncodingAESKey |
二、在本系统新增企微配置
进入 功能管理 → 点击「+ 新增配置」，填写下表字段：
| 字段 | 说明 | 从哪里获取 |
|---|---|---|
| Corp ID | 企业 ID | 管理后台 → 我的企业 → 企业信息 |
| 客户联系 Secret | 用于拉取客户与获客链接 | 管理后台 → 客户联系 → 客户 → API → Secret |
| 自建应用 AgentId | 应用数字 ID | 应用详情页 → AgentId |
| 自建应用 Secret | 用于发送应用消息 | 应用详情页 → Secret |
| 回调 Token | 回调验签令牌 | 自行设置（英文/数字，建议 32 位） |
| EncodingAESKey | 回调消息加解密密钥 | 自行设置或点「随机生成」（43 位） |
| 同步间隔 | 定时拉取客户频率 | 默认 15 分钟 |
新建配置后自动设为「活跃」；全局仅一条活跃配置生效。
三、配置回调 URL（重要）
每个企微配置有独立回调路径，创建后在配置列表「回调路径」列可查看。格式为：
加载中...
客户联系回调（外部联系人变更）：
- 管理后台 → 客户联系 → 客户 → 回调配置
- URL 填上方完整地址（将
{配置ID}换为实际数字 ID） - Token、EncodingAESKey 与本系统配置保持一致
- 点击保存并验证 URL（需服务已部署且可公网访问）
自建应用接收消息（消息通知平台）：
- 管理后台 → 应用管理 → 自建 → 选择应用 → 接收消息
- URL 填相同回调地址，Token/AESKey 一致
- 开启接收消息，保存并验证
注意：回调 URL 必须是 HTTPS 公网地址，本地开发需用内网穿透（如 ngrok）。多套企微配置时，每个 corp 在各自后台配置带对应
配置ID 的 URL。
四、配置老师与获客链接
- 进入 老师管理，为每位老师填写
企微 UserID（管理后台 → 通讯录 → 成员详情） - 在 企微配置 点击「立即同步」拉取获客链接，系统会尝试自动回填老师的「获客链接」
- 同步结果可在 获客助手链接 菜单查看；也可手动填写老师获客链接
- 落地页会自动拼接
state=学员ID便于精确追踪
五、客户同步与学员匹配
- 手动同步：企微配置 → 同步管理 →「立即同步」
- 自动同步：每 15 分钟（或配置的间隔）自动执行
- 客户列表：同步后在 企微客户 菜单查看与筛选
- 匹配规则：优先「学员手机号 + 所属老师」，无命中再按手机号 fallback
- 删微识别：同步或回调发现客户已删除 → 标记学员
wecom_deleted - 前提：企微客户备注中需有手机号，否则无法自动匹配（同步日志会统计未匹配数）
六、企微员工同步
菜单路径：企微运营 → 企微员工
- 功能：从企微通讯录拉取员工姓名、UserID、部门、手机号等到本地
- 手动同步：点击「拉取员工」
- 关联老师：若老师管理中已填写相同
企微 UserID，会自动关联 - 前提：自建应用需开通「通讯录只读」权限；未配置时会降级拉取客户联系成员列表（字段较少）
七、消息通知平台
- 收到消息：成员向自建应用发消息 → 自动出现在「消息通知平台」列表
- 发送消息：点击「发送消息」，填写成员 UserID（多个用
|分隔） - 支持文本 / Markdown；发送记录可在列表中查看成功/失败状态
- 自建应用需有「发送消息到成员」权限，且接收人需在应用可见范围内
八、验证配置是否成功
- 配置列表 →「测试客户联系」：验证客户联系 Secret 是否正确
- 配置列表 →「测试自建应用」：验证 AgentId + 应用 Secret 是否正确
- 执行一次「立即同步」，查看同步日志是否有客户数/匹配数
- 在「企微员工」执行拉取，确认有员工记录
- 在企微后台完成回调 URL 验证（显示验证成功）
九、常见问题
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 回调 URL 验证失败 | Token/AESKey 不一致或服务不可访问 | 核对密钥、确认 HTTPS 公网可达 |
| 40001 invalid credential | Corp ID 与 Secret 不匹配 | 确认 Secret 来自「客户联系 → 客户 → API」，重新保存 |
| 48002 api forbidden | 凭证有效但接口无权限 | 客户联系 → 客户 → API 确认权限；未开通获客助手则获客链接会跳过；老师需配置 UserID |
| 同步客户数为 0 | 老师未填 UserID 或 Secret 错误 | 检查老师配置，测试客户联系连通性 |
| 学员无法匹配 | 企微客户备注无手机号 | 在企微侧补充备注手机号 |
| 发送消息失败 | 应用 Secret/AgentId 错误或成员不在可见范围 | 测试自建应用，检查应用权限与可见范围 |
| 员工信息不完整 | 未开通通讯录权限或未配置自建应用 | 配置 AgentId/Secret 并勾选通讯录只读 |
| 收不到应用消息 | 未开启接收消息或回调未配置 | 按第三节配置自建应用回调 |
相关文档：
企微开发文档 ·
本系统 API 文档