回调信息速览

当微信平台触发用户聊天消息或系统事件时，服务端将以 HTTP POST 方式实时推送标准 JSON 数据至开发者配置的回调接口

概述

项目	说明
推送方式	HTTP POST，Content-Type: `application/json`
响应时限	3 秒内必须返回响应（建议直接返回 `""` 或 HTTP 200）
去重键	`$.Appid + $.Data.NewMsgId`
判定路径	先判定外层 `TypeName` → 若为 `AddMsg` 再判定 `MsgType` → 最后解析 `Content.string`

消息统一结构

{
  "TypeName": "AddMsg",                          消息类型
  "Appid": "wx_e2PiMSX8ySDV6tQGroCDc",           设备ID
  "Wxid": "wxid_msxcysdpcdf18",                  所属微信的wxid
  "Data": {
    "MsgId": 1040357364,                         消息ID
    "FromUserName": { "string": "wxid_sender" }, 发送人的wxid
    "ToUserName": { "string": "wxid_receiver" }, 接收人的wxid
    "MsgType": 1,                                消息类型 1是文本消息
    "Content": { "string": "哈喽" },             消息内容
    "CreateTime": 1705041728,                    发送时间
    "PushContent": "通知栏内容",                  消息通知内容 
    "NewMsgId": 7353749793478223190,             消息ID2
    "MsgSeq": 640322095
  }
}

核心字段释义

字段	含义	示例 / 说明
`TypeName`	事件类型	`AddMsg` / `ModContacts` / `DelContacts` 🗑 / `Offline` / `FinderSyncMsg` / `FinderBypMsg`
`Appid`	设备标识	云 Pad 或 Mac 设备编号
`Wxid`	微信账号标识	当前接收消息的微信账号 wxid
`Data.MsgType`	消息类型编码	详见下表
`Data.Content.string`	消息内容 / XML	文本正文或各类消息的 XML 结构数据
`Data.NewMsgId`	消息唯一 ID	与 `Appid` 组合作为去重键
`Data.CreateTime`	消息时间戳	Unix 时间戳
`Data.FromUserName.string`	发送人标识	以 `@chatroom` 结尾表示群消息
`Data.ToUserName.string`	接收人标识	自己发出的群消息中，接收人以 `@chatroom` 结尾

MsgType 分类编码

基础消息（TypeName: AddMsg）

MsgType	消息类型	Content.string 说明
1	文本消息	文本正文
3	图片消息	图片 CDN XML，可直接用于图片转发
34	语音消息	语音下载 XML，部分含 base64 数据
37	好友请求	申请人验证信息，可用于自动同意接口
42	名片消息	被推荐人信息，可用于主动加人
43	视频消息	视频 CDN XML，可直接用于视频转发
47	Emoji 表情	表情 XML（含 MD5）
48	地理位置	位置 XML，可直接转发位置

复合 / 应用类消息（TypeName: AddMsg, MsgType: 49）

⚠ 当 MsgType = 49 时，必须解析 Content.string 中 XML 的 msg.appmsg.type：

appmsg.type	业务分类	备注说明
5	公众号 / 文章链接	需结合 XML `title` 区分群邀请链接
6	文件就绪（可下载）	文件发送完毕，可执行下载或转发
33 / 36	小程序卡片
57	引用回复消息
74	文件发送中（提示）	仅通知，此时不可下载
2000	微信转账	仅提醒
2001	微信红包	仅提醒
51	视频号	视频号内容分享

系统与通知指令（TypeName: AddMsg, MsgType: 10000 / 10002）

⚠ 此类消息需配合解析 Content.string 文本或 XML（sysmsg.type）判断：

指令类型	判断条件
消息撤回	`MsgType = 10002` 且 `sysmsg.type = revokemsg`
拍一拍	`MsgType = 10002` 且 `sysmsg.type = pat`
群公告	`sysmsg.type = mmchatroombarannouncememt`
群待办	`sysmsg.type = roomtoolstips`
被移出群聊 / 修改群名 / 更换群主	`MsgType = 10000`，Content 包含对应关键字
踢人 / 解散群聊	`MsgType = 10002` 且 `sysmsg.type = sysmsgtemplate`

账号与联系人变动（独立 TypeName）

变动事件	TypeName	Data 数据说明
资料变更 / 加粉成功	`ModContacts`	返回包含昵称、性别、地区的完整 Profile 对象
删好友 / 退出群聊	`DelContacts`	包含 `UserName` 对象（wxid 或 `@chatroom`）
节点掉线告警	`Offline`	节点离线，需立即告警并重新扫码登录

视频号专属事件

事件	TypeName	处理建议
互动（点赞 / 评论 / 关注）	`FinderSyncMsg`	收到通知后，调用获取消息列表接口查详情
💬 收到私信	`FinderBypMsg`	同上

回调服务配置

配置路径：登录 API 控制台 → 左侧菜单【访问控制】→【配置回调地址】。

全局生效：该 Token 下登录的所有微信账号收到的消息，都会自动推送到回调接口。

接口要求：

回调地址必须公网可达

3 秒内返回响应（建议异步队列处理业务逻辑）

保存时网关会发送 "验证回调地址是否可用" 测试数据

去重：必须使用 Key = $.Appid + $.Data.NewMsgId 进行消息去重。

注：通过 API 接口主动发送的消息不会触发回调，但手机端主动发送的消息会有回调，属于多端消息同步的 IM 机制。

常见问题

微信在线，为什么没有收到消息推送？

先用 Apifox 或 Postman 向接收地址发送测试消息。若接口无法接收，检查防火墙、网关配置或代码拦截器。若能收到手动测试但收不到微信推送，请联系技术客服排查节点状态。

如何判断这条消息是不是"我自己"发出去的？

对比 $.Data.FromUserName.string 与 $.Wxid，若一致则为本账号发出的消息。

如何判断消息是不是发在群里的？

别人发的：FromUserName.string 以 @chatroom 结尾

自己发的：ToUserName.string 以 @chatroom 结尾

如何提取群聊消息的真实发送者？

群消息的 Content.string 格式通常为 wxid_xxxx:\n消息内容。通过切割 :\n 前的第一段内容，即可提取真实发言人的 wxid。

没找到对应的消息类型怎么处理？

请使用手机微信，主动向登录了 API 节点的账号发送该类型消息，然后在回调接收端查看实际推送的原始 JSON 结构。

开发者最佳实践

优先判定 MsgType 进行一级分流，避免无效解析

MsgType = 49 时再解析内部 XML，提取 msg.appmsg.type 进行二次判定

全部推送消息务必做好去重处理，使用 Appid + NewMsgId 作为唯一键

XML 数据为核心内容不可遗漏，CDN 信息、MD5、Base64 等均在其中

以 NewMsgId 作为消息唯一标识，其唯一性和稳定性优于 MsgId

概述#

消息统一结构#

核心字段释义#

MsgType 分类编码#

基础消息（TypeName: AddMsg）#

复合 / 应用类消息（TypeName: AddMsg, MsgType: 49）#

系统与通知指令（TypeName: AddMsg, MsgType: 10000 / 10002）#

账号与联系人变动（独立 TypeName）#

视频号专属事件#

回调服务配置#

常见问题#

微信在线，为什么没有收到消息推送？#

如何判断这条消息是不是"我自己"发出去的？#

如何判断消息是不是发在群里的？#

如何提取群聊消息的真实发送者？#

没找到对应的消息类型怎么处理？#

开发者最佳实践#

概述