7dcd89c7fc
- 前台用户端 API 迁移到 frontend/ 目录（auth/contact/im/meeting/notify） - 后台管理端 admin.md 拆分为 admin/ 目录下 4 个文档（auth/user/meeting/system） - WebSocket 协议保留在根目录（跨端通用） - 更新 README 导航为两级结构，补充目录结构说明 - 更新所有文档间的交叉引用路径 Made-with: Cursor
209 lines
5.4 KiB
Markdown
209 lines
5.4 KiB
Markdown
# 即时通讯模块 API (IM)
|
||
|
||
> 通用规范（认证方式、响应格式、错误码）见 [README.md](../README.md)
|
||
> 消息的实时收发通过 WebSocket 完成，见 [websocket.md](../websocket.md)
|
||
> 本文档中的接口用于会话管理和消息历史查询等非实时操作。
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | /api/v1/conversations | 需认证 | 获取会话列表 |
|
||
| POST | /api/v1/conversations | 需认证 | 创建群聊 |
|
||
| GET | /api/v1/conversations/:id | 需认证 | 获取会话详情 |
|
||
| GET | /api/v1/conversations/:id/messages | 需认证 | 获取消息历史 |
|
||
| POST | /api/v1/conversations/:id/members | 需认证 | 邀请成员加入群聊 |
|
||
| DELETE | /api/v1/conversations/:id/members/:uid | 需认证 | 移除群聊成员 |
|
||
|
||
---
|
||
|
||
## 1. 获取会话列表
|
||
|
||
`GET /api/v1/conversations`
|
||
|
||
**权限：** 需认证
|
||
|
||
**说明：** 返回当前用户的所有会话，按最后消息时间倒序排列。单聊会话的 `name`/`avatar` 为空，前端应使用 `target_user` 的信息展示。
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"type": 1,
|
||
"name": "",
|
||
"avatar": "",
|
||
"target_user": {
|
||
"id": 2,
|
||
"nickname": "李四",
|
||
"avatar": "https://cdn.echochat.com/avatar/2.jpg",
|
||
"online": true
|
||
},
|
||
"last_message": {
|
||
"id": 100,
|
||
"type": 1,
|
||
"content": "你好",
|
||
"sender_id": 2,
|
||
"created_at": "2026-02-27 10:30:00"
|
||
},
|
||
"unread_count": 3,
|
||
"is_pinned": false
|
||
},
|
||
{
|
||
"id": 5,
|
||
"type": 2,
|
||
"name": "产品讨论组",
|
||
"avatar": "https://cdn.echochat.com/group/5.jpg",
|
||
"target_user": null,
|
||
"last_message": {
|
||
"id": 205,
|
||
"type": 1,
|
||
"content": "明天开会",
|
||
"sender_id": 3,
|
||
"created_at": "2026-02-27 11:00:00"
|
||
},
|
||
"unread_count": 0,
|
||
"is_pinned": true,
|
||
"member_count": 8
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 创建群聊
|
||
|
||
`POST /api/v1/conversations`
|
||
|
||
**权限：** 需认证
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | 是 | 群聊名称 |
|
||
| member_ids | int[] | 是 | 初始成员用户 ID 列表（不含自己，至少 2 人） |
|
||
|
||
**说明：** 创建者自动成为群主（role=2），被邀请的成员为普通成员（role=0）。
|
||
|
||
---
|
||
|
||
## 3. 获取会话详情
|
||
|
||
`GET /api/v1/conversations/:id`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**成功响应（群聊示例）：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"id": 5,
|
||
"type": 2,
|
||
"name": "产品讨论组",
|
||
"avatar": "https://cdn.echochat.com/group/5.jpg",
|
||
"owner_id": 1,
|
||
"max_members": 200,
|
||
"member_count": 8,
|
||
"members": [
|
||
{ "user_id": 1, "nickname": "张三", "role": 2, "online": true },
|
||
{ "user_id": 2, "nickname": "李四", "role": 0, "online": false }
|
||
],
|
||
"created_at": "2026-02-20 09:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 获取消息历史
|
||
|
||
`GET /api/v1/conversations/:id/messages`
|
||
|
||
**权限：** 需认证，且为该会话成员
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| before_id | int | 无 | 获取此消息 ID 之前的消息（用于向上翻页加载历史） |
|
||
| limit | int | 30 | 每次获取数量，最大 50 |
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"messages": [
|
||
{
|
||
"id": 98,
|
||
"sender_id": 1,
|
||
"sender_name": "张三",
|
||
"sender_avatar": "https://...",
|
||
"type": 1,
|
||
"content": "明天几点开会？",
|
||
"extra": {},
|
||
"status": 1,
|
||
"created_at": "2026-02-27 10:28:00"
|
||
},
|
||
{
|
||
"id": 99,
|
||
"sender_id": 2,
|
||
"sender_name": "李四",
|
||
"sender_avatar": "https://...",
|
||
"type": 2,
|
||
"content": "",
|
||
"extra": {
|
||
"url": "https://cdn.echochat.com/img/xxx.jpg",
|
||
"width": 800,
|
||
"height": 600,
|
||
"thumbnail": "https://cdn.echochat.com/img/xxx_thumb.jpg"
|
||
},
|
||
"status": 1,
|
||
"created_at": "2026-02-27 10:29:00"
|
||
}
|
||
],
|
||
"has_more": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 邀请成员加入群聊
|
||
|
||
`POST /api/v1/conversations/:id/members`
|
||
|
||
**权限：** 需认证，且为该群聊成员
|
||
|
||
**请求参数：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| user_ids | int[] | 是 | 要邀请的用户 ID 列表 |
|
||
|
||
**可能的错误码：** 3001（会话不存在），3002（非会话成员），4003（超出人数上限）
|
||
|
||
---
|
||
|
||
## 6. 移除群聊成员
|
||
|
||
`DELETE /api/v1/conversations/:id/members/:uid`
|
||
|
||
**权限：** 需认证，且为群主或管理员
|
||
|
||
**路径参数：**
|
||
- `id` — 会话 ID
|
||
- `uid` — 被移除的用户 ID
|
||
|
||
**可能的错误码：** 3001, 3002, 1003（非群主/管理员无权操作）
|