Appearance
同步消息
主动拉取消息。正常情况下新消息通过 Webhook 推送给你；本接口用于补拉（掉线补偿、历史回溯、首次全量）。
说明与注意
- 响应
data包含count、isEnd与list列表；消息对象里的id、syncKey是 int64。 - 本接口拉取历史时，
content基本是 protobuf，文本拿不到明文；Webhook 推送的文本是明文数组，媒体是带下载凭证的明文对象。推送和同步消息要分开解析，发送响应则回显你发送的内容。见回调字典。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
appid | 是 | string | 实例 appid，标识操作哪个已登录账号。示例：we_xxxxxxxxxxxxxxx |
limit | 否 | int64 | 拉取条数。示例：100 |
syncKey | 增量时必填 | int64 | 上次同步游标；首次可传 0。示例：15875106 |
请求示例
http
POST {BASE_URL}/wx-api/api/message/sync
Authorization: Bearer <你的 App Token>
Content-Type: application/json
{
"appid": "we_xxxxxxxxxxxxxxx",
"limit": 100,
"syncKey": 15875106
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
bash
curl -X POST '{BASE_URL}/wx-api/api/message/sync' \
-H 'Authorization: Bearer <你的 App Token>' \
-H 'Content-Type: application/json' \
--data-raw '{
"appid": "we_xxxxxxxxxxxxxxx",
"limit": 100,
"syncKey": 15875106
}'1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
python
import requests
url = "{BASE_URL}/wx-api/api/message/sync"
headers = {"Authorization": "Bearer <你的 App Token>", "Content-Type": "application/json"}
body = """{
"appid": "we_xxxxxxxxxxxxxxx",
"limit": 100,
"syncKey": 15875106
}"""
resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String url = "{BASE_URL}/wx-api/api/message/sync";
String body = "{\n" +
" \"appid\": \"we_xxxxxxxxxxxxxxx\",\n" +
" \"limit\": 100,\n" +
" \"syncKey\": 15875106\n" +
"}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
.header("Authorization", "Bearer <你的 App Token>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
php
<?php
$url = '{BASE_URL}/wx-api/api/message/sync';
$body = <<<'JSON'
{
"appid": "we_xxxxxxxxxxxxxxx",
"limit": 100,
"syncKey": 15875106
}
JSON;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer <你的 App Token>',
'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
响应示例
json
{
"code": 0,
"data": {
"count": 935,
"isEnd": false,
"list": [
{
"id": 1136157,
"syncKey": 12269915,
"messageType": 3,
"fromUserId": 10120,
"toUserId": 0,
"roomId": 10120,
"contentType": 31,
"sendTime": 1780878274,
"appInfo": "wwdailyindustrynews_appinfo_1780848000",
"senderName": "",
"content": {
"msgType": 31,
"hex": "0ae9020a4be5908ce4ba8be4bbace59ca8e79c8b..."
},
"extraData": "<base64>",
"flag": 0,
"devInfo": 0,
"summary": ""
}
],
"syncKey": 12370562
},
"detail": "",
"message": "ok",
"time": "2026-09-06 11:12:58"
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
响应字段
响应字段（26 项）
| 字段 | 类型 | 说明 |
|---|---|---|
code | int64 | 统一封套状态码：0=成功，负数=失败 |
data | object | 业务数据 |
data.count | int64 | 本批返回条数 |
data.isEnd | boolean | 是否已到末页 |
data.list | array<object> | 消息对象数组 |
data.list[].id | int64 | 记录/文件业务标识 |
data.list[].syncKey | int64 | 同步游标；增量拉取的断点 |
data.list[].messageType | int64 | 会话类型：0 好友（单聊）、1 群聊、3 系统通知，与 Webhook 报文外层的 messageType 同一取值，见会话类型 |
data.list[].fromUserId | int64 | 发送方 id（uin）；群消息里是真实发送成员 |
data.list[].toUserId | int64 | 接收方 id（uin），通常是本账号 |
data.list[].roomId | int64 | 群会话 id；非群消息为 0 |
data.list[].contentType | int64 | 消息类型码（0 文本/14 图片/23 视频…） |
data.list[].sendTime | int64 | 发送时间（Unix 秒） |
data.list[].appInfo | string | 企微内部透传串（base64）；群发/待发送场景需回填，业务方不必解析 |
data.list[].senderName | string | 发送者昵称（可能为空） |
data.list[].content | object | 消息内容；文本为数组、媒体为对象；未解析的消息为 {msgType, hex}（hex=protobuf 原始十六进制） |
data.list[].content.msgType | int64 | 消息类型码，决定 content 形状（见类型速查表） |
data.list[].content.hex | string | |
data.list[].extraData | string | 企微内部透传（新协议为 base64 字符串；老协议曾为字符串数组）；业务方不解析 |
data.list[].flag / data.list[].devInfo / data.list[].summary | int64 / string | 消息标志位 / 设备信息 / 摘要；观测到 flag 取 0 或 16777216，summary 常为空。精确含义待确认 |
data.syncKey | int64 | 同步游标；增量拉取的断点 |
detail | string | 附加明细，通常为空 |
message | string | 文案：成功为 ok；失败形如 -码|描述 |
time | string | 服务端处理时间 YYYY-MM-DD HH:MM:SS |