消息订阅：当您需要接收好友消息、群聊变动、或进行各类自动化交互业务时（如根据关键词回复、踢人、拉群等），需要开启消息回调服务。
WechatApi 会将触发的事件以 POST application/json 的形式，实时推送到您配置的接口地址。
📦 核心事件速查表#
消息类型判定路径：先判定外层 TypeName，如果是 AddMsg，再判定内层 MsgType。
1. 基础消息 (TypeName: AddMsg)#
| 消息类型 | MsgType | $.Data.Content.string (核心内容) |
|---|
| 文本消息 | 1 | 文本正文 |
| 图片消息 | 3 | 图片 CDN XML (可免上传直接用于【图片转发】) |
| 语音消息 | 34 | 语音下载 XML |
| 好友请求 | 37 | 申请人验证信息 (可用于【自动同意】接口) |
| 名片消息 | 42 | 被推荐人信息 (可用于主动加人) |
| 视频消息 | 43 | 视频 CDN XML (可免上传直接用于【视频转发】) |
| Emoji表情 | 47 | 表情 XML (含 MD5) |
| 地理位置 | 48 | 位置 XML (可直接转发位置) |
2. 复合/应用类消息 (TypeName: AddMsg , MsgType: 49)#
⚠️ 当 MsgType = 49 时，必须解析 Content.string 中 XML 的 msg.appmsg.type：| 业务分类 | appmsg.type | 备注说明 |
|---|
| 公众号/文章链接 | 5 | 需结合 XML title 区分是否为群邀请链接 |
| 文件就绪(可下载) | 6 | 文件已发送完毕，可执行下载或转发 |
| 小程序卡片 | 33 或 36 | |
| 引用回复消息 | 57 | 引用消息回复参考发送APPMSG消息 |
| 文件发送中(提示) | 74 | 仅提示对方在发文件，此时不可下载 |
| 微信转账 | 2000 | 仅提醒 |
| 微信红包 | 2001 | 仅提醒 |
3. 系统与通知指令 (TypeName: AddMsg , MsgType: 10000 / 10002)#
⚠️ 此类消息需配合解析 Content.string 文本或 XML (sysmsg.type) 判断：| 指令类型 | 判断条件 |
|---|
| 消息撤回 | MsgType = 10002 且 sysmsg.type = revokemsg |
| 拍一拍 | MsgType = 10002 且 sysmsg.type = pat |
| 群变动 | sysmsg.type 为 mmchatroombarannouncememt(公告) 或 roomtoolstips(待办) |
| 群管理 | 被移出群聊/修改群名 (MsgType=10000)；解散/踢人 (MsgType=10002+sysmsgtemplate) |
4. 账号与联系人变动 (独立 TypeName)#
| 变动事件 | TypeName | Data 数据说明 |
|---|
| 资料变更/加粉成功 | ModContacts | 返回包含昵称、性别、地区的完整 Profile 对象 |
| 删好友/退出群聊 | DelContacts | 包含 UserName 对象 (wxid 或 @chatroom) |
| ⚠️ 节点掉线告警 | Offline | 节点离线。需立即告警并重新扫码登录 |
5. 视频号专属事件#
| 事件 | TypeName | 处理建议 |
|---|
| 互动(点赞/评论) | FinderSyncMsg | 收到通知后，调用【获取消息列表接口】查详情 |
| 收到私信 | FinderBypMsg | 同上 |
示例报文参考#
{
"TypeName": "AddMsg",
"Appid": "wx_xxxxxxxx",
"Wxid": "wxid_xxxxxx",
"Data": {
"NewMsgId": 1234567,
"MsgType": 1,
"FromUserName": { "string": "wxid_sender" },
"ToUserName": { "string": "wxid_receiver" },
"Content": { "string": "消息正文/XML数据" }
}
}
完整报文参考#
