277e8ed7c6
- 实现了聊天消息发送功能，支持文本、图片、视频、音频、文件等多种消息类型 - 集成了文件上传下载功能，支持多媒体文件的传输和管理 - 添加了群组管理功能，包括创建群组、成员管理、权限控制等操作 - 实现了好友系统，支持好友添加、删除、分组等功能 - 集成了黑名单管理，提供用户屏蔽和解除屏蔽功能 - 添加了会话管理功能，支持对话列表、未读消息统计等 - 实现了历史消息查询和搜索功能 - 添加了实时连接状态管理和自动重连机制
250 行
4.5 KiB
Markdown
250 行
4.5 KiB
Markdown
# Server API 参考
|
||
|
||
**Base URL**：`https://dev.xuqinmin.com`
|
||
|
||
所有 API 通过 Nginx 反代，无需区分内部端口。
|
||
|
||
## 认证
|
||
|
||
除 `/api/im/auth/login` 外，所有 IM 接口需在请求头携带 JWT Token：
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
Token 由 `/api/im/auth/login` 接口签发。当前 IM 登录不做过期功能，只校验 `userId + UserSig` 是否匹配。
|
||
|
||
---
|
||
|
||
## IM 服务（/api/im/）
|
||
|
||
### 登录 · 获取 Token
|
||
|
||
```
|
||
POST /api/im/auth/login
|
||
```
|
||
|
||
**Query 参数**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `appId` | 是 | 应用 ID |
|
||
| `userId` | 是 | 用户 ID |
|
||
|
||
**请求头**
|
||
|
||
| 头 | 必填 | 说明 |
|
||
|----|------|------|
|
||
| `X-App-Timestamp` | 是 | 当前时间戳（毫秒） |
|
||
| `X-App-Nonce` | 是 | 随机字符串 |
|
||
| `X-App-Signature` | 是 | HmacSHA256 签名 |
|
||
|
||
**签名 Payload**（已简化，不再包含 nickname/avatar）：
|
||
```
|
||
{appId}\n{userId}\n{timestamp}\n{nonce}
|
||
```
|
||
|
||
**响应**
|
||
|
||
```json
|
||
{ "token": "eyJ..." }
|
||
```
|
||
|
||
> 重复登录会覆盖当前会话；SDK 侧不做生命周期检测或旧登录兼容。
|
||
|
||
---
|
||
|
||
### 发送消息
|
||
|
||
```
|
||
POST /api/im/messages/send
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"toId": "user_002",
|
||
"chatType": "SINGLE",
|
||
"msgType": "TEXT",
|
||
"content": "Hello!"
|
||
}
|
||
```
|
||
|
||
`chatType`：`SINGLE` | `GROUP`
|
||
|
||
`msgType`：`TEXT` | `IMAGE` | `VIDEO` | `AUDIO` | `FILE` | `CUSTOM` | `LOCATION` | `NOTIFY` | `RICH_TEXT` | `CALL_AUDIO` | `CALL_VIDEO` | `FORWARD`
|
||
|
||
**响应**：`ImMessage` 对象
|
||
|
||
---
|
||
|
||
### 撤回消息
|
||
|
||
```
|
||
PUT /api/im/messages/{messageId}/revoke
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**响应**：更新后的 `ImMessage`（`status: "REVOKED"`，`msgType: "REVOKED"`）
|
||
|
||
---
|
||
|
||
### 消息历史（单聊）
|
||
|
||
```
|
||
GET /api/im/messages/history?appId=&userId=&toId=&page=0&size=50
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**响应**：分页 `ImMessage` 列表
|
||
|
||
---
|
||
|
||
### 创建群组
|
||
|
||
```
|
||
POST /api/im/groups
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"appId": "ak_demo_chat",
|
||
"name": "开发群",
|
||
"memberIds": ["user_001", "user_002"]
|
||
}
|
||
```
|
||
|
||
**响应**：`ImGroup` 对象
|
||
|
||
---
|
||
|
||
### 获取群列表
|
||
|
||
```
|
||
GET /api/im/groups?appId=ak_demo_chat
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
---
|
||
|
||
### 添加群成员
|
||
|
||
```
|
||
POST /api/im/groups/{groupId}/members
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{ "userId": "user_003" }
|
||
```
|
||
|
||
---
|
||
|
||
### 移除群成员
|
||
|
||
```
|
||
DELETE /api/im/groups/{groupId}/members/{targetUserId}
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
---
|
||
|
||
### 会话扩展
|
||
|
||
```
|
||
PUT /api/im/conversations/{targetId}/hidden?appId=&chatType=SINGLE&hidden=true
|
||
PUT /api/im/conversations/{targetId}/group?appId=&chatType=SINGLE&groupName=重要客户
|
||
GET /api/im/conversation-groups?appId=
|
||
GET /api/im/conversation-groups/{groupName}?appId=
|
||
```
|
||
|
||
### 好友扩展
|
||
|
||
```
|
||
DELETE /api/im/friends?appId=
|
||
PUT /api/im/friends/{friendId}/group?appId=&groupName=同事
|
||
GET /api/im/friends/groups?appId=
|
||
GET /api/im/friends/groups/{groupName}?appId=
|
||
```
|
||
|
||
### 黑名单校验
|
||
|
||
```
|
||
GET /api/im/blacklist/check?appId=&targetUserId=user_002
|
||
```
|
||
|
||
### 群扩展
|
||
|
||
```
|
||
POST /api/im/groups/{groupId}/owner
|
||
PUT /api/im/groups/{groupId}/attributes
|
||
POST /api/im/groups/{groupId}/attributes/delete
|
||
```
|
||
|
||
管理端补充：
|
||
|
||
```
|
||
POST /api/im/admin/groups/{groupId}/owner?appId=
|
||
PUT /api/im/admin/groups/{groupId}/attributes?appId=
|
||
POST /api/im/admin/groups/{groupId}/attributes/delete?appId=
|
||
POST /api/im/admin/groups/{groupId}/read-receipts?appId=
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### ImMessage
|
||
|
||
```json
|
||
{
|
||
"id": "uuid",
|
||
"appId": "ak_demo_chat",
|
||
"fromUserId": "user_001",
|
||
"toId": "user_002",
|
||
"chatType": "SINGLE",
|
||
"msgType": "TEXT",
|
||
"content": "Hello!",
|
||
"status": "SENT",
|
||
"mentionedUserIds": [],
|
||
"createdAt": "2026-04-24T10:00:00"
|
||
}
|
||
```
|
||
|
||
### ImGroup
|
||
|
||
```json
|
||
{
|
||
"id": "group_uuid",
|
||
"appId": "ak_demo_chat",
|
||
"name": "开发群",
|
||
"creatorId": "user_001",
|
||
"memberIds": ["user_001", "user_002"],
|
||
"adminIds": ["user_001"],
|
||
"extAttributes": "{\"department\":\"sales\"}",
|
||
"createdAt": "2026-04-24T10:00:00"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| HTTP 状态 | code | 说明 |
|
||
|-----------|------|------|
|
||
| 400 | 400 | 请求参数错误 |
|
||
| 401 | 401 | Token 无效或签名验证失败 |
|
||
| 403 | 403 | 无权限操作（如撤回他人消息）|
|
||
| 404 | 404 | 资源不存在 |
|
||
| 500 | 500 | 服务器内部错误 |
|
||
|
||
错误响应格式：
|
||
|
||
```json
|
||
{ "code": 403, "message": "只能撤回自己发送的消息" }
|
||
```
|
