User synchronization
POST /api/open/v1/users/sync
Use request signing. The first request creates a user by userId; subsequent requests update that user in the same workspace. Sync before submitting chat input.
json
{"userId":"u-1001","nickname":"Alex","avatarUrl":"https://cdn.example.com/avatar.png","gender":"MALE","age":25,"country":"China","region":"Zhejiang","city":"Hangzhou","language":"en","timezone":"Asia/Shanghai","utcOffsetMinutes":480,"status":"ACTIVE","tags":["new user"]}Fields
| Field | Required | Constraint / behavior when omitted |
|---|---|---|
userId | Yes | At most 128 characters; must not start with test: |
nickname | No | At most 100 characters; cleared when omitted |
avatarUrl | No | HTTP(S) URL, at most 1,024 characters; cleared when omitted |
gender | No | UNKNOWN, MALE, FEMALE, OTHER; defaults to UNKNOWN |
age | No | 0–150; cleared when omitted |
country / region / city | No | At most 100 characters each; cleared when omitted |
language | No | Valid language tag, at most 35 characters, such as en; cleared when omitted |
timezone | No | Valid time zone, at most 64 characters, such as Asia/Shanghai; cleared when omitted |
utcOffsetMinutes | No | Integer minutes from -840 to 840; cleared when omitted |
status | No | ACTIVE or BLOCKED; defaults back to ACTIVE when omitted |
tags | No | At most 20 tags of up to 40 characters each; defaults to an empty list |
Full synchronization, not a partial update
Send the complete current profile each time. Omitted fields are cleared or defaulted, including console-managed tags and status. Explicitly send BLOCKED to keep a user blocked. Console operator notes are preserved.
Response
json
{"code":"OK","message":"success","data":{"userId":"u-1001","created":true,"nickname":"Alex","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"}}This example corresponds to syncing only userId and nickname. created identifies the first synchronization; other fields reflect the saved profile. updatedAt is a UTC ISO 8601 timestamp.