# Webhook 接收消息 “响应体” 格式规范 · v1
Webhook 接收消息 “响应体” 格式规范 · v1
本文定义 你方接收 的 HTTP POST 请求体（平台 → 你）的结构及字段含义，便于解析、验签、入库与去重。
1) 顶层结构
{
"Data": {
"messages": [/* Message */]
},
"IsSelf": false,
"MessageType": "sync_message",
"Signature": "string",
"Timestamp": 1757156304,
"Wxid": "wxid_xxxxxxxxx"
}| 字段 | 类型 | 说明 |
|---|---|---|
MessageType | string | 事件类型，样例：sync_message（消息同步推送） |
Signature | string | 事件签名（按双方约定校验） |
Timestamp | number | 事件时间（秒） |
Wxid | string | 当前账号/机器人标识 |
Data.messages | Message[] | 本次推送的消息数组 |
IsSelf | boolean | 顶层是否由自己触发（以每条 isSelf 为准） |
2) Message 通用结构
{
"createTime": 1757156304,
"fromUser": "wxid_xxxxxxxxx",
"fromNick": "可选",
"toUser": "filehelper",
"isSelf": true,
"msgId": 409021811,
"newMsgId": 293044386915895552,
"msgType": 51,
"text": "可选",
"pushContent": "可选",
"rawContent": "可选（XML 原文）",
"voice": { /* 可选：语音负载 */ },
"image": { /* 可选：图片负载 */ }
}| 字段 | 类型 | 说明 |
|---|---|---|
createTime | number | 消息时间（秒） |
fromUser | string | 发送方；群聊形如 xxx@chatroom |
fromNick | string? | 群内展示昵称 |
toUser | string | 接收方（当前号/助手或 filehelper） |
isSelf | boolean | 是否自己发送 |
msgId | number | 端侧短 ID |
newMsgId | number | 服务器长 ID（推荐去重主键） |
msgType | number | 消息类型（见下） |
text/pushContent/rawContent/voice/image | — | 按类型出现 |
3) msgType 枚举与负载
msgType | 名称 | 负载字段 | 说明 |
|---|---|---|---|
| 1 | 文本 | text（可伴随 pushContent） | 群文本常含“{senderWxid}:\n内 容”前缀 |
| 3 | 图片 | image | 见 3.2 |
| 34 | 语音 | voice | 见 3.1 |
| 43 | 视频 | rawContent（XML <videomsg/>） | 见 3.3 |
| 49 | 链接/AppMsg | rawContent（XML <appmsg>...</appmsg>） | 见 3.4 |
| 51 | 同步/操作 | rawContent（XML <op id='...'>） | 见 3.5（如 lastMessage 游标） |
未知类型：请原样保存 rawContent，标记为unknown以便离线解析。
3.1 语音（34）
"voice": {
"voiceurl": "string",
"voicelength": 1660, // 毫秒
"voiceformat": 4, // 编码枚举（如 SILK/AMR）
"aeskey": "string",
"length": "2346", // 字节数（字符串）
"base64": "可选，大段数据"
}voiceurl + aeskey 拉取，避免 base64 撑大请求体。3.2 图片（3）
"image": {
"cdnthumburl": "string",
"cdnthumbaeskey": "string",
"cdnthumbwidth": "55",
"cdnthumbheight": "120",
"cdnmidimgurl": "string",
"length": "44692",
"encryver": "1"
}3.3 视频（43 · 原文在 rawContent）
<msg>
<videomsg
aeskey="string"
cdnvideourl="string"
playlength="22"
length="2541114"
cdnthumburl="string"
cdnthumbaeskey="string"
cdnthumbwidth="288"
cdnthumbheight="162"
/>
</msg>可在你方解析为： "video": { "url": "string", "aeskey": "string", "duration": 22, "size": 2541114, "thumb": { "url": "string", "aeskey": "string", "width": 288, "height": 162 } }
3.4 链接/AppMsg（49 · 原文在 rawContent）
title、des、url、sourcedisplayname/sourceusername、appattach.cdnthumburl、webviewshared.shareUrlOpen/shareUrlOriginal 等。解析后可落标准结构： "link": { "title": "string", "description": "string", "url": "https://...", "source": { "name": "string", "username": "string" }, "thumb": { "url": "string", "width": 120, "height": 120 } }
3.5 同步/操作（51 · 原文在 rawContent）
<msg>
<op id='5'>
<username>filehelper</username>
<name>lastMessage</name>
<arg>{"messageSvrId":"7129875...","MsgCreateTime":"1757156311"}</arg>
</op>
</msg>可解析为： "op": { "id": 5, "username": "filehelper", "name": "lastMessage", "arg": { "messageSvrId": "string", "MsgCreateTime": "string" } }
4) 群聊文本拆分规则
fromUser 以 @chatroom 结尾，且 text 符合：^([^:
]+):
([\s\S]*)$sender（原始发送者 wxid）content（正文）"text": { "sender": "wxid_xxx", "content": "正文", "preview": "pushContent 可选" }5) 去重与顺序
newMsgId（优先）createTime 升序，若相同再比 newMsgIdmsgType=51 的 op(name=lastMessage) 可作为断点续传位点6) 安全与大对象获取
Signature + Timestamp + 原文体按约定算法验签。base64。rawContent 原文以便离线修复。7) 最小示例
文本（群）
{
"createTime": 1757156327,
"fromUser": "39325196004@chatroom",
"fromNick": "小k",
"toUser": "wxid_xxxxxxxxx",
"isSelf": false,
"msgId": 1989960994,
"newMsgId": 4854487905432113152,
"msgType": 1,
"pushContent": "小k : 以下岗位均有hc...",
"text": "wxid_owbd6qwjb66t22:
以下岗位均有hc🙌🏻 ..."
}图片
{
"createTime": 1757156391,
"fromUser": "wxid_xxxxxxxxx",
"toUser": "filehelper",
"isSelf": true,
"msgId": 577452582,
"newMsgId": 3401743659875373056,
"msgType": 3,
"image": {
"cdnthumburl": "30570201...",
"cdnthumbaeskey": "d4c09a...",
"cdnthumbwidth": "55",
"cdnthumbheight": "120",
"length": "44692"
}
}语音
{
"createTime": 1757156306,
"fromUser": "wxid_xxxxxxxxx",
"toUser": "filehelper",
"isSelf": true,
"msgId": 417747429,
"newMsgId": 6684617047514877952,
"msgType": 34,
"voice": {
"voiceurl": "30520201...",
"voicelength": 1660,
"voiceformat": 4,
"aeskey": "5f7f...",
"length": "2346"
}
}视频
{
"createTime": 1757156313,
"fromUser": "wxid_xxxxxxxxx",
"toUser": "filehelper",
"isSelf": true,
"msgId": 492364546,
"newMsgId": 7129875397130150912,
"msgType": 43,
"rawContent": "<?xml version=\"1.0\"><msg><videomsg ... /></msg>"
}链接/AppMsg
{
"createTime": 1757156329,
"fromUser": "39325196004@chatroom",
"fromNick": "小k",
"toUser": "wxid_xxxxxxxxx",
"isSelf": false,
"msgId": 849167,
"newMsgId": 345631163411640832,
"msgType": 49,
"rawContent": "<?xml version=\"1.0\"><msg><appmsg>...</appmsg></msg>"
}同步/操作（游标）
{
"createTime": 1757156383,
"fromUser": "wxid_xxxxxxxxx",
"toUser": "filehelper",
"isSelf": true,
"msgId": 2112768065,
"newMsgId": 7564106960466729984,
"msgType": 51,
"rawContent": "<msg><op id='5'><username>filehelper</username><name>lastMessage</name><arg>{\"messageSvrId\":\"7129875...\",\"MsgCreateTime\":\"1757156311\"}</arg></op></msg>"
}
修改于 2025-09-07 05:33:50