消息收发

发送消息（HTTP）

POST JWT

/api/message/send

通过 HTTP 接口发送消息。适用于 WebSocket 不可用的降级场景。消息会通过 WebSocket 实时推送给在线接收方，离线用户触发 Web Push 通知。

请求参数：

字段	类型	必填	说明
toId	string	是	接收方 ID（用户 ID 或群 ID）
chatType	string	是	聊天类型："single" 或 "group"
content	string	是	消息内容，最长 10000 字符
contentType	string	否	内容类型，默认 "text"，可选 "image"
replyTo	string	否	引用的消息 ID
imageUrl	string	否	图片 URL（contentType 为 image 时必填）

请求示例：

curl -X POST http://localhost:3000/api/message/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "toId": "u_def456",
    "chatType": "single",
    "content": "你好！"
  }'

成功响应：

{
  "code": 200,
  "message": "消息发送成功",
  "data": {
    "id": "msg_xyz789",
    "timestamp": 1719000000000
  }
}

错误场景：

条件	响应
被对方屏蔽	{ "code": 403, "msg": "对方已将你屏蔽" }
群聊中被禁言	{ "code": 403, "msg": "你已被禁言" }
非群成员	{ "code": 403, "msg": "你不是该群成员" }

注意

推荐使用 WebSocket 发送消息以获得更好的实时性。HTTP 接口主要用于兼容场景或服务端主动推送。

---

发送消息（WebSocket）

通过 WebSocket 发送 message 类型消息，是推荐的发送方式。

{
  "type": "message",
  "data": {
    "id": "msg_1719000000_a1b2c3",
    "fromId": "u_abc123",
    "toId": "u_def456",
    "chatType": "single",
    "content": "你好！",
    "contentType": "text",
    "replyTo": "",
    "imageUrl": ""
  }
}

发送后服务端会返回 ack 确认：

{
  "type": "ack",
  "data": {
    "id": "msg_1719000000_a1b2c3",
    "status": "success"
  }
}

消息 ID 生成规则

前端生成，格式为 msg_{timestamp}_{random}，如 msg_1719000000_a1b2c3。确保唯一性即可。

详细的 WebSocket 协议请参考 WebSocket 消息类型。

---

获取历史消息

GET JWT

/api/history

分页获取聊天历史消息，按时间升序返回。自动排除已撤回的消息。

查询参数：

参数	类型	必填	说明
type	string	是	聊天类型："single" 或 "group"
fromId	string	单聊必填	发送方 ID（当前用户 ID）
toId	string	是	接收方 ID（对方用户 ID 或群 ID）
before	number	否	时间戳，获取此时间之前的消息（用于向上翻页加载更多）
limit	number	否	每页数量，默认 50，最大 100

请求示例：

# 获取最近 50 条消息
curl "http://localhost:3000/api/history?type=single&fromId=u_abc123&toId=u_def456" \
  -H "Authorization: Bearer <token>"

# 加载更多（获取某时间戳之前的 50 条）
curl "http://localhost:3000/api/history?type=single&fromId=u_abc123&toId=u_def456&before=1719000000000&limit=50" \
  -H "Authorization: Bearer <token>"

# 获取群聊历史
curl "http://localhost:3000/api/history?type=group&toId=g_abc123" \
  -H "Authorization: Bearer <token>"

成功响应：

{
  "code": 200,
  "data": [
    {
      "id": "msg_001",
      "from_id": "u_abc123",
      "to_id": "u_def456",
      "type": "single",
      "content": "你好！",
      "timestamp": 1719000000000,
      "content_type": "text",
      "reply_to": "",
      "image_url": ""
    }
  ],
  "hasMore": true
}

TIP

hasMore 为 true 表示还有更早的消息可以加载。

---

撤回消息

POST JWT

/api/message/revoke

撤回已发送的消息。仅支持撤回自己的消息，且发送时间不超过 2 分钟。撤回后，相关用户会通过 WebSocket 收到 message_revoked 通知。

请求参数：

字段	类型	必填	说明
messageId	string	是	要撤回的消息 ID

请求示例：

curl -X POST http://localhost:3000/api/message/revoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{ "messageId": "msg_001" }'

成功响应：

{
  "code": 200,
  "message": "消息已撤回"
}

错误场景：

条件	响应
非本人消息	{ "code": 403, "msg": "只能撤回自己的消息" }
超过 2 分钟	{ "code": 400, "msg": "超过撤回时限" }
消息不存在	{ "code": 404, "msg": "消息不存在" }

---

消息内容类型

contentType	说明	content 字段
text	文本消息	文本内容
image	图片消息	图片 URL（配合 imageUrl 字段）

前端可根据 contentType 决定消息的渲染方式。默认值为 text。