IM 即时通讯系统

Appearance

WebSocket 事件协议 ​

本文档列出所有 WebSocket 事件类型及其数据格式。

客户端 → 服务端事件 ​

auth — 手动认证 ​

json
{
  "type": "auth",
  "data": {
    "token": "jwt-token-string"
  }
}

message — 发送消息 ​

json
{
  "type": "message",
  "data": {
    "id": "msg_uuid_001",
    "fromId": "user_001",
    "toId": "user_002",
    "chatType": "single",
    "content": "你好！",
    "contentType": "text",
    "replyTo": "",
    "imageUrl": ""
  }
}
字段类型必填限制说明
idstring是-客户端生成的消息唯一 ID（UUID）
fromIdstring是-发送者用户 ID
toIdstring是-接收者 ID（私聊为用户 ID，群聊为群 ID）
chatTypestring是-single 或 group
contentstring是最长 10000 字符消息内容
contentTypestring否-内容类型，默认 text，可选 image
replyTostring否-回复的消息 ID
imageUrlstring否-图片 URL（contentType 为 image 时使用）

read — 标记已读 ​

json
{
  "type": "read",
  "data": {
    "chatId": "user_002"
  }
}
字段类型说明
chatIdstring聊天对象 ID（私聊为对方用户 ID，群聊为群 ID）

ping — 心跳（JSON 格式） ​

json
{ "type": "ping" }

服务端 → 客户端事件 ​

auth_success — 认证成功 ​

json
{
  "type": "auth_success",
  "data": { "userId": "user_001" }
}

auth_error — 认证失败 ​

json
{
  "type": "auth_error",
  "data": { "message": "令牌无效或已过期" }
}

WARNING

认证失败后连接将被关闭。

message — 新消息 ​

json
{
  "type": "message",
  "data": {
    "id": "msg_uuid_001",
    "fromId": "user_001",
    "toId": "user_002",
    "chatType": "single",
    "content": "你好！",
    "timestamp": 1719820800000,
    "contentType": "text",
    "replyTo": "",
    "imageUrl": "",
    "from_name": "小明",
    "from_avatar": "https://example.com/avatar.png"
  }
}

TIP

群聊消息中，服务端会自动附加 from_name 和 from_avatar 字段，方便接收端直接显示发送者信息。

ack — 消息发送确认 ​

json
{
  "type": "ack",
  "data": {
    "id": "msg_uuid_001",
    "status": "success"
  }
}

TIP

客户端发送消息后应等待 ack，确认消息已被服务端保存。

error — 错误 ​

json
{
  "type": "error",
  "data": {
    "message": "消息发送过于频繁",
    "messageId": "msg_uuid_001"
  }
}

常见错误消息：

错误信息说明
未认证未通过认证就发送消息
消息缺少必要字段message 事件缺少 id、fromId 等必填字段
消息内容过长content 超过 10000 字符
对方已将你屏蔽被对方拉黑
你已被禁言群聊中被禁言
消息发送过于频繁触发速率限制

pong — 心跳响应 ​

json
{ "type": "pong" }

kick — 被踢下线（SSO） ​

json
{
  "type": "kick",
  "data": { "reason": "您的账号在其他设备登录" }
}

friend_request — 收到好友请求 ​

json
{
  "type": "friend_request",
  "data": {
    "id": "req_001",
    "fromId": "user_002",
    "fromName": "小红",
    "createTime": 1719820800000
  }
}

friend_accepted — 好友请求被接受 ​

json
{
  "type": "friend_accepted",
  "data": {
    "friendId": "user_002",
    "friendName": "小红"
  }
}

message_revoked — 消息撤回 ​

json
{
  "type": "message_revoked",
  "data": {
    "messageId": "msg_uuid_001",
    "fromId": "user_001",
    "toId": "user_002",
    "chatType": "single"
  }
}

TIP

客户端收到后应从本地消息列表中移除或标记该消息为已撤回。

群聊相关事件 ​

group_member_quit — 成员退出/被踢 ​

json
{
  "type": "group_member_quit",
  "data": {
    "groupId": "group_001",
    "userId": "user_002"
  }
}

group_dissolved — 群聊已解散 ​

json
{
  "type": "group_dissolved",
  "data": { "groupId": "group_001" }
}

TIP

客户端收到后应提示用户并跳转到群列表页。

group_transfer — 群主转让 ​

json
{
  "type": "group_transfer",
  "data": {
    "groupId": "group_001",
    "newOwnerId": "user_002"
  }
}

group_member_mute — 成员禁言状态变更 ​

json
{
  "type": "group_member_mute",
  "data": {
    "groupId": "group_001",
    "targetUserId": "user_002",
    "muted": true
  }
}

group_member_kick — 被踢出群（仅发给被踢者） ​

json
{
  "type": "group_member_kick",
  "data": {
    "groupId": "group_001",
    "targetUserId": "user_002"
  }
}

group_announcement — 群公告更新 ​

json
{
  "type": "group_announcement",
  "data": {
    "groupId": "group_001",
    "announcement": "本周六下午 3 点团建"
  }
}

group_invite — 群邀请 ​

json
{
  "type": "group_invite",
  "data": {
    "groupId": "group_001",
    "groupName": "技术交流群",
    "inviterName": "小明"
  }
}

TIP

客户端收到后可弹窗提示用户，提供"加入"或"忽略"选项。

事件总览 ​

方向事件类型说明
C→Sauth手动认证
C→Smessage发送消息
C→Sread标记已读
C→Sping心跳
S→Cauth_success认证成功
S→Cauth_error认证失败
S→Cmessage新消息
S→Cack消息确认
S→Cerror错误通知
S→Cpong心跳响应
S→Ckick被踢下线
S→Cfriend_request好友请求
S→Cfriend_accepted好友已接受
S→Cmessage_revoked消息撤回
S→Cgroup_member_quit成员退出
S→Cgroup_dissolved群已解散
S→Cgroup_transfer群主转让
S→Cgroup_member_mute禁言变更
S→Cgroup_member_kick被踢出群
S→Cgroup_announcement公告更新
S→Cgroup_invite群邀请