mirror of
https://github.com/hicccc77/WeFlow.git
synced 2026-03-24 23:06:51 +00:00
509 lines
11 KiB
Markdown
509 lines
11 KiB
Markdown
# WeFlow HTTP API / Push 文档
|
||
|
||
WeFlow 提供本地 HTTP API，便于外部脚本或工具读取聊天记录、会话、联系人、群成员和导出的媒体文件；也支持在检测到新消息后通过固定 SSE 地址主动推送消息事件。
|
||
|
||
## 启用方式
|
||
|
||
在应用设置页启用 `API 服务`。
|
||
|
||
- 默认监听地址：`127.0.0.1`
|
||
- 默认端口：`5031`
|
||
- 基础地址：`http://127.0.0.1:5031`
|
||
- 可选开启 `主动推送`，检测到新收到的消息后会通过 `GET /api/v1/push/messages` 推送给 SSE 订阅端
|
||
|
||
## 接口列表
|
||
|
||
- `GET /health`
|
||
- `GET /api/v1/health`
|
||
- `GET /api/v1/push/messages`
|
||
- `GET /api/v1/messages`
|
||
- `GET /api/v1/messages/new`
|
||
- `GET /api/v1/sessions`
|
||
- `GET /api/v1/contacts`
|
||
- `GET /api/v1/group-members`
|
||
- `GET /api/v1/media/*`
|
||
|
||
---
|
||
|
||
## 1. 健康检查
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /health
|
||
```
|
||
|
||
或
|
||
|
||
```http
|
||
GET /api/v1/health
|
||
```
|
||
|
||
**响应**
|
||
|
||
```json
|
||
{
|
||
"status": "ok"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 主动推送
|
||
|
||
通过 SSE 长连接接收新消息事件，端口与 HTTP API 共用。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/v1/push/messages
|
||
```
|
||
|
||
### 说明
|
||
|
||
- 需要先在设置页开启 `HTTP API 服务`
|
||
- 同时需要开启 `主动推送`
|
||
- 响应类型为 `text/event-stream`
|
||
- 新消息事件名固定为 `message.new`
|
||
- 建议接收端按 `messageKey` 去重
|
||
|
||
### 事件字段
|
||
|
||
- `event`
|
||
- `sessionId`
|
||
- `messageKey`
|
||
- `avatarUrl`
|
||
- `sourceName`
|
||
- `groupName`（仅群聊）
|
||
- `content`
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
curl -N "http://127.0.0.1:5031/api/v1/push/messages"
|
||
```
|
||
|
||
示例事件：
|
||
|
||
```text
|
||
event: message.new
|
||
data: {"event":"message.new","sessionId":"xxx@chatroom","messageKey":"server:123456:1760000123:1760000123000:321:wxid_member:1","avatarUrl":"https://example.com/group.jpg","sourceName":"李四","groupName":"项目群","content":"[图片]"}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 获取消息
|
||
|
||
读取指定会话的消息，支持原始 JSON 和 ChatLab 格式。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/v1/messages
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `talker` | string | 是 | 会话 ID。私聊通常是对方 `wxid`，群聊是 `xxx@chatroom` |
|
||
| `limit` | number | 否 | 返回条数，默认 `100`，范围 `1~10000` |
|
||
| `offset` | number | 否 | 分页偏移，默认 `0` |
|
||
| `start` | string | 否 | 开始时间，支持 `YYYYMMDD` 或时间戳 |
|
||
| `end` | string | 否 | 结束时间，支持 `YYYYMMDD` 或时间戳 |
|
||
| `keyword` | string | 否 | 基于消息显示文本过滤 |
|
||
| `chatlab` | string | 否 | `1/true` 时输出 ChatLab 格式 |
|
||
| `format` | string | 否 | `json` 或 `chatlab` |
|
||
| `media` | string | 否 | `1/true` 时导出媒体并返回媒体地址，兼容别名 `meiti` |
|
||
| `image` | string | 否 | 在 `media=1` 时控制图片导出，兼容别名 `tupian` |
|
||
| `voice` | string | 否 | 在 `media=1` 时控制语音导出，兼容别名 `vioce` |
|
||
| `video` | string | 否 | 在 `media=1` 时控制视频导出 |
|
||
| `emoji` | string | 否 | 在 `media=1` 时控制表情导出 |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&limit=20"
|
||
curl "http://127.0.0.1:5031/api/v1/messages?talker=xxx@chatroom&chatlab=1"
|
||
curl "http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&start=20260101&end=20260131"
|
||
curl "http://127.0.0.1:5031/api/v1/messages?talker=xxx@chatroom&media=1&image=1&voice=0&video=0&emoji=0"
|
||
```
|
||
|
||
### JSON 响应字段
|
||
|
||
顶层字段：
|
||
|
||
- `success`
|
||
- `talker`
|
||
- `count`
|
||
- `hasMore`
|
||
- `media.enabled`
|
||
- `media.exportPath`
|
||
- `media.count`
|
||
- `messages`
|
||
|
||
单条消息字段：
|
||
|
||
- `localId`
|
||
- `serverId`
|
||
- `localType`
|
||
- `createTime`
|
||
- `isSend`
|
||
- `senderUsername`
|
||
- `content`
|
||
- `rawContent`
|
||
- `parsedContent`
|
||
- `mediaType`
|
||
- `mediaFileName`
|
||
- `mediaUrl`
|
||
- `mediaLocalPath`
|
||
|
||
**示例响应**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"talker": "xxx@chatroom",
|
||
"count": 2,
|
||
"hasMore": true,
|
||
"media": {
|
||
"enabled": true,
|
||
"exportPath": "C:\\Users\\Alice\\Documents\\WeFlow\\api-media",
|
||
"count": 1
|
||
},
|
||
"messages": [
|
||
{
|
||
"localId": 123,
|
||
"serverId": "456",
|
||
"localType": 1,
|
||
"createTime": 1738713600,
|
||
"isSend": 0,
|
||
"senderUsername": "wxid_member",
|
||
"content": "你好",
|
||
"rawContent": "你好",
|
||
"parsedContent": "你好"
|
||
},
|
||
{
|
||
"localId": 124,
|
||
"localType": 3,
|
||
"createTime": 1738713660,
|
||
"isSend": 0,
|
||
"senderUsername": "wxid_member",
|
||
"content": "[图片]",
|
||
"mediaType": "image",
|
||
"mediaFileName": "abc123.jpg",
|
||
"mediaUrl": "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/images/abc123.jpg",
|
||
"mediaLocalPath": "C:\\Users\\Alice\\Documents\\WeFlow\\api-media\\xxx@chatroom\\images\\abc123.jpg"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### ChatLab 响应
|
||
|
||
当 `chatlab=1` 或 `format=chatlab` 时，返回 ChatLab 结构：
|
||
|
||
- `chatlab.version`
|
||
- `chatlab.exportedAt`
|
||
- `chatlab.generator`
|
||
- `meta.name`
|
||
- `meta.platform`
|
||
- `meta.type`
|
||
- `meta.groupId`
|
||
- `meta.groupAvatar`
|
||
- `meta.ownerId`
|
||
- `members[].platformId`
|
||
- `members[].accountName`
|
||
- `members[].groupNickname`
|
||
- `members[].avatar`
|
||
- `messages[].sender`
|
||
- `messages[].accountName`
|
||
- `messages[].groupNickname`
|
||
- `messages[].timestamp`
|
||
- `messages[].type`
|
||
- `messages[].content`
|
||
- `messages[].platformMessageId`
|
||
- `messages[].mediaPath`
|
||
|
||
群聊里 `groupNickname` 会优先来自群成员群昵称；若源数据缺失，则回退为空或展示名。
|
||
|
||
---
|
||
|
||
## 4. 获取会话列表
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/v1/sessions
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `keyword` | string | 否 | 匹配 `username` 或 `displayName` |
|
||
| `limit` | number | 否 | 默认 `100` |
|
||
|
||
### 响应字段
|
||
|
||
- `success`
|
||
- `count`
|
||
- `sessions[].username`
|
||
- `sessions[].displayName`
|
||
- `sessions[].type`
|
||
- `sessions[].lastTimestamp`
|
||
- `sessions[].unreadCount`
|
||
|
||
**示例响应**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"count": 1,
|
||
"sessions": [
|
||
{
|
||
"username": "xxx@chatroom",
|
||
"displayName": "项目群",
|
||
"type": 2,
|
||
"lastTimestamp": 1738713600,
|
||
"unreadCount": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 获取联系人列表
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/v1/contacts
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `keyword` | string | 否 | 匹配 `username`、`nickname`、`remark`、`displayName` |
|
||
| `limit` | number | 否 | 默认 `100` |
|
||
|
||
### 响应字段
|
||
|
||
- `success`
|
||
- `count`
|
||
- `contacts[].username`
|
||
- `contacts[].displayName`
|
||
- `contacts[].remark`
|
||
- `contacts[].nickname`
|
||
- `contacts[].alias`
|
||
- `contacts[].avatarUrl`
|
||
- `contacts[].type`
|
||
|
||
**示例响应**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"count": 1,
|
||
"contacts": [
|
||
{
|
||
"username": "wxid_xxx",
|
||
"displayName": "张三",
|
||
"remark": "客户张三",
|
||
"nickname": "张三",
|
||
"alias": "zhangsan",
|
||
"avatarUrl": "https://example.com/avatar.jpg",
|
||
"type": "friend"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 获取群成员列表
|
||
|
||
返回群成员的 `wxid`、群昵称、备注、微信号等信息。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/v1/group-members
|
||
```
|
||
|
||
### 参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `chatroomId` | string | 是 | 群 ID，兼容使用 `talker` 传入 |
|
||
| `includeMessageCounts` | string | 否 | `1/true` 时附带成员发言数 |
|
||
| `withCounts` | string | 否 | `includeMessageCounts` 的别名 |
|
||
| `forceRefresh` | string | 否 | `1/true` 时跳过内存缓存强制刷新 |
|
||
|
||
### 响应字段
|
||
|
||
- `success`
|
||
- `chatroomId`
|
||
- `count`
|
||
- `fromCache`
|
||
- `updatedAt`
|
||
- `members[].wxid`
|
||
- `members[].displayName`
|
||
- `members[].nickname`
|
||
- `members[].remark`
|
||
- `members[].alias`
|
||
- `members[].groupNickname`
|
||
- `members[].avatarUrl`
|
||
- `members[].isOwner`
|
||
- `members[].isFriend`
|
||
- `members[].messageCount`
|
||
|
||
**示例请求**
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:5031/api/v1/group-members?chatroomId=xxx@chatroom"
|
||
curl "http://127.0.0.1:5031/api/v1/group-members?chatroomId=xxx@chatroom&includeMessageCounts=1&forceRefresh=1"
|
||
```
|
||
|
||
**示例响应**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"chatroomId": "xxx@chatroom",
|
||
"count": 2,
|
||
"fromCache": false,
|
||
"updatedAt": 1760000000000,
|
||
"members": [
|
||
{
|
||
"wxid": "wxid_member_a",
|
||
"displayName": "客户A",
|
||
"nickname": "阿甲",
|
||
"remark": "客户A",
|
||
"alias": "kehua",
|
||
"groupNickname": "甲方",
|
||
"avatarUrl": "https://example.com/a.jpg",
|
||
"isOwner": true,
|
||
"isFriend": true,
|
||
"messageCount": 128
|
||
},
|
||
{
|
||
"wxid": "wxid_member_b",
|
||
"displayName": "李四",
|
||
"nickname": "李四",
|
||
"remark": "",
|
||
"alias": "",
|
||
"groupNickname": "",
|
||
"avatarUrl": "",
|
||
"isOwner": false,
|
||
"isFriend": false,
|
||
"messageCount": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `displayName` 是当前应用内的主展示名。
|
||
- `groupNickname` 是成员在该群里的群昵称。
|
||
- `remark` 是你对该联系人的备注。
|
||
- `alias` 是微信号。
|
||
- 当微信源数据里没有群昵称时，`groupNickname` 会为空。
|
||
|
||
---
|
||
|
||
## 7. 访问导出媒体
|
||
|
||
通过消息接口启用 `media=1` 后，接口会先把图片、语音、视频、表情导出到本地缓存目录，再返回可访问的 HTTP 地址。
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/v1/media/{relativePath}
|
||
```
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
curl "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/images/abc123.jpg"
|
||
curl "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/voices/voice_100.wav"
|
||
curl "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/videos/video_200.mp4"
|
||
curl "http://127.0.0.1:5031/api/v1/media/xxx@chatroom/emojis/emoji_300.gif"
|
||
```
|
||
|
||
### 支持的 Content-Type
|
||
|
||
| 扩展名 | Content-Type |
|
||
| --- | --- |
|
||
| `.png` | `image/png` |
|
||
| `.jpg` / `.jpeg` | `image/jpeg` |
|
||
| `.gif` | `image/gif` |
|
||
| `.webp` | `image/webp` |
|
||
| `.wav` | `audio/wav` |
|
||
| `.mp3` | `audio/mpeg` |
|
||
| `.mp4` | `video/mp4` |
|
||
|
||
常见错误响应：
|
||
|
||
```json
|
||
{
|
||
"error": "Media not found"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 使用示例
|
||
|
||
### PowerShell
|
||
|
||
```powershell
|
||
Invoke-RestMethod http://127.0.0.1:5031/health
|
||
Invoke-RestMethod http://127.0.0.1:5031/api/v1/sessions
|
||
Invoke-RestMethod "http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&limit=10"
|
||
Invoke-RestMethod "http://127.0.0.1:5031/api/v1/group-members?chatroomId=xxx@chatroom&includeMessageCounts=1"
|
||
```
|
||
|
||
### cURL
|
||
|
||
```bash
|
||
curl http://127.0.0.1:5031/health
|
||
curl "http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&chatlab=1"
|
||
curl "http://127.0.0.1:5031/api/v1/contacts?keyword=张三"
|
||
curl "http://127.0.0.1:5031/api/v1/group-members?chatroomId=xxx@chatroom"
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
|
||
BASE_URL = "http://127.0.0.1:5031"
|
||
|
||
messages = requests.get(
|
||
f"{BASE_URL}/api/v1/messages",
|
||
params={"talker": "xxx@chatroom", "limit": 50}
|
||
).json()
|
||
|
||
members = requests.get(
|
||
f"{BASE_URL}/api/v1/group-members",
|
||
params={"chatroomId": "xxx@chatroom", "includeMessageCounts": 1}
|
||
).json()
|
||
|
||
print(messages)
|
||
print(members)
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 注意事项
|
||
|
||
1. API 仅监听本机 `127.0.0.1`，不对外网开放。
|
||
2. 使用前需要先在 WeFlow 中完成数据库连接。
|
||
3. `start` 和 `end` 支持 `YYYYMMDD` 与时间戳；纯 `YYYYMMDD` 的 `end` 会扩展到当天 `23:59:59`。
|
||
4. 群成员的 `groupNickname` 依赖微信源数据；源数据缺失时不会自动补出。
|
||
5. 媒体访问链接只有在对应消息已经通过 `media=1` 导出后才可访问。
|