mirror of
https://github.com/hicccc77/WeFlow.git
synced 2026-03-25 15:25:50 +00:00
339 lines
7.3 KiB
Markdown
339 lines
7.3 KiB
Markdown
# WeFlow HTTP API 接口文档
|
||
|
||
WeFlow 提供 HTTP API 服务，支持通过 HTTP 接口查询消息数据，支持 [ChatLab](https://github.com/nichuanfang/chatlab-format) 标准化格式输出。
|
||
|
||
## 启用 API 服务
|
||
|
||
在设置页面 → API 服务 → 点击「启动服务」按钮。
|
||
|
||
默认端口：`5031`
|
||
|
||
## 基础地址
|
||
|
||
```
|
||
http://127.0.0.1:5031
|
||
```
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 健康检查
|
||
|
||
检查 API 服务是否正常运行。
|
||
|
||
**请求**
|
||
```
|
||
GET /health
|
||
```
|
||
|
||
**响应**
|
||
```json
|
||
{
|
||
"status": "ok"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取消息列表
|
||
|
||
获取指定会话的消息，支持 ChatLab 格式输出。
|
||
|
||
**请求**
|
||
```
|
||
GET /api/v1/messages
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| `talker` | string | ✅ | 会话 ID（wxid 或群 ID） |
|
||
| `limit` | number | ❌ | 返回数量限制，默认 100，范围 `1~10000` |
|
||
| `offset` | number | ❌ | 偏移量，用于分页，默认 0 |
|
||
| `start` | string | ❌ | 开始时间，格式 YYYYMMDD |
|
||
| `end` | string | ❌ | 结束时间，格式 YYYYMMDD |
|
||
| `keyword` | string | ❌ | 关键词过滤（基于消息显示文本） |
|
||
| `chatlab` | string | ❌ | 设为 `1` 则输出 ChatLab 格式 |
|
||
| `format` | string | ❌ | 输出格式：`json`（默认）或 `chatlab` |
|
||
| `media` | string | ❌ | 设为 `1` 时导出媒体并返回媒体路径（兼容别名 `meiti`）；`0` 时媒体返回占位符 |
|
||
| `image` | string | ❌ | 在 `media=1` 时控制图片导出，`1/0`（兼容别名 `tupian`） |
|
||
| `voice` | string | ❌ | 在 `media=1` 时控制语音导出，`1/0`（兼容别名 `vioce`） |
|
||
| `video` | string | ❌ | 在 `media=1` 时控制视频导出，`1/0` |
|
||
| `emoji` | string | ❌ | 在 `media=1` 时控制表情导出，`1/0` |
|
||
|
||
默认媒体导出目录：`%USERPROFILE%\\Documents\\WeFlow\\api-media`
|
||
|
||
**示例请求**
|
||
|
||
```bash
|
||
# 获取消息（原始格式）
|
||
GET http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&limit=50
|
||
|
||
# 获取消息（ChatLab 格式）
|
||
GET http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&chatlab=1
|
||
|
||
# 带时间范围查询
|
||
GET http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&start=20260101&end=20260205&limit=100
|
||
|
||
# 开启媒体导出（只导出图片和语音）
|
||
GET http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&media=1&image=1&voice=1&video=0&emoji=0
|
||
|
||
# 关键词过滤
|
||
GET http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&keyword=项目进度&limit=50
|
||
```
|
||
|
||
**响应（原始格式）**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"talker": "wxid_xxx",
|
||
"count": 50,
|
||
"hasMore": true,
|
||
"media": {
|
||
"enabled": true,
|
||
"exportPath": "C:\\Users\\Alice\\Documents\\WeFlow\\api-media",
|
||
"count": 12
|
||
},
|
||
"messages": [
|
||
{
|
||
"localId": 123,
|
||
"localType": 3,
|
||
"content": "[图片]",
|
||
"createTime": 1738713600000,
|
||
"senderUsername": "wxid_sender",
|
||
"mediaType": "image",
|
||
"mediaFileName": "image_123.jpg",
|
||
"mediaPath": "C:\\Users\\Alice\\Documents\\WeFlow\\api-media\\wxid_xxx\\images\\image_123.jpg"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应（ChatLab 格式）**
|
||
```json
|
||
{
|
||
"chatlab": {
|
||
"version": "0.0.2",
|
||
"exportedAt": 1738713600000,
|
||
"generator": "WeFlow",
|
||
"description": "Exported from WeFlow"
|
||
},
|
||
"meta": {
|
||
"name": "会话名称",
|
||
"platform": "wechat",
|
||
"type": "private",
|
||
"ownerId": "wxid_me"
|
||
},
|
||
"members": [
|
||
{
|
||
"platformId": "wxid_xxx",
|
||
"accountName": "用户名",
|
||
"groupNickname": "群昵称"
|
||
}
|
||
],
|
||
"messages": [
|
||
{
|
||
"sender": "wxid_xxx",
|
||
"accountName": "用户名",
|
||
"timestamp": 1738713600000,
|
||
"type": 0,
|
||
"content": "消息内容",
|
||
"mediaPath": "C:\\Users\\Alice\\Documents\\WeFlow\\api-media\\wxid_xxx\\images\\image_123.jpg"
|
||
}
|
||
],
|
||
"media": {
|
||
"enabled": true,
|
||
"exportPath": "C:\\Users\\Alice\\Documents\\WeFlow\\api-media",
|
||
"count": 12
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取会话列表
|
||
|
||
获取所有会话列表。
|
||
|
||
**请求**
|
||
```
|
||
GET /api/v1/sessions
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| `keyword` | string | ❌ | 搜索关键词，匹配会话名或 ID |
|
||
| `limit` | number | ❌ | 返回数量限制，默认 100 |
|
||
|
||
**示例请求**
|
||
```bash
|
||
GET http://127.0.0.1:5031/api/v1/sessions
|
||
|
||
GET http://127.0.0.1:5031/api/v1/sessions?keyword=工作群&limit=20
|
||
```
|
||
|
||
**响应**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"count": 50,
|
||
"total": 100,
|
||
"sessions": [
|
||
{
|
||
"username": "wxid_xxx",
|
||
"displayName": "用户名",
|
||
"lastMessage": "最后一条消息",
|
||
"lastTime": 1738713600000,
|
||
"unreadCount": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取联系人列表
|
||
|
||
获取所有联系人信息。
|
||
|
||
**请求**
|
||
```
|
||
GET /api/v1/contacts
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| `keyword` | string | ❌ | 搜索关键词 |
|
||
| `limit` | number | ❌ | 返回数量限制，默认 100 |
|
||
|
||
**示例请求**
|
||
```bash
|
||
GET http://127.0.0.1:5031/api/v1/contacts
|
||
|
||
GET http://127.0.0.1:5031/api/v1/contacts?keyword=张三
|
||
```
|
||
|
||
**响应**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"count": 50,
|
||
"contacts": [
|
||
{
|
||
"userName": "wxid_xxx",
|
||
"alias": "微信号",
|
||
"nickName": "昵称",
|
||
"remark": "备注名"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ChatLab 格式说明
|
||
|
||
ChatLab 是一种标准化的聊天记录交换格式，版本 0.0.2。
|
||
|
||
### 消息类型映射
|
||
|
||
| ChatLab Type | 值 | 说明 |
|
||
|--------------|-----|------|
|
||
| TEXT | 0 | 文本消息 |
|
||
| IMAGE | 1 | 图片 |
|
||
| VOICE | 2 | 语音 |
|
||
| VIDEO | 3 | 视频 |
|
||
| FILE | 4 | 文件 |
|
||
| EMOJI | 5 | 表情 |
|
||
| LINK | 7 | 链接 |
|
||
| LOCATION | 8 | 位置 |
|
||
| RED_PACKET | 20 | 红包 |
|
||
| TRANSFER | 21 | 转账 |
|
||
| CALL | 23 | 通话 |
|
||
| SYSTEM | 80 | 系统消息 |
|
||
| RECALL | 81 | 撤回消息 |
|
||
| OTHER | 99 | 其他 |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 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"
|
||
|
||
# 获取 ChatLab 格式
|
||
Invoke-RestMethod "http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&chatlab=1" | ConvertTo-Json -Depth 10
|
||
```
|
||
|
||
### cURL
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://127.0.0.1:5031/health
|
||
|
||
# 获取会话列表
|
||
curl http://127.0.0.1:5031/api/v1/sessions
|
||
|
||
# 获取消息（ChatLab 格式）
|
||
curl "http://127.0.0.1:5031/api/v1/messages?talker=wxid_xxx&chatlab=1"
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
|
||
BASE_URL = "http://127.0.0.1:5031"
|
||
|
||
# 获取会话列表
|
||
sessions = requests.get(f"{BASE_URL}/api/v1/sessions").json()
|
||
print(sessions)
|
||
|
||
# 获取消息
|
||
messages = requests.get(f"{BASE_URL}/api/v1/messages", params={
|
||
"talker": "wxid_xxx",
|
||
"limit": 100,
|
||
"chatlab": 1
|
||
}).json()
|
||
print(messages)
|
||
```
|
||
|
||
### JavaScript / Node.js
|
||
|
||
```javascript
|
||
const BASE_URL = "http://127.0.0.1:5031";
|
||
|
||
// 获取会话列表
|
||
const sessions = await fetch(`${BASE_URL}/api/v1/sessions`).then(r => r.json());
|
||
console.log(sessions);
|
||
|
||
// 获取消息（ChatLab 格式）
|
||
const messages = await fetch(`${BASE_URL}/api/v1/messages?talker=wxid_xxx&chatlab=1`)
|
||
.then(r => r.json());
|
||
console.log(messages);
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. API 仅监听本地地址 `127.0.0.1`，不对外网开放
|
||
2. 需要先连接数据库才能查询数据
|
||
3. 时间参数格式为 `YYYYMMDD`（如 20260205）
|
||
4. 支持 CORS，可从浏览器前端直接调用
|