公共对象

本页集中说明 HTTP 与实时事件共用的对象。对象中的完整字段应原样保留，null 不应替换成缺失字段。示例身份为陈悦与林舟，时间仅用于展示结构。

User

公开用户资料不包含密码、手机号或宿主登录态。

json

{
  "id": "1025",
  "user_id": "linzhou",
  "username": "linzhou",
  "nickname": "林舟",
  "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
  "signature": "把每一次出发安排妥当",
  "profile_updated_at": 1792301400000
}

字段	类型	含义
id	string	IM 内部用户 ID
user_id	string	宿主外部用户 ID
username	string \| null	可检索账号
nickname / avatar / signature	string	昵称、头像绝对 URL、签名
profile_updated_at	integer	资料版本时间，Unix 毫秒

Presence 为 { "online": true, "online_updated_at": 1792301400000 }，也可为 null。在线状态是读取时快照，与公开资料版本独立；不能仅凭资料更新时间判断在线新旧。

Conversation

单聊完整对象：

json

{
  "conversation_id": "friend_bGluemhvdQ",
  "type": "friend",
  "target_id": "linzhou",
  "name": "林舟",
  "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
  "member_count": null,
  "group_role": null,
  "all_muted": false,
  "send_forbidden_until": 0,
  "last_mid": "8601",
  "last_seq": "18",
  "read_seq": "18",
  "peer_read_seq": "17",
  "announcement_updated_at": 0,
  "announcement_unread": false,
  "mention_unread": false,
  "updated_at": 1792301401000,
  "last_message_time": 1792301401000,
  "last_message": {
    "mid": "8601",
    "conversation_seq": "18",
    "sender_id": "chenyue",
    "sender_name": null,
    "type": "text",
    "status": "normal",
    "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
    "file_name": null,
    "created_at": 1792301401000,
    "updated_at": 1792301401000
  },
  "unread_count": 0,
  "pinned": false,
  "muted": false,
  "state": "chatting",
  "peer": {
    "id": "1025",
    "user_id": "linzhou",
    "username": "linzhou",
    "nickname": "林舟",
    "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
    "signature": "把每一次出发安排妥当",
    "profile_updated_at": 1792301400000
  },
  "peer_presence": {
    "online": true,
    "online_updated_at": 1792301400000
  }
}

群聊使用 type="group"，target_id=group_id，包含完整 group，group_role 为 owner / admin / member，member_count 为整数。单聊含完整 peer 与可空 peer_presence；群聊的 peer_read_seq、peer_presence 为 null。

字段	类型	说明
conversation_id / type / target_id	string	会话身份；type 为 friend 或 group
name / avatar	string	当前用户视角展示名称和头像
last_mid / last_seq	string	最新消息 ID、会话内最新序号；空会话为 `"0"`
read_seq / peer_read_seq	string \| null	本人 / 对端已读边界；群无对端已读
updated_at / last_message_time	integer	内容版本、最新消息时间，毫秒
last_message	object \| null	最新消息摘要；字段如示例
unread_count	integer \| null	个人未读，0–100；100 表示 99+
pinned / muted	boolean \| null	个人置顶、免打扰
state	string \| null	`chatting` 或 `hidden`；共享群事件可无个人状态
all_muted	boolean	群全员禁言
send_forbidden_until	integer \| null	本人禁言截止毫秒；0 表示未禁言
announcement_updated_at	integer	群公告版本毫秒；单聊为 0
announcement_unread / mention_unread	boolean \| null	个人公告 / @ 未读

共享群消息事件的 read_seq、unread_count、pinned、muted、state、group_role、send_forbidden_until、announcement_unread、mention_unread 可为 null，客户端保留既有私有值并依据消息归约。

Message

json

{
  "mid": "8601",
  "client_message_id": "outing-20261018-01",
  "conversation_id": "friend_bGluemhvdQ",
  "conversation_seq": "18",
  "sender_id": "chenyue",
  "sender": {
    "id": "1024",
    "user_id": "chenyue",
    "username": "chenyue",
    "nickname": "陈悦",
    "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
    "signature": "一起发现沿途的风景",
    "profile_updated_at": 1792301400000
  },
  "type": "text",
  "status": "normal",
  "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
  "mentions": null,
  "media": null,
  "contact": null,
  "system": null,
  "quote": null,
  "recalled_by": null,
  "recalled_at": null,
  "deleted_at": null,
  "created_at": 1792301401000,
  "updated_at": 1792301401000
}

字段	类型	说明
mid / conversation_id / conversation_seq	string	全局消息 ID、会话 ID、会话内严格序号
client_message_id	string \| null	发送者自定义幂等 ID；其他接收者为 null
sender_id / sender	string \| null / User \| null	非系统消息含完整发送者；系统消息为 null
type	string	`text`、`image`、`voice`、`video`、`file`、`contact`、`system`、`unsupported`
status	string	`normal`、`recalled`、`deleted`
text	string \| null	文字内容
mentions	object \| null	`{type:"all"}` 或 `{type:"users",user_ids:[...]}`
media	object \| null	媒体资源，见媒体
contact	object \| null	`{user_id,nickname,avatar}` 名片快照，avatar 可空
system	object \| null	`{code,text,params}`，params 为对象
quote	object \| null	`{mid,sender_id,sender_name,type,preview}` 引用快照，preview 可空
recalled_by / recalled_at	string \| null / integer \| null	撤回人外部 ID / 撤回时间
deleted_at	integer \| null	当前账号删除时间
created_at / updated_at	integer	创建 / 更新毫秒

撤回与删除后内容字段为 null；删除 tombstone 保留原 mid 和 conversation_seq 供时间线消费序号，界面不再渲染该气泡。不要将缺少正文的消息当成序号缺口。

Group

json

{
  "group_id": "6284173029",
  "owner_id": "chenyue",
  "name": "秋日海岸出游",
  "avatar": "https://example.com/uploads/avatars/group/6284173029/1792301400.webp",
  "avatar_custom": false,
  "announcement": "周六 8:30 公司楼下集合，请带好防晒用品。",
  "announcement_author_id": "chenyue",
  "announcement_author_name": "陈悦",
  "announcement_updated_at": 1792301400000,
  "status": "active",
  "all_muted": false,
  "join_approval_required": false,
  "member_count": 2,
  "unread_mode": "fanout",
  "last_mid": "0",
  "last_seq": "0",
  "last_message_at": 0,
  "conversation_updated_at": 1792301400000,
  "created_at": 1792301400000,
  "updated_at": 1792301400000
}

status 为 active / disabled / dissolved；unread_mode 为 fanout / sequence。后者由服务端管理，不是客户端可设置选项。群公开资料与当前账号的 Membership 分开更新。

Membership 与群权限

json

{
  "membership": {
    "conversation_id": "group_6284173029",
    "status": "active",
    "role": "owner",
    "remark": "",
    "conversation_state": "hidden",
    "pinnable": false,
    "pinned": false,
    "muted": false,
    "announcement_unread": false,
    "send_forbidden_until": 0,
    "joined_at": 1792301400000,
    "updated_at": 1792301400000
  },
  "permissions": {
    "send_message": true,
    "rename_group": true,
    "edit_announcement": true,
    "edit_remark": true,
    "add_member": true,
    "remove_member": true,
    "manage_admins": true,
    "manage_mute": true,
    "manage_join_approval": true,
    "share_group": true,
    "dissolve_group": true,
    "leave_group": false
  }
}

membership.status 还可能为 left / removed / dissolved，此时会话隐藏、权限关闭。role 为 owner / admin / member。界面直接使用 permissions 判断操作，不要仅根据角色猜测；群禁用、全员禁言和个人禁言都会影响权限。

GroupMember

json

{
  "user": {
    "id": "1025",
    "user_id": "linzhou",
    "username": "linzhou",
    "nickname": "林舟",
    "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
    "signature": "把每一次出发安排妥当",
    "profile_updated_at": 1792301400000
  },
  "presence": {
    "online": true,
    "online_updated_at": 1792301400000
  },
  "display_name": "林舟",
  "role": "member",
  "send_forbidden_until": 0,
  "joined_at": 1792301400000,
  "updated_at": 1792301400000
}

presence 可空，成员排序与分页由服务端提供。

UserProfile

json

{
  "ip_region": null,
  "conversation_id": "friend_bGluemhvdQ",
  "user": {
    "id": "1025",
    "user_id": "linzhou",
    "username": "linzhou",
    "nickname": "林舟",
    "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
    "signature": "把每一次出发安排妥当",
    "profile_updated_at": 1792301400000
  },
  "presence": {
    "online": true,
    "online_updated_at": 1792301400000
  },
  "relation": {
    "status": "friend",
    "blocked": false,
    "remark": "",
    "display_name": "林舟",
    "initial": "L",
    "updated_at": 1792301400000
  },
  "conversation_settings": {
    "available": true,
    "pinnable": true,
    "pinned": false,
    "muted": false
  },
  "permissions": {
    "message": true,
    "set_remark": true,
    "add_friend": false,
    "block_user": true,
    "report_user": true
  }
}

relation.status 为 friend / stranger；conversation_settings 为当前账号私有设置；permissions 是当前可用操作。修改关系的响应另含可空 event_id。

Notice

json

{
  "notice_id": "3101",
  "type": "friend_request",
  "direction": "received",
  "status": "pending",
  "message": "我是行政部陈悦，一起确认秋日海岸出游安排吧。",
  "source": "search",
  "created_at": 1792301400000,
  "updated_at": 1792301400000,
  "handled_at": null,
  "actor": {
    "id": "1024",
    "user_id": "chenyue",
    "username": "chenyue",
    "nickname": "陈悦",
    "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
    "signature": "一起发现沿途的风景",
    "profile_updated_at": 1792301400000
  },
  "recipient": {
    "id": "1025",
    "user_id": "linzhou",
    "username": "linzhou",
    "nickname": "林舟",
    "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
    "signature": "把每一次出发安排妥当",
    "profile_updated_at": 1792301400000
  },
  "subject": null,
  "group": null,
  "permissions": {
    "accept": true,
    "reject": true
  }
}

type：friend_request / group_join_request / group_invitation。
direction：received / sent。
status：pending / accepted / rejected / expired / revoked。
好友申请的 group=null；入群申请和群邀请含完整 Group。
群邀请的 subject 为被邀请 User；其他类型为 null。
handled_at 在 pending 时为 null；permissions 决定是否可以同意、拒绝。

用户预置与 Token

首页与会话

消息

上传与下载

用户、好友与申请

群与成员

搜索

音视频通话

随附宿主账号

设备与推送

举报与诊断

公共对象

User

Conversation

Message

Group

Membership 与群权限

GroupMember

UserProfile

Notice

公共对象 ​

User ​

Conversation ​

Message ​

Group ​

Membership 与群权限 ​

GroupMember ​

UserProfile ​

Notice ​

公共对象

User

Conversation

Message

Group

Membership 与群权限

GroupMember

UserProfile

Notice