预置或同步用户

提前创建或更新一个 IM 用户。适合打开对方资料、发起聊天之前，同步尚未登录 IM 的目标用户。

POST /app/sdk/users/upsert

调用方： 宿主后端　·　认证： SDK 后端密钥

请求头：Authorization: Bearer <sdkSecret>。只允许宿主后端调用，密钥不能放到客户端。

请求参数

JSON Body

参数	类型	必填	说明
user_id	string	是	宿主账号的稳定、唯一 ID，1–64 字符，不含控制字符和首尾空白。昵称改变时不要改变此 ID。
nickname	string	是	用户昵称，1–80 字符，不含控制字符和首尾空白。
username	string | null	否	用于账号搜索，非空时 1–64 字符。不传或传 null 会将该值同步为空。
avatar	string | null	否	头像地址，最长 1024 字符。不传、空字符串或 null 使用默认头像。
signature	string | null	否	个性签名，最长 255 字符。不传或 null 同步为空字符串。

请求示例

curl 'https://example.com/app/sdk/users/upsert' \
  -H "Authorization: Bearer $POPOIM_SDK_SECRET" \
  -H 'Content-Type: application/json' \
  --data '{"user_id":"chenyue","nickname":"陈悦","username":"chenyue","avatar":"https://example.com/avatars/chenyue.jpg","signature":"一起发现沿途的风景"}'

使用说明

• 这里只同步资料，不返回 IM Token。需要让此用户登录时，调用获取 IM Token。
• username 不传或传 null 会同步为空；avatar 不传使用默认头像；signature 不传同步为空字符串。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
code	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
msg	string	成功通常为 ok，失败时为错误说明。
data	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
user	User	同步后的用户资料。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

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

返回对象字段

数组中的每个对象使用同一套字段。点击名称跳到说明：

用户资料

用户资料（User）

字段	类型	说明
id	string	IM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。
user_id	string	宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。
username	string | null	可用于精确搜索的账号；没有设置时为 null。
nickname	string	显示昵称。
avatar	string	头像地址。
signature	string	个性签名；未设置时为空字符串。
profile_updated_at	integer	公开资料最后更新时间，Unix 毫秒时间戳。

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回用户预置与 Token接口列表 · HTTP 请求约定