用户 API

用户模块覆盖账号注册与资料、Token 签发与吊销、在线状态、封禁与注销、私聊白名单/禁言、标签与订阅、推送免打扰以及代聊能力。

模块概览​

项目值
接口数量33
幂等接口6
路径前缀/im/v2
请求方法POST（JSON 请求体）
鉴权方式App-Key / Nonce / Timestamp / Signature（见 鉴权与签名）
响应信封{ code, msg?, data?, requestId? }

接口列表​

接口方法路径说明幂等
注册用户POST/im/v2/user/register注册用户；userId 幂等（已存在则更新 name/avatarUrl 并返回现有用户）。是
更新用户资料POST/im/v2/user/update更新用户资料。否
查询用户POST/im/v2/user/get查询用户。否
签发用户 JWTPOST/im/v2/user/token/issue签发用户 JWT（供客户端 SDK connect 使用），有效期 7 天。否
查询用户在线状态POST/im/v2/user/online/check查询用户在线状态。否
封禁/解封用户POST/im/v2/user/ban封禁/解封用户；封禁后在线连接被 kick，新连接返回 1016。否
用户私聊白名单POST/im/v2/user/whitelist/add用户私聊白名单：仅白名单用户可给该用户发私聊（空表示不启用）。否
用户私聊白名单POST/im/v2/user/whitelist/remove用户私聊白名单：移除。否
用户私聊白名单POST/im/v2/user/whitelist/list用户私聊白名单：查询。否
主动作废用户全部客户端 tokenPOST/im/v2/user/token/revoke主动作废用户全部客户端 token（tokenVersion++，旧 JWT 立即失效）。否
批量获取用户资料POST/im/v2/user/batch/get批量获取用户资料（上限 100；不存在的 userId 返回在 missing）。否
设置/解除单聊禁言POST/im/v2/user/chat/mute设置/解除单聊禁言（mutedUntil=0 解除；禁言后该用户向目标发私聊返回 1009）。是
查询用户的单聊禁言列表POST/im/v2/user/chat/mute/list查询用户的单聊禁言列表。否
设置用户标签POST/im/v2/user/tag/set设置用户标签（全量覆盖，最多 20 个，每个 ≤32 字符）。是
获取用户标签POST/im/v2/user/tag/get获取用户标签。否
批量设置用户标签POST/im/v2/user/tag/batch/set批量设置用户标签（上限 100 条，返回 updated/failed）。否
获取封禁用户列表POST/im/v2/user/ban/list获取封禁用户列表（分页）。否
删除用户POST/im/v2/user/delete删除用户（开发/测试环境；物理删除用户及其会话关系）。否
清理用户托管资料POST/im/v2/user/profile/clean清理用户托管资料（保留 userId，清空 name/avatarUrl 等自定义字段）。否
设置用户订阅关系POST/im/v2/user/subscription/set设置用户订阅关系（全量覆盖，最多 100 个）。是
查询用户订阅关系POST/im/v2/user/subscription/get查询用户订阅关系。否
注销用户POST/im/v2/user/deactivate注销用户（合规能力：保留记录但禁止登录/收发，踢下线）。否
重新激活已注销用户POST/im/v2/user/reactivate重新激活已注销用户。否
查询已注销用户列表POST/im/v2/user/deactivated/list查询已注销用户列表（分页）。否
设置用户推送免打扰时段POST/im/v2/user/push/period/set设置用户推送免打扰时段（startMinute/endMinute 为当天分钟数 0-1439）。是
查询用户推送免打扰时段POST/im/v2/user/push/period/get查询用户推送免打扰时段。否
删除用户推送免打扰时段POST/im/v2/user/push/period/remove删除用户推送免打扰时段。否
将指定用户踢出其加入的所有群组POST/im/v2/user/group/kick-all将指定用户踢出其加入的所有群组（应用管理员操作）。否
开启用户代聊POST/im/v2/user/proxychat/start开启用户代聊（绑定 Agent，收到私聊时由 Agent 自动回复；回复生成依赖 AI 端点）。覆盖融云 /v3/user/proxychat/start。是
停止用户代聊POST/im/v2/user/proxychat/stop停止用户代聊。覆盖融云 /v3/user/proxychat/stop。否
查询用户代聊列表POST/im/v2/user/proxychat/list查询用户代聊列表（userId 省略返回应用全部）。覆盖融云 /v3/user/proxychat/query。否
接收托管资料审核结果并落库POST/im/v2/user/profile/moderation/sync接收托管资料审核结果并落库（approved/rejected；rejected 可回滚指定资料字段）。覆盖融云 /user/profile/sync。否
查询用户所在的群组POST/im/v2/user/group/query查询用户所在的群组（page/size 分页；page 缺省或 0 返回前 5000 个）。覆盖融云 /user/group/query.json。否

相关回调事件​

接口约定​

  • 完整请求地址 = 部署域名 + /im/v2 + 接口路径；所有接口使用 POST。
  • 请求头必须携带 App-Key / Nonce / Timestamp / Signature；签名规则见鉴权与签名。
  • 响应统一为 { code, msg?, data?, requestId? }；code = 0 表示成功。
  • 列表类接口使用 limit 分页，单页上限见限频与限制。

相关说明​