用户同步

POST /api/open/v1/users/sync

使用请求签名。首次以 userId 创建数据，之后更新同一空间内同一用户。请在推送私聊输入前完成同步。

{
  "userId": "u-1001",
  "nickname": "小明",
  "avatarUrl": "https://cdn.example.com/avatar.png",
  "gender": "MALE",
  "age": 25,
  "country": "中国",
  "region": "浙江",
  "city": "杭州",
  "language": "zh-CN",
  "timezone": "Asia/Shanghai",
  "utcOffsetMinutes": 480,
  "status": "ACTIVE",
  "tags": ["新用户"]
}

字段

字段	必填	约束／省略时行为
userId	是	最长 128 字符，不得以 test: 开头
nickname	否	最长 100 字；省略清空
avatarUrl	否	HTTP(S) URL，最长 1024 字符；省略清空
gender	否	UNKNOWN、MALE、FEMALE、OTHER；默认 UNKNOWN
age	否	0–150；省略清空
country / region / city	否	各最多 100 字；省略清空
language	否	有效语言标签，最多 35 字符，例如 zh-CN；省略清空
timezone	否	有效时区，最多 64 字符，例如 Asia/Shanghai；省略清空
utcOffsetMinutes	否	-840～840 的整数分钟；省略清空
status	否	ACTIVE 或 BLOCKED；省略恢复为 ACTIVE
tags	否	最多 20 个，每个最多 40 字；省略变为空列表

这是完整同步，不是部分修改

每次请传完整的最新数据。省略字段会清空或使用默认值，包括覆盖控制台的标签和状态。若用户应继续禁止交互，请明确传 BLOCKED。控制台的运营备注不受影响。

响应

{
  "code": "OK",
  "message": "success",
  "data": {
    "userId": "u-1001",
    "created": true,
    "nickname": "小明",
    "avatarUrl": null,
    "gender": "UNKNOWN",
    "age": null,
    "country": null,
    "region": null,
    "city": null,
    "language": null,
    "timezone": null,
    "utcOffsetMinutes": null,
    "status": "ACTIVE",
    "tags": [],
    "updatedAt": "2026-10-26T08:00:00Z"
  }
}

上例对应只同步 userId、nickname 的请求。created 表示是否首次创建；其余字段为保存后的数据。updatedAt 为 UTC ISO 8601 时间。