使用者同步

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 時間。