🔄 消息推送(回调)服务

文档说明

本文档用于说明微信 API 的 Webhook 事件回调接入方式、事件分类、公共字段、账号状态、普通消息、系统事件、异步回执以及完整 msgType 字典。

为了降低阅读压力，本文采用 「快速接入 + 常用示例 + 完整附录」 的结构：

前半部分适合首次接入时快速阅读。

后半部分适合开发过程中按 cmd / msgType 查询字段。

1. 快速接入

开发者只需要在控制台配置一个公网可访问的回调地址，系统会在账号状态变化、收到消息、系统事件发生或异步任务完成时，通过 HTTP POST 推送 JSON 数据。

1.1 支持的回调方式

回调方式	说明	适用场景
HTTP Webhook	在控制台配置接收 URL，系统通过 `POST application/json` 推送事件	SaaS 默认推荐方式
MQTT 长连接	订阅指定 Topic 接收实时事件流	私有化部署版本可用，具体以实际交付为准

1.2 接入重点

接入重点

回调地址必须公网可访问。

接收端需要在 3 秒内 返回 HTTP 200 OK。

不建议在回调请求里直接处理复杂业务，建议先入库或投递队列，再异步处理。

所有回调都可以通过 cmd 判断事件大类。

普通消息和系统事件需要继续根据 msgType 解析 msgData。

可使用 guid 区分来源设备或登录实例。

可使用 msgUniqueIdentifier、requestId 或 seq 做幂等去重。

2. 回调整体结构

2.1 标准回调外层结构

大多数回调数据都遵循以下结构：

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "guid": "a3318ad6-5544-4a4f-a1bb-2aa667b2ipad",
      "userId": "16885550001804",
      "requestId": "901efcada57ff16a469411b3e7f1b009",
      "customParam": "",
      "cmd": 15000,
      "msgType": 2,
      "msgUniqueIdentifier": "901efcada57ff16a469411b3e7f1b009",
      "seq": 1759125951405848,
      "timestamp": 1759125951,
      "msgData": {}
    }
  ]
}

2.2 公共字段说明

字段	类型	说明
`code`	number	外层状态码，`0` 通常表示成功
`msg`	string	外层说明文案
`data`	array	回调事件数组，通常每个元素是一条事件
`guid`	string	来源设备、登录实例或终端标识
`userId`	string / number	当前登录账号 ID
`requestId`	string	请求或异步任务 ID，异步回执场景下非常重要
`customParam`	string	自定义透传参数，具体以接口调用时传入为准
`cmd`	number	一级事件命令字，用于判断事件大类
`msgType`	number	二级消息类型，不同 `cmd` 下含义不同
`msgUniqueIdentifier`	string	消息唯一标识，可用于幂等去重
`seq`	number	消息序列号，可用于排序、去重或排查问题
`timestamp`	number	秒级时间戳
`msgData`	object / null	事件详细数据，不同 `msgType` 对应不同结构
`fromRoomId`	number	群聊 ID，群消息或群事件中常见
`senderId`	number	发送人 ID
`receiverId`	number	接收人 ID
`senderName`	string	发送人昵称或名称，可能为空
`base64RawData`	string	原始数据或扩展数据，部分事件使用

3. CMD 一级事件分类

系统根据 cmd 区分四大类基础业务场景。接收回调后，应先判断 cmd，再根据 msgType 做二级解析。

`cmd`	业务模块	触发场景说明	常用程度
`11016`	设备与账号状态	登录成功、离线、顶号、扫码状态变更、登录态过期等	高频
`15000`	普通消息数据流	文本、图片、文件、视频、语音、名片、位置、撤回、已读未读、群操作提示等	高频
`15500`	系统级事件通知	好友关系、标签、群组、朋友圈等系统事件	中高频
`20000`	异步 API 回执	文件上传、下载、群发任务等异步任务完成通知	中频

注意
部分群事件、会话事件或系统提示类事件，在实际回调中可能以 cmd=15000 的普通消息流形式投递。建议开发时以 实际回调中的 cmd 字段作为一级路由依据，再结合 msgType 做业务归类。

4. 推荐处理流程

4.1 后端处理建议

推荐流程：

接收 Webhook 请求。

校验 JSON 格式。

立即记录原始回调。

使用 msgUniqueIdentifier / requestId / seq 做幂等判断。

根据 cmd 分发到不同处理器。

根据 msgType 解析 msgData。

返回 HTTP 200 OK。

复杂业务异步处理。

4.2 伪代码示例

5. 常用事件快速示例

本章只保留接入时最常用的几类事件。完整 msgType 和 Payload 请看后面的附录。

5.1 登录成功 / 在线状态变化

{
  "cmd": 11016,
  "msgData": {
    "guid": "a3318ad6-5544-4a4f-a1bb-2aa667b2ipad",
    "msg": "login ok",
    "code": 11001,
    "status": 2,
    "serverReboot": false
  }
}

5.2 文本消息 / At 消息

{
  "cmd": 15000,
  "msgType": 2,
  "fromRoomId": 10791082136095292,
  "msgData": {
    "content": "@Alex 接口已经部署，@Bob 请复核",
    "atList": [
      { "userId": "788FFFFFF987664", "nickname": "Alex" },
      { "userId": "168BBBBBB0713881", "nickname": "Bob" }
    ]
  }
}

5.3 图片消息

{
  "cmd": 15000,
  "msgType": 14,
  "msgData": {
    "fileId": "30680201020461305f0201000...",
    "fileAeskey": "636638353836366233393432...",
    "fileMd5": "1e3cfce05a05bbfafbc6c80a3444f7a4",
    "fileName": "5LyB5Lia5b6u5L+h5oiq5Zu+...",
    "fileSize": 819,
    "imageHasHd": true
  }
}

5.4 文件消息

{
  "cmd": 15000,
  "msgType": 102,
  "msgData": {
    "fileAeskey": "38663530393138623030313335333533",
    "fileAuthkey": "v1_xxx...",
    "fileHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileMd5": "4df4e056138311f099819fbcfe14e7a1",
    "fileName": "ZG93bmxvYWRfeG1sX3ZpZC5tcDQ=",
    "fileSize": 319044
  }
}

5.5 好友申请通知

{
  "cmd": 15500,
  "msgType": 2357,
  "msgData": {
    "applyTime": 1759063191,
    "contactId": 7881300000061361,
    "contactNickname": "技术合作-张三",
    "contactType": "微信",
    "userId": 1970320000006843
  }
}

5.6 消息撤回通知

{
  "cmd": 15000,
  "msgType": 2063,
  "msgData": {
    "fromRoomId": 10920000000658,
    "revokeMsgUniqueIdentifier": "5982062000920770451",
    "revokeTime": 1776070536,
    "revokeUserId": 788130000000050
  }
}

5.7 消息已读通知

{
  "cmd": 15000,
  "msgType": 2001,
  "msgUniqueIdentifier": "CAQQnLb7rgYY1+C/qomAgAMgk+2roAM=",
  "senderId": 1688852365307991,
  "receiverId": 0,
  "timestamp": 1709103900,
  "msgData": null
}

6. 账号状态事件：`cmd=11016`

当终端设备的登录态、二维码扫描进度或网络状态发生变化时，会触发 cmd=11016 回调。此类事件适合用于构建多账号管理控制台、在线状态监控、掉线提醒等能力。

6.1 基础数据模型

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "guid": "a3318ad6-5544-4a4f-a1bb-2aa667b2ipad",
      "userId": "16885550001804",
      "requestId": "901efcada57ff16a469411b3e7f1b009",
      "cmd": 11016,
      "msgType": 0,
      "msgUniqueIdentifier": "901efcada57ff16a469411b3e7f1b009",
      "seq": 1759125951405848,
      "timestamp": 1759125951,
      "msgData": {
        "guid": "a3318ad6-5544-4a4f-a1bb-2aa667b2ipad",
        "msg": "login ok",
        "code": 11001,
        "status": 2,
        "serverReboot": false
      }
    }
  ]
}

6.2 `msgData.status` 状态说明

`status`	状态说明	业务建议
`0` / `-1`	离线	标记账号离线，暂停任务
`1`	已扫码，待手机端确认	前端提示用户在手机端确认
`2`	正常在线	标记账号可用
`3`	登录失败	提示重新扫码或检查环境
`4`	用户取消登录	结束当前扫码流程
`10`	已扫码确认，待输入 6 位辅助验证码	前端提示输入验证码

6.3 `msgData.code` 状态码说明

Code	状态定义	业务侧处理建议
`10000`	网络异常离线	系统会自动尝试重连，无需过度干预
`11001`	登录成功	标记设备在线，可开始下发自动化任务
`11002`	注销成功	释放该实例绑定的资源
`11013`	Session 刷新失败	凭证失效，需提示用户重新扫码授权
`11017`	其它端顶号	设备被挤下线，立刻停止该账号的业务任务
`11022`	手机端主动退出	用户取消授权，清理本地 Token 与缓存
`11023`	账号环境异常	触发风控或环境异常，建议人工介入重新登录
`11024`	登录态已过期	常规过期，需重新登录
`11025`	新设备安全验证	需手机端辅助扫码进行安全验证

7. 异步 API 回执事件：`cmd=20000`

由于部分 API 操作耗时较长，例如文件上传、文件下载、群发任务处理等，系统会采用异步架构。当异步任务完成后，会通过 cmd=20000 回调最终结果。

7.1 基础数据模型

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "guid": "a3318ad6-5544-4a4f-a1bb-2aa667b2ipad",
      "userId": "16885550001804",
      "requestId": "57a360fd-f920-4b4d-84c0-351ec1c63fe8",
      "cmd": 20000,
      "msgType": 0,
      "msgUniqueIdentifier": "cf3e312fbae0f4f9a20422609a203a66",
      "seq": 1759127702979498,
      "timestamp": 1759127702,
      "msgData": {
        "cloudUrl": "https://foo.com/0485.jpg"
      }
    }
  ]
}

7.2 处理重点

字段	说明
`requestId`	与发起异步 API 时返回的 ID 对应，用于关联原始业务请求
`msgUniqueIdentifier`	本次回执消息唯一标识，可用于幂等
`msgData`	异步任务执行结果，不同 API 对应不同结构
`cloudUrl`	文件类异步任务常见字段，表示上传后可访问地址

8. 普通消息事件：`cmd=15000`

cmd=15000 用于推送聊天消息、媒体消息、撤回、已读未读、部分群操作提示和会话事件。它是自动化客服、AI 回复、消息存档、业务 Agent 等场景的核心数据流。

8.1 普通消息基础模型

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "guid": "2cc69541-4e71-46e6-9389-65563e0da1c2",
      "cmd": 15000,
      "base64RawData": "CAMQ0e+yBA==",
      "fromRoomId": 10791082136095292,
      "isRoomNotice": 0,
      "msgData": null,
      "msgServerId": 1002114,
      "msgType": 2001,
      "msgUniqueIdentifier": "CAQQnLb7rgYY1+C/qomAgAMgk+2roAM=",
      "receiverId": 0,
      "senderId": 1688852365307991,
      "senderName": "",
      "timestamp": 1709103900
    }
  ]
}

8.2 常用普通消息类型

`msgType`	类型	常用程度	说明
`0` / `2`	文本消息	高频	普通文本、@ 消息
`7` / `14` / `101`	图片消息	高频	图片、高清图、缩略图
`20` / `15` / `102`	文件消息	高频	普通文件、大文件
`22` / `23` / `103`	视频消息	中频	视频文件、视频封面
`16`	语音消息	中频	语音片段，通常需按文件方式下载
`13`	链接消息	中频	图文外链卡片
`41`	名片消息	中频	个人名片或联系人名片
`78`	小程序消息	中频	小程序卡片
`2063`	撤回消息	高频	消息被撤回通知
`2001`	已读通知	中频	消息已读通知
`2005`	未读通知	中频	消息未读通知

9. 系统事件通知：`cmd=15500`

cmd=15500 主要用于推送联系人、标签、群组、朋友圈等系统级事件。开发时建议先根据 cmd=15500 进入系统事件处理器，再根据 msgType 判断具体事件。

9.1 系统事件基础模型

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "guid": "29348d4d-5ee4-46c4-d458-7ff764959f16",
      "userId": "1688850000000000",
      "requestId": "3088f0f7e621896ba62b193fe608311f",
      "customParam": "",
      "cmd": 15500,
      "msgServerId": 1001679,
      "msgType": 2357,
      "msgUniqueIdentifier": "contact_apply_friend_across_corp_1821945318",
      "senderId": 10030,
      "seq": 4649430,
      "timestamp": 1759063190,
      "msgData": {
        "applyTime": 1759063191,
        "contactId": 7881300000061361,
        "contactNickname": "nihao～",
        "contactType": "微信",
        "userId": 1970320000006843
      }
    }
  ]
}

9.2 常用系统事件类型

模块	`msgType`	事件说明
联系人	`2357` / `2132`	好友申请通知
联系人	`2131`	外部联系人信息变动或删除
联系人	`2313`	外部联系人加入黑名单
联系人	`2188`	内部联系人信息变动
联系人	`2104`	联系人免打扰 / 置顶
联系人	`2115`	联系人标记操作
标签	`2160` / `2161`	聊天标签变动 / 标签联系人变动
标签	`2185` / `2186`	企业标签 / 个人标签新增或删除
群组	`1001` / `1002` / `1003`	群名变更 / 成员新增 / 成员移除
群组	`1005` / `1006`	自己退群 / 群新增
群组	`1022` / `1023`	群主转让 / 群解散
群组	`1029` / `1043`	入群申请 / 群管理员变动
会话	`2055` / `2002`	清空聊天记录 / 删除聊天
朋友圈	`2215` / `517`	朋友圈变动 / 朋友圈推送

10. 附录 A：完整 `msgType` 字典

10.1 普通消息 `cmd=15000` 类型字典

`msgType`	`newMsgType`	消息类型	说明
`0`	`TEXT`	文本消息	普通文本
`2`	`TEXT_ALT`	文本 / At 消息	常见于群聊 @ 场景
`7`	`IMAGE`	图片消息	图片类型之一
`14`	`IMAGE_14`	图片消息	常见图片消息，可能包含 HD 原图信息
`101`	`IMAGE_101`	个微图片消息	可能包含 `fileThumbHttpUrl` / `fileMiddleHttpUrl` / `fileBigHttpUrl`
`22`	`VIDEO`	视频消息	视频类型之一，大视频场景也可能使用
`23`	`VIDEO_23`	视频消息	常见视频消息，可能包含封面和文件信息
`103`	`VIDEO_103`	个微视频消息	可能包含 `fileHttpUrl` / `coverImageHttpUrl`
`20`	`FILE_20`	文件消息	普通文件或大文件场景
`15`	`FILE`	文件消息	常见文件消息
`102`	`FILE_102`	个微文件消息	可能包含 `fileHttpUrl`
`29`	`GIF_29`	GIF 表情	动态表情包
`104`	`GIF_104`	GIF 表情	个微 GIF 表情
`6`	`LOCATION`	位置消息	经纬度、地址、标题
`13`	`LINK`	链接消息	图文外链卡片
`41`	`BUSINESS_CARD`	名片消息	个人名片、联系人卡片
`26`	`RED_PACKET`	红包通知	红包消息通知
`16`	`VOICE`	语音消息	语音文件，通常需下载处理
`78`	`MINI_PROGRAM`	小程序消息	小程序卡片
`123`	`MIXED`	图文混合消息	由多个子消息组成
`141`	`VIDEO_CHANNEL`	视频号消息	视频号卡片
`146`	`LIVE`	直播消息	直播卡片或直播相关消息
`213`	`SOLITAIRE`	群接龙	聊天内群接龙面板
`40`	`CALL_END`	通话结束	语音、视频通话挂断、拒接、超时等
`503`	`CALL_NOTIFY`	通话通知	发起、接通、未接等通话信令
`2166`	`CALL_NOTIFY_2166`	通话通知	另一类通话信令事件
`2001`	`READ_NOTIFY`	消息已读通知	消息已读状态变化
`2005`	`UNREAD_NOTIFY`	消息未读通知	消息未读状态变化
`2063`	`REVOKE`	消息撤回	消息被撤回通知

10.2 系统事件 `cmd=15500` 类型字典

模块	`msgType`	`newMsgType`	说明
联系人相关	`2131`	`CONTACT_EXTERNAL_CHANGE`	外部联系人信息（备注/描述/手机号）变动或删除通知
联系人相关	`2313`	`CONTACT_EXTERNAL_BLACKLIST`	外部联系人加入黑名单通知
联系人相关	`2188`	`CONTACT_INTERNAL_CHANGE`	内部联系人信息（备注/描述/手机号）变动通知
联系人相关	`2357`	`CONTACT_FRIEND_REQUEST_2357`	好友申请通知
联系人相关	`2132`	`CONTACT_FRIEND_REQUEST_2132`	好友申请通知
联系人相关	`2104`	`CONTACT_DND_TOP`	联系人免打扰 / 置顶通知
联系人相关	`2115`	`CONTACT_MARK`	联系人标记操作通知
标签相关	`2160`	`TAG_CHAT_CHANGE`	聊天标签变动通知
标签相关	`2161`	`TAG_CHAT_CONTACT_CHANGE`	聊天标签中的联系人变动通知
标签相关	`2185`	`TAG_CORP_ADD_DEL`	企业标签新增或删除回调通知
标签相关	`2186`	`TAG_PERSONAL_ADD_DEL`	个人标签新增或删除回调通知
群相关	`1001`	`GROUP_NAME_CHANGE`	群名变更通知
群相关	`1002`	`GROUP_MEMBER_ADD`	新增群成员通知
群相关	`1003`	`GROUP_MEMBER_REMOVE`	移除群成员通知
群相关	`1005`	`GROUP_MEMBER_QUIT`	当前账号自己退群通知
群相关	`1006`	`GROUP_CREATE`	群新增通知
群相关	`1011`	`GROUP_OPERATION_TIP`	群操作提示，例如聊天窗口灰色小字
群相关	`1022`	`GROUP_OWNER_TRANSFER`	转让群主通知
群相关	`1023`	`GROUP_DISMISS`	群解散通知
群相关	`1029`	`GROUP_INVITE_APPLY`	群成员邀请其他人进群申请
群相关	`1043`	`GROUP_ADMIN_CHANGE`	群管理员变动通知
群相关	`2118`	`GROUP_INFO_CHANGE`	群信息变动，例如群个微成员自己退群通知
会话消息	`2055`	`SESSION_CLEAR`	清空聊天记录通知
会话消息	`2002`	`SESSION_DELETE`	删除聊天通知
通话消息	`40`	`CALL_END`	通话结束通知，实际通常属于 `cmd=15000`
通话消息	`503` / `2166`	`CALL_NOTIFY` / `CALL_NOTIFY_2166`	语音、视频通话通知
朋友圈	`2215`	`MOMENT_CHANGE`	朋友圈变动通知
朋友圈	`517`	`MOMENT_PUSH`	朋友圈推送通知

11. 附录 B：常见 Payload 示例

说明：以下示例主要用于展示字段结构。为了便于阅读，部分长 URL、密钥、Base64、ID 已做省略或脱敏处理，实际字段以真实回调为准。

11.1 文本消息

{
  "cmd": 15000,
  "msgType": 2,
  "msgData": {
    "atList": [
      { "userId": "788FFFFFF987664", "nickname": "Alex" },
      { "userId": "168BBBBBB0713881", "nickname": "Bob" }
    ],
    "content": "@Alex aaa @Bob bbb"
  }
}

11.2 图片消息：`msgType=14`

{
  "cmd": 15000,
  "msgType": 14,
  "msgData": {
    "fileAeskey": "63663835383636623339343264346435",
    "fileId": "30680201020461305f0201000204445cc782...",
    "fileMd5": "1e3cfce05a05bbfafbc6c80a3444f7a4",
    "fileName": "5LyB5Lia5b6u5L+h5oiq5Zu+XzE2ODEz...",
    "fileSize": 819,
    "imageHasHd": true
  }
}

11.3 个微图片消息：`msgType=101`

{
  "cmd": 15000,
  "msgType": 101,
  "msgData": {
    "fileAeskey": "01bbda3d34aac6def0f9551979a7055e",
    "fileAuthkey": "v1_xxx...",
    "fileBigHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileBigSize": 254,
    "fileMiddleHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileMiddleSize": 254,
    "fileThumbHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileThumbSize": 739,
    "fileMd5": "a1aeb5166748cb66189c733e9b68f4a9",
    "fileName": "",
    "imageHasHd": false
  }
}

11.4 视频消息：`msgType=23`

{
  "cmd": 15000,
  "msgType": 23,
  "msgData": {
    "coverImageAeskey": "",
    "coverImageId": "306902010204623060020100...",
    "coverImageMd5": "fe3b08a566af99e7ab2c964464402ee2",
    "coverImageSize": 11284,
    "duration": 5,
    "fileAeskey": "38663530393138623030313335333533",
    "fileId": "306902010204623060020100...",
    "fileMd5": "4df4e056138311f099819fbcfe14e7a1",
    "fileName": "ZG93bmxvYWRfeG1sX3ZpZC5tcDQ=",
    "fileSize": 319044
  }
}

11.5 个微视频消息：`msgType=103`

{
  "cmd": 15000,
  "msgType": 103,
  "msgData": {
    "coverImageHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "coverImageSize": 11284,
    "duration": 5,
    "fileAeskey": "38663530393138623030313335333533",
    "fileAuthkey": "38663530393138623030313335333533",
    "fileHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileMd5": "4df4e056138311f099819fbcfe14e7a1",
    "fileName": "ZG93bmxvYWRfeG1sX3ZpZC5tcDQ=",
    "fileSize": 319044
  }
}

11.6 文件消息：`msgType=15`

{
  "cmd": 15000,
  "msgType": 15,
  "msgData": {
    "fileAeskey": "38663530393138623030313335333533",
    "fileId": "38663530393138623030313335333533",
    "fileMd5": "4df4e056138311f099819fbcfe14e7a1",
    "fileName": "ZG93bmxvYWRfeG1sX3ZpZC5tcDQ=",
    "fileNameExt": "excel",
    "fileSize": 319044
  }
}

11.7 个微文件消息：`msgType=102`

{
  "cmd": 15000,
  "msgType": 102,
  "msgData": {
    "fileAeskey": "38663530393138623030313335333533",
    "fileAuthkey": "38663530393138623030313335333533",
    "fileHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileMd5": "4df4e056138311f099819fbcfe14e7a1",
    "fileName": "ZG93bmxvYWRfeG1sX3ZpZC5tcDQ=",
    "fileSize": 319044
  }
}

11.8 GIF 消息：`msgType=29 / 104`

{
  "cmd": 15000,
  "msgType": 104,
  "msgData": {
    "fileHttpUrl": "https://imunion.weixin.qq.com/cgi-bin/mmae-bin/tpdownloadmedia?...",
    "fileMd5": "4df4e056138311f099819fbcfe14e7a1",
    "fileName": "ZG93bmxvYWRfeG1sX3ZpZC5tcDQ=",
    "fileSize": 319044
  }
}

11.9 位置消息：`msgType=6`

{
  "cmd": 15000,
  "msgType": 6,
  "msgData": {
    "address": "5LqR5Y2X55yB5b63...",
    "latitude": 24.085241,
    "longitude": 97.93544,
    "title": "",
    "zoom": 8
  }
}

11.10 链接消息：`msgType=13`

{
  "cmd": 15000,
  "msgType": 13,
  "msgData": {
    "desc": "NOaciDnml6UtNOaciDE55pel...",
    "iconUrl": "https://mmbiz.qpic.cn/mmbiz_jpg/...",
    "linkUrl": "http://mp.weixin.qq.com/s?...",
    "title": "5YWR56ev5YiG6LWia..."
  }
}

11.11 名片消息：`msgType=41`

{
  "cmd": 15000,
  "msgType": 41,
  "msgData": {
    "avatarUrl": "http://wx.qlogo.cn/mmhead/.../0",
    "corpId": 0,
    "corpName": "5b6u5L+h",
    "nickname": "eHhx",
    "realName": "",
    "shared_id": "78813*****"
  }
}

11.12 红包消息：`msgType=26`

{
  "cmd": 15000,
  "msgType": 26,
  "msgData": {
    "coverUrl1x": "http://dldir1.qq.com/qqcontacts/hongbao1x_20160413.png",
    "coverUrl2x": "http://dldir1.qq.com/qqcontacts/hongbao2x_20160413.png",
    "hongbaoSubtype": 3,
    "hongbaoType": 1,
    "lookWording": "来自*的红包，请进入手机版查看",
    "orderId": "1800008896202304147042530242005",
    "recvWording": "来自*的红包，请进入手机版领取",
    "ticket": "CMmt/ciXgIADEvIB...",
    "toIdList": ["1688*01"],
    "totalAmount": 1,
    "wishingContent": "5oGt5Zac5*Sn5Yip"
  }
}

11.13 语音消息：`msgType=16`

{
  "cmd": 15000,
  "msgType": 16,
  "msgData": {
    "fileAesKey": "7866746C766E6967706173667363786A",
    "fileId": "308183020...",
    "fileMd5": "18eee3d1cc8401c059fb2bd075bb1a44",
    "fileSize": 8934,
    "voiceTime": 5
  }
}

11.14 小程序消息：`msgType=78`

{
  "cmd": 15000,
  "msgType": 78,
  "msgData": {
    "appid": "wxbb58ee267a6",
    "coverImageAeskey": "79736C7...",
    "coverImageId": "306a0201020...",
    "coverImage_md5": "7d39f52a8f...",
    "coverImageSize": 29973,
    "desc": "扫码乘车出行",
    "iconUrl": "http://mmbiz.qpic.cn/mmbiz_png/...",
    "pagepath": "pages/qrcode/index.html?city_code=**&yktId=**",
    "title": "乘车码",
    "username": "gh_3cf62f4f1d52@app"
  }
}

11.15 图文混合消息：`msgType=123`

{
  "cmd": 15000,
  "msgType": 123,
  "msgData": [
    {
      "subMsgType": 14,
      "subMsgData": {
        "fileAeskey": "333936643...",
        "fileId": "30680201020461305f020100...",
        "fileMd5": "2c5817af1f2b45b9...",
        "fileName": "5LyB5Lia5b6...",
        "fileSize": 1467,
        "imageHasHd": true
      }
    },
    {
      "subMsgType": 2,
      "subMsgData": {
        "atList": null,
        "content": "NDQ="
      }
    }
  ]
}

11.16 视频号消息：`msgType=141`

{
  "cmd": 15000,
  "msgType": 141,
  "msgData": {
    "channelName": "56S+5Lqk5oKN5...",
    "channelUrl": "https://channels.weixin.qq.com/web/pages/feed?...",
    "coverUrl": "http://wxapp.tc.qq.com/...",
    "encodeData": "CAEQACL+GwAE9OmXBAAAA...",
    "headImgUrl": "http://wx.qlogo.cn/finderhead/.../0",
    "username": "5LiK5a*566r"
  }
}

11.17 消息已读通知：`msgType=2001`

{
  "cmd": 15000,
  "msgType": 2001,
  "base64RawData": "CAMQ0e+yBA==",
  "fromRoomId": 10791082136095292,
  "isRoomNotice": 0,
  "msgData": null,
  "msgServerId": 1002114,
  "msgUniqueIdentifier": "CAQQnLb7rgYY1+C/qomAgAMgk+2roAM=",
  "receiverId": 0,
  "senderId": 1688852365307991,
  "senderName": "",
  "timestamp": 1709103900
}

11.18 消息未读通知：`msgType=2005`

{
  "cmd": 15000,
  "msgType": 2005,
  "msgData": null,
  "msgUniqueIdentifier": "CAMQ2frkxgYYpMg0s+M7gE=",
  "timestamp": 1709103900
}

11.19 消息撤回通知：`msgType=2063`

{
  "cmd": 15000,
  "msgType": 2063,
  "msgData": {
    "fromRoomId": 10920000000658,
    "revokeMsgUniqueIdentifier": "5982062000920770451",
    "revokeTime": 1776070536,
    "revokeUserId": 788130000000050
  }
}

11.20 好友申请通知：`msgType=2357`

{
  "cmd": 15500,
  "msgType": 2357,
  "msgUniqueIdentifier": "contact_apply_friend_across_corp_1821945318",
  "msgData": {
    "applyTime": 1759063191,
    "contactId": 7881300000061361,
    "contactNickname": "nihao～",
    "contactType": "微信",
    "userId": 1970320000006843
  }
}

11.21 好友申请通知：`msgType=2132`

{
  "cmd": 15500,
  "msgType": 2132,
  "msgServerId": 1001677,
  "msgUniqueIdentifier": "1#queue5@21_98_245_170@8#1759063190|603963534",
  "senderId": 10030,
  "timestamp": 1759063190,
  "msgData": null
}

11.22 外部联系人变动：`msgType=2131`

{
  "cmd": 15500,
  "msgType": 2131,
  "msgServerId": 1001601,
  "msgUniqueIdentifier": "GAC_jZSwSYK4nIv",
  "senderId": 10030,
  "timestamp": 1759061799,
  "msgData": null
}

11.23 外部联系人加入黑名单：`msgType=2313`

{
  "cmd": 15500,
  "msgType": 2313,
  "msgData": {
    "base64RawData": ""
  }
}

11.24 内部联系人信息变动：`msgType=2188`

{
  "cmd": 15500,
  "msgType": 2188,
  "msgData": {
    "base64RawData": ""
  }
}

11.25 联系人免打扰 / 置顶：`msgType=2104`

{
  "cmd": 15500,
  "msgType": 2104,
  "msgData": {
    "base64RawData": ""
  }
}

11.26 联系人标记操作：`msgType=2115`

{
  "cmd": 15500,
  "msgType": 2115,
  "msgServerId": 1001823,
  "msgUniqueIdentifier": "QldP57zKTmiicaB",
  "senderId": 10008,
  "msgData": null
}

11.27 标签变动：`msgType=2160 / 2161 / 2185 / 2186`

{
  "cmd": 15500,
  "msgType": 2160,
  "msgData": {
    "base64RawData": ""
  }
}

11.28 群名变更：`msgType=1001`

{
  "cmd": 15000,
  "msgType": 1001,
  "fromRoomId": 239655862281126,
  "isRoomNotice": 0,
  "base64RawData": "MTExx",
  "msgData": {
    "changedMemberList": "MTExx"
  }
}

11.29 新增群成员：`msgType=1002`

{
  "cmd": 15000,
  "msgType": 1002,
  "fromRoomId": 239655862281126,
  "base64RawData": "MTY4ODg1NTk4OTY0MjQ4Nw==",
  "msgData": {
    "changedMemberList": "MTY4ODg1NTk4OTY0MjQ4Nw=="
  }
}

11.30 移除群成员：`msgType=1003`

{
  "cmd": 15000,
  "msgType": 1003,
  "fromRoomId": 239655862281126,
  "base64RawData": "MTY4ODg1NTk4OTY0MjQ4Nw==",
  "msgData": {
    "changedMemberList": "MTY4ODg1NTk4OTY0MjQ4Nw=="
  }
}

11.31 当前账号自己退群：`msgType=1005`

{
  "cmd": 15000,
  "msgType": 1005,
  "fromRoomId": 239655862281126,
  "msgData": {
    "changedMemberList": ""
  }
}

11.32 群新增通知：`msgType=1006`

{
  "cmd": 15000,
  "msgType": 1006,
  "fromRoomId": 239655862281126,
  "base64RawData": "MTY4ODg1NTk4OTY0MjQ4NzsxNj...",
  "msgData": {
    "changedMemberList": "MTY4ODg1NTk4OTY0MjQ4NzsxNj..."
  }
}

11.33 群主转让：`msgType=1022`

{
  "cmd": 15000,
  "msgType": 1022,
  "fromRoomId": 239655862281126,
  "base64RawData": "CiMInLvZs5CAgAMSGOW3suea...",
  "msgData": {
    "base64RawData": "CiMInLvZs5CAgAMSGOW3suea..."
  }
}

11.34 群解散：`msgType=1023`

{
  "cmd": 15000,
  "msgType": 1023,
  "fromRoomId": 261023134682181,
  "base64RawData": "CKXD3OKIAD",
  "msgData": {
    "base64RawData": "CKXD3OKIAD"
  }
}

11.35 群管理员变动：`msgType=1043`

{
  "cmd": 15000,
  "msgType": 1043,
  "fromRoomId": 261023134682181,
  "base64RawData": "CKXD3OKRgIADEJy72bOIADGAA=",
  "msgData": {
    "base64RawData": "CKXD3OKRgIADEJy72bOIADGAA="
  }
}

11.36 清空聊天记录：`msgType=2055`

{
  "cmd": 15000,
  "msgType": 2055,
  "fromRoomId": 0,
  "receiverId": 1688850000000000,
  "base64RawData": "CI+U==",
  "msgData": {
    "base64RawData": "CI+U=="
  }
}

11.37 删除聊天：`msgType=2002`

{
  "cmd": 15000,
  "msgType": 2002,
  "fromRoomId": 0,
  "receiverId": 1688850000000000,
  "base64RawData": "",
  "msgData": {
    "base64RawData": ""
  }
}

12. 接入建议与注意事项

12.1 推荐的业务处理方式

场景	推荐做法
接收回调	只做验签、落库、入队，快速返回 `200 OK`
消息去重	优先使用 `msgUniqueIdentifier`，异步回执可使用 `requestId`
消息排序	可参考 `timestamp` 与 `seq`
多账号区分	使用 `guid` 或 `userId` 建立账号映射
群聊识别	`fromRoomId` 大于 0 时一般表示群聊场景
文件处理	不建议同步下载文件，建议异步下载并设置重试
异常事件	未识别的 `cmd` / `msgType` 建议完整记录原始数据，方便后续兼容

12.2 Webhook 响应要求

接收端推荐返回：

或者：

12.3 不建议的做法

不建议在回调请求里直接调用 AI、大模型、CRM、ERP 等慢接口。

不建议在回调请求里同步下载图片、视频、文件。

不建议仅依赖 timestamp 做唯一判断。

不建议遇到未知 msgType 直接丢弃，应先记录原始数据。

不建议将业务成功与否作为 Webhook 签收成功与否，Webhook 应优先快速签收。

12.4 推荐入库字段

建议至少保存以下字段，便于后续排查和重放：

字段	说明
`id`	本地自增 ID
`guid`	来源设备
`userId`	当前账号
`cmd`	一级事件类型
`msgType`	二级事件类型
`msgUniqueIdentifier`	消息唯一标识
`requestId`	请求 ID / 异步任务 ID
`seq`	序列号
`timestamp`	事件时间
`fromRoomId`	群 ID
`senderId`	发送人
`receiverId`	接收人
`msgData`	解析后的消息内容
`rawPayload`	原始回调 JSON
`processedAt`	处理时间
`processStatus`	处理状态

13. 常见问题

Q1：应该先判断 `cmd` 还是 `msgType`？

建议先判断 cmd，再判断 msgType。cmd 是一级事件分类，msgType 是二级消息或事件类型。

Q2：为什么有些群事件是 `cmd=15000`？

部分群操作提示、会话操作或系统灰字消息，实际会通过普通消息流投递，因此可能看到 cmd=15000 搭配群相关 msgType。开发时以实际回调为准。

Q3：`msgData` 为什么有时是 `null`？

部分事件只需要通过 msgType、msgUniqueIdentifier、senderId、receiverId 等公共字段表达，不一定会携带结构化 msgData。

Q4：如何防止重复处理？

建议使用 msgUniqueIdentifier 做消息级幂等；异步 API 回执可使用 requestId 关联业务请求；必要时可以结合 seq 做二次校验。

Q5：文件、图片、视频应该怎么处理？

建议先保存消息记录，再异步下载或转存文件。不要在 Webhook 请求中同步下载大文件，避免超过 3 秒响应限制。

14. 版本建议

如果文档用于官网或控制台，建议拆成三类页面：

页面	用途
Webhook 快速接入	给首次接入客户看，保留接入流程和常用示例
msgType 速查表	给开发者快速查询类型
Payload 示例大全	给后端开发调试字段时查阅

当前文档已经按这个思路组织，可直接作为单页 Markdown 使用，也可以后续拆分成多页文档。

目录#

1. 快速接入#

1.1 支持的回调方式#

1.2 接入重点#

2. 回调整体结构#

2.1 标准回调外层结构#

2.2 公共字段说明#

3. CMD 一级事件分类#

4. 推荐处理流程#

4.1 后端处理建议#

4.2 伪代码示例#

5. 常用事件快速示例#

5.1 登录成功 / 在线状态变化#

5.2 文本消息 / At 消息#

5.3 图片消息#

5.4 文件消息#

5.5 好友申请通知#

5.6 消息撤回通知#

5.7 消息已读通知#

6. 账号状态事件：cmd=11016#

6.1 基础数据模型#

6.2 msgData.status 状态说明#

6.3 msgData.code 状态码说明#

7. 异步 API 回执事件：cmd=20000#

7.1 基础数据模型#

7.2 处理重点#

8. 普通消息事件：cmd=15000#

8.1 普通消息基础模型#

8.2 常用普通消息类型#

9. 系统事件通知：cmd=15500#

9.1 系统事件基础模型#

9.2 常用系统事件类型#

10. 附录 A：完整 msgType 字典#

10.1 普通消息 cmd=15000 类型字典#

10.2 系统事件 cmd=15500 类型字典#

11. 附录 B：常见 Payload 示例#

11.1 文本消息#

11.2 图片消息：msgType=14#

11.3 个微图片消息：msgType=101#

11.4 视频消息：msgType=23#

11.5 个微视频消息：msgType=103#

11.6 文件消息：msgType=15#

11.7 个微文件消息：msgType=102#

11.8 GIF 消息：msgType=29 / 104#

11.9 位置消息：msgType=6#

11.10 链接消息：msgType=13#

11.11 名片消息：msgType=41#

11.12 红包消息：msgType=26#

11.13 语音消息：msgType=16#

11.14 小程序消息：msgType=78#

11.15 图文混合消息：msgType=123#

11.16 视频号消息：msgType=141#

11.17 消息已读通知：msgType=2001#

11.18 消息未读通知：msgType=2005#

11.19 消息撤回通知：msgType=2063#

11.20 好友申请通知：msgType=2357#

11.21 好友申请通知：msgType=2132#

11.22 外部联系人变动：msgType=2131#

11.23 外部联系人加入黑名单：msgType=2313#

11.24 内部联系人信息变动：msgType=2188#

11.25 联系人免打扰 / 置顶：msgType=2104#

11.26 联系人标记操作：msgType=2115#

11.27 标签变动：msgType=2160 / 2161 / 2185 / 2186#

11.28 群名变更：msgType=1001#

11.29 新增群成员：msgType=1002#

11.30 移除群成员：msgType=1003#

11.31 当前账号自己退群：msgType=1005#

11.32 群新增通知：msgType=1006#

11.33 群主转让：msgType=1022#

11.34 群解散：msgType=1023#

11.35 群管理员变动：msgType=1043#

11.36 清空聊天记录：msgType=2055#

11.37 删除聊天：msgType=2002#

12. 接入建议与注意事项#

12.1 推荐的业务处理方式#

12.2 Webhook 响应要求#

12.3 不建议的做法#

12.4 推荐入库字段#

13. 常见问题#

目录