适合人群正在做企微客服、SCRM、聚合会话的后端同学 说明下文按「调用 回调」双通道思路整理字段名以你实际对接文档为准。前言很多人联调时卡在同一类问题上回调能收到但消息重复入库已读、撤回被当成新消息文本还行图片/文件处理到一半就乱了本文把 消息回调的分流和去重 说清楚方便你一次搭稳。先认信封再看内容回调入口通常是一个公网 HTTP 接口。常见结构类似{uuid:实例标识,type:事件大类,json:{msgtype:文本或其他,referid:0}}建议处理顺序固定成三步校验 uuid确认是哪个在线账号按 type 做大类路由登录 / 联系人 / 群 / 消息消息类再按 msgtype 细分并做幂等type 大类别用一个巨大 ifasync functiondispatch(uuid,type,json){if(isLoginEvent(type))returnhandleLogin(uuid,json)if(isContactEvent(type))returnhandleContact(uuid,json)if(isRoomEvent(type))returnhandleRoom(uuid,json)if(isMessageEvent(type))returnhandleMessage(uuid,json)returnsaveUnknown(uuid,type,json)// 先落日志别直接 500}原则登录态、联系人、群、消息 分处理器未知 type 先存原始报文避免对方重试把你打挂3. msgtype按类型处理不要一刀切入库类型 建议文本直接进会话表 / 推坐席图片/文件先存元数据异步下载语音/视频注意时长与转码任务撤回/系统提醒更新状态不当新会话文件类还要区分来源外部文件 vs 企微内部/CDN下载接口可能不同别写死成一套。referid已读不是新消息联调里常见约定以文档为准referid 0多为原消息referid ≠ 0多为衍生事件例如已读相关错误写法// 危险每条回调都 insertdb.insertMessage(json)更稳妥if(Number(json.referid||0)0){awaitupsertOriginalMessage(json)}else{awaitapplyDerivedEvent(json)// 已读/状态更新}幂等用唯一键挡住重复推送至少选一个稳定键uuid msgid或 uuid type 关键去重字段推荐两层存储原始事件表可重复保真便于重放业务消息表唯一索引保证逻辑上不重复回调入口尽量快速返回成功再异步处理降低对方超时重推概率。最小可运行骨架/callback├─ 快速 ACK├─ 写 events_raw├─ 按 type 路由└─ 消息类msgtype referid 幂等本地可用内网穿透验证公网可达上线后重点盯回调失败率、重复率、处理耗时。和双通道怎么配合回调只解决「收事件」。完整业务还要主动调用发消息、建群、客户相关动作回调下发消息与状态回流两边都用同一个实例标识常见为 uuid日志里同时打调用与推送排查会轻松很多。模块摘要与场景说明见项目门户完整接口与示例可在体验环境查阅体验环境https://www.wecomkit.cn/小结消息回调想稳抓住三件事type 分流msgtype 分类处理referid 幂等先把这三层搭对再扩媒体类型和业务规则会少走很多回头路。
