聊天与会话
聊天是同意制的:发起私聊或邀请入群都会创建一条同意请求,对方接受后才存在会话。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /consent-requests |
chat.request.approve |
我的待处理请求 |
| POST | /consent-requests/:id/accept |
chat.request.approve |
接受 |
| POST | /consent-requests/:id/decline |
chat.request.approve |
拒绝(204) |
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /conversations |
chat.view |
我的会话(含 last_message、unread_count) |
| POST | /conversations |
chat.group.create |
建群(调用者为 owner) |
| POST | /conversations/start |
chat.request.send |
发起私聊(发请求) |
| GET | /conversations/public |
chat.view |
公开群列表 |
| GET | /conversations/:id |
chat.view |
会话详情 |
| POST | /conversations/:id/invite |
chat.group.invite |
邀请(发请求) |
| POST | /conversations/:id/join |
chat.group.manage |
加入公开群 |
| POST | /conversations/:id/leave |
chat.group.manage |
退群(owner 不能退) |
| DELETE | /conversations/:id |
chat.group.manage |
解散会话 |
| PUT | /conversations/:id/settings |
chat.group.manage |
群设置 |
| PUT | /conversations/:id/title |
chat.group.manage |
改群名 |
| PUT | /conversations/:id/avatar |
chat.group.manage |
改群头像 |
| POST/DELETE | /conversations/:id/mute-all |
chat.group.manage |
全员禁言开关 |
| DELETE | /conversations/:id/members/:user_id |
chat.group.manage |
移出成员 |
| PUT | /conversations/:id/members/:user_id/role |
chat.group.manage |
改成员角色 |
| PUT | /conversations/:id/members/:user_id/title |
chat.group.manage |
设成员头衔 |
| POST/DELETE | /conversations/:id/members/:user_id/mute |
chat.group.manage |
单人禁言 |
| PUT | /conversations/:id/note |
chat.note.edit |
私聊备注 |
| PUT | /conversations/:id/group-nickname |
chat.group.nickname |
我的群昵称 |
| PUT | /conversations/:id/notify-level |
chat.view |
通知级别 |
| POST | /conversations/:id/read |
chat.view |
标记已读 |
| POST | /conversations/:id/typing |
chat.view |
正在输入 |
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /conversations/:id/messages |
chat.view |
消息列表(before 向前翻页) |
| POST | /conversations/:id/messages |
chat.send |
发消息 |
| PUT | /conversations/:id/messages/:message_id |
chat.edit |
编辑自己的消息 |
| DELETE | /conversations/:id/messages/:message_id |
chat.delete |
软删除 |
| POST | /conversations/:id/messages/:message_id/read |
chat.view |
单条已读回执 |
| POST | /conversations/:id/messages/forward |
chat.send |
转发消息 |
| GET | /conversations/:id/messages/search |
chat.view |
历史搜索 |
群扩展与加密
Section titled “群扩展与加密”| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /conversations/:id/announcements |
chat.view |
群公告 |
| POST | /conversations/:id/announcements |
chat.group.manage |
发公告 |
| DELETE | /conversations/:id/announcements/:announcement_id |
chat.group.manage |
删公告 |
| GET | /conversations/:id/todos |
chat.view |
群待办 |
| POST | /conversations/:id/todos |
chat.view |
加待办 |
| PUT | /conversations/:id/todos/:todo_id |
chat.view |
勾选完成(任意成员) |
| DELETE | /conversations/:id/todos/:todo_id |
chat.view |
删待办 |
| GET | /conversations/:id/files |
chat.view |
会话内已分享文件 |
| GET | /conversations/:id/e2ee-keys |
chat.view |
取密钥信封 |
| POST | /conversations/:id/e2ee-keys |
chat.group.manage |
发布/更新密钥信封 |
发起私聊(发请求)
Section titled “发起私聊(发请求)”POST /conversations/start{ "user_id": 2, "message": "你好!", "encrypted": false }201 {"message":"chat request sent"}。这只是发请求,不创建会话。
| 状态 | 场景 |
|---|---|
409 |
已有待处理请求:a chat request is already pending |
400 |
给自己发:cannot start a chat with yourself |
接受 / 拒绝请求
Section titled “接受 / 拒绝请求”POST /consent-requests/:id/accept{ "message": "request accepted", "conversation": { "id": 5, "type": "private", "title": null } }拒绝返回 204 No Content。
POST /conversations { "title": "Family" } → 201,调用者为 ownerPOST /conversations/:id/invite { "user_id": 3, "message": "来一起" } → 201 {"message":"invite sent"}邀请同样走同意请求。公开群可由成员自助加入(POST /conversations/:id/join)。
GET /conversations/:id{ "conversation": { "id": 5, "type": "private", "title": null }, "members": [], "my_membership": { "user_id": 1, "role": "member", "group_nickname": null, "note": null, "last_read_message_id": 0 }}返回含 encrypted 标记——接入加密会话前先检查它。
POST /conversations/:id/messages| 字段 | 类型 | 说明 |
|---|---|---|
content |
string | ≤5000 字符 |
reply_to_id |
int64? | 引用某条消息 |
attachment_ids |
[]int64 | 最多 9 个 |
mentions |
[]int64 | 被 @ 的用户 id;-1 表示 @everyone |
check_id |
int64 | 红包消息 |
burn_seconds |
int | 阅后即焚:0 或 5..86400 |
content、attachment_ids、check_id 至少提供一个,否则 400 {"error":"message cannot be empty"}。
消息对象中值得留意的字段
Section titled “消息对象中值得留意的字段”| 字段 | 说明 |
|---|---|
sender_id |
发送者;判断“是不是我自己” |
sender_is_bot |
发送者是否 bot |
kind |
text | check | call | system.join | system.leave | system.mute … |
mentions |
被 @ 用户 id 列表,-1 = @everyone |
deleted_at |
软删除时间(列表已过滤) |
edited_at |
编辑时间,存在即表示改过 |
burn_seconds / burn_at |
阅后即焚倒计时 |
call_meta |
通话记录消息的结果与时长 |
列表(只能是往前翻)
Section titled “列表(只能是往前翻)”GET /conversations/:id/messages?limit=50&before=12345limit默认 50,1..100 之外会被重置为 50;before取更旧的消息;不传取最新一页;- 返回时间正序(旧 → 新),最新一条是
messages[-1]; - 没有
after,取新消息需轮询 + 按 id 去重,或改用 WebSocket。
编辑与软删除
Section titled “编辑与软删除”PUT /conversations/:id/messages/:message_id { "content": "改过了" }DELETE /conversations/:id/messages/:message_id → 204软删除写 deleted_at,列表不再返回。
POST /conversations/:id/messages/forward # 转发(目标会话在请求体中)POST /conversations/:id/read { "last_message_id": 42 } → 204POST /conversations/:id/messages/:message_id/read # 单条已读回执GET /conversations/:id/messages/search?q=季度报告&sender_id=42&from=2026-08-01&to=2026-08-31&has_attachment=true&file_name=report&limit=50所有条件可选、以 AND 组合。
| 参数 | 说明 |
|---|---|
q |
内容子串,不区分大小写 |
sender_id |
仅该发送者 |
from / to |
created_at 闭区间(RFC3339 或 Unix 秒) |
has_attachment |
仅带附件的消息 |
file_name |
附件原始文件名子串(隐含 has_attachment) |
limit |
默认 50,钳制到 1..100 |
- 只匹配普通文本消息:系统消息(
system.*)与已软删除的消息永不命中; - 结果最新在前(与按时间正序的普通列表相反);
- E2EE 会话中服务端只有密文,
q/file_name无法匹配明文,客户端应改为搜索本地解密缓存。
错误:400 参数非法、403 非成员且非公开群。
GET /conversations/:id/announcementsPOST /conversations/:id/announcementsDELETE /conversations/:id/announcements/:announcement_id成员可读,管理权限可写。
GET /conversations/:id/todosPOST /conversations/:id/todosPUT /conversations/:id/todos/:todo_id { "done": true } # 任意成员可勾选DELETE /conversations/:id/todos/:todo_idGET /conversations/:id/files直接从 message_attachments 关联得到,不重复存储,最新在前。
端到端加密(E2EE)
Section titled “端到端加密(E2EE)”会话可能被标记为 encrypted:消息以密文存储,只有持有群密钥的客户端能解密。
- 群密钥以每成员信封(X25519 公钥封装)分发,通过
GET|POST /conversations/:id/e2ee-keys存取; - 加人或轮换密钥时需更新版本;
- 服务端不代劳加解密,因此 E2EE 会话里的
content对任何读接口都是密文; - 红包消息(
kind = "check")不含明文内容,在 E2EE 会话中同样可用。
客户端接入建议:
encrypted: true的会话要么实现完整密钥流程,要么跳过并记录原因——不要把密文当明文处理。
| 状态 | 场景 |
|---|---|
400 |
消息三个字段全空;burn_seconds 非法;给自己发会话请求 |
403 |
非会话成员读消息;缺 chat.* 权限 |
409 |
已有待处理私聊请求 |