回调信息速览
当微信平台触发用户聊天消息或系统事件时，服务端将以 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 | 同上 🔍 |
🔧 回调服务配置
1.
2.
3.
"验证回调地址是否可用" 测试数据4.
Key = $.Appid + $.Data.NewMsgId 进行消息去重。💡 注：通过 API 接口主动发送的消息不会触发回调，但手机端主动发送的消息会有回调，属于多端消息同步的 IM 机制。
❓ 常见问题
🤔 微信在线，为什么没有收到消息推送？
🙋 如何判断这条消息是不是"我自己"发出去的？
$.Data.FromUserName.string 与 $.Wxid，若一致则为本账号发出的消息。👥 如何判断消息是不是发在群里的？
FromUserName.string 以 @chatroom 结尾ToUserName.string 以 @chatroom 结尾🔍 如何提取群聊消息的真实发送者？
Content.string 格式通常为 wxid_xxxx:\n消息内容。通过切割 :\n 前的第一段内容，即可提取真实发言人的 wxid。🧐 没找到对应的消息类型怎么处理？
✅ 开发者最佳实践
1.
2.
msg.appmsg.type 进行二次判定3.
Appid + NewMsgId 作为唯一键4.
5.
修改于 2026-06-09 06:29:37