企业微信协议怎么接入？从环境准备到第一条消息的联调步骤

适合准备做企微客服、SCRM、聚合会话的后端同学。按可执行清单写，接口名以你方实际文档为准。

写在前面

对接协议能力时，最容易犯的错是：对着接口列表东点西点，登录态、回调、业务调用顺序乱了，排障成本很高。

更稳的做法是固定一条主路径：

准备环境 → 初始化实例 → 配置回调 → 扫码登录 → 发第一条消息 → 用回调验收

跑通后再扩展联系人、标签、群等模块。

一、接入前准备

没有环境时，可先在体验环境按模块浏览接口分类与示例，再按门户接入说明推进：

二、Step 1：初始化实例，拿到 uuid

首次接入一般先初始化，获得实例标识uuid。首次登录场景下，账号标识vid常为空。

保存好：

POST /wxwork/init Content-Type: application/json { "vid": "" }

• uuid：后续所有业务调用都带它
• 环境备注：对应哪个业务线 / 测试号

注意：多账号时每个在线号对应自己的uuid，不要混用。

三、Step 2：配置回调地址

把公网回调 URL 绑到当前实例（接口名常见类似设置回调地址）：

POST /wxwork/SetCallbackUrl Content-Type: application/json { "uuid": "你的uuid", "url": "https://your-domain.com/wx/callback" }

自检三步：

1. 用 Postman/curl 对本机回调打一发模拟请求
2. 确认网关没有截断 body
3. HTTPS 场景检查证书是否有效

回调入口建议「先应答、再异步处理」：

app.post('/wx/callback', async (req, res) => { const { uuid, type, json } = req.body res.status(200).send('ok') await enqueue({ uuid, type, json }) })

四、Step 3：扫码登录，持久化 vid

调用获取二维码接口（如getQrCode），用测试账号完成登录。

关注点：

• 新设备可能触发验证码或二次验证
• 登录成功后，回调里会出现登录成功类事件
• 登录成功务必持久化vid，供后续断线恢复

建议状态：

INIT → WAIT_QR → ONLINE 日志同时打： [PUSH] uuid=... type=登录相关... [CALL] uuid=... api=getQrCode ...

五、Step 4：发出第一条业务调用

登录成功后，用 同一个 uuid 发一条文本消息做验收（接口名以文档为准，例如发送文本）：

{ "uuid": "你的uuid", "to": "目标会话标识", "content": "接入联调测试消息" }

验收标准：

1. 接口返回成功
2. 企微会话里能看到消息
3. 回调侧能观察到对应消息或状态事件（按实际下发为准）

六、Step 5：用回调做闭环验收

不要只看「发送成功」。完整验收至少包括：

• 回调公网可达，有原始报文日志
• 能按type区分登录 / 消息等大类
• 消息类能读到msgtype
• 重复推送有幂等（如uuid + msgid）
• 同一uuid的调用日志与回调日志能对上

消息回调里若文档提到referid：0多为原消息，非0多为衍生状态（如已读），不要一律当新消息入库。

七、常见失败对照表

八、跑通后怎么扩展（别一次做完）

主路径通了再按模块加：

1. 客户与联系人、标签（SCRM）
2. 群运营
3. 媒体消息与文件下载
4. 多实例 + 断线自动恢复（vid+ 自动登录）

生产环境额外补：

• 每账号独立队列
• 在线数 / 重连成功率 / 回调失败率监控

小结

接入步骤可以记成一句话：

init 拿 uuid → 配回调 → 扫码拿 vid → 带 uuid 发第一条消息 → 用回调验收闭环。

顺序对了，后面扩 SCRM、客服、群运营会顺很多；顺序乱了，排障会成倍增加。