Open API / 同步 IM 建号

同步 IM 建号

平台用户需要进直播 IM 时调用。按众享号确保本地账号，并导入腾讯云 IM。已有映射时只补导入，不重复建号。

RSA2 仅服务端 application/json

POST /v1/im/account/sync

签名算法见签名规范。本页只写本接口的 PATH、字段和错误码。管理端须给应用勾选「同步 IM 建号」。

调用时机

平台侧用户已存在，需要在直播 IM 建号或确认号已导入时调用。不要用本接口代替 H5 注册。

userNo 是平台众享号。本地还没有这个众享号的映射时，phone 必填，服务按手机号建本地号再导入 IM。已有映射时 phone 可省略。password 填写时一并写入登录密码：新建本地号直接落库，已有本地号则覆盖原密码。location 填写时写入本地 tag_profile_im_location，并同步到腾讯标准资料字段 Tag_Profile_IM_Location（不是自定义字段）；已有地区且本次未传时，重同步仍会把库里的地区补写到腾讯。

签名 PATH

项	值
METHOD	`POST`
HTTP 路径	`/v1/im/account/sync`
签名 PATH	`/api/open/v1/im/account/sync`
测试 URL	`https://test-chat-live-open-go.gyyx.store/v1/im/account/sync`
生产 URL

请求体

字段	类型		约束	说明
`userNo`	string	必填	最长 32	平台众享号
`phone`	string	条件	11 位手机号	无映射时必填。已有映射时可省略；填写则必须与已同步手机号一致
`nickname`	string	可选	最长 100	新建本地号时的昵称。空则自动生成
`avatar`	string	可选	http(s)，最长 512	新建本地号时的头像
`password`	string	可选	6-64 位	登录密码。新建本地号时直接写入；已有账号时覆盖原密码（账号无盐值时跳过）
`location`	string	可选	最长 128	地区 / 所在地。落库后写入腾讯 `Tag_Profile_IM_Location`，供好友列表等展示

json

{
  "userNo": "69493154",
  "phone": "13800138000",
  "nickname": "晚风",
  "avatar": "https://cdn.example.com/a.png",
  "password": "Abc123",
  "location": "中国-北京-朝阳"
}

响应

统一信封。鉴权失败多为 HTTP 4xx；业务失败多为 HTTP 200 且 code != 0。

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "imUserId": "42",
    "userNo": "69493154",
    "created": true
  }
}

字段	说明
`imUserId`	直播侧 IM 账号，等于本地用户 id
`userNo`	请求里的众享号
`created`	`true` 表示本次新建了本地号；已有号再导入为 `false`

错误码

HTTP	code	message	处理
400	400	缺少必要请求头 / 签名无效 / 参数错误 / 密码长度需在 6-64 之间	同签名规范；并检查 `userNo`、`phone`、`avatar`、`password`、`location`
403	403	接口未授权	在管理端勾选「同步 IM 建号」
200	404	用户不存在	映射指向的本地号已不在
200	4091	手机号已绑定其他众享号	不要改绑，改用原众享号
200	4092	手机号与已同步账号不一致	省略 phone，或传已同步的手机号
200	4102	账号已禁用或注销	不要重试
200	5610	IM 建号失败	按重试策略重试。本地号可能已写下，重试不会重复建号

重试

结果	是否重试
超时、连接失败、`5610`	是。1s / 2s / 4s，最多 3 次。请求体保持不变
`429`	是。至少间隔 1 秒
`400` / `403` / `404` / `4091` / `4092` / `4102` / `0`	否

重试须更换 X-YS-Timestamp、X-YS-Nonce，建议更换 X-YS-Request-Id，并对同一份 body 重新签名。

调用示例

http

POST /v1/im/account/sync HTTP/1.1
Host: test-chat-live-open-go.gyyx.store
Content-Type: application/json
X-YS-App-Id: ys_app_asset
X-YS-Timestamp: 1756610000
X-YS-Nonce: a1b2c3d4e5f67890
X-YS-Request-Id: req_001
X-YS-Sign-Type: RSA2
X-YS-Key-Version: v1
X-YS-Signature: <RSA2 Base64>

{"userNo":"69493154","phone":"13800138000","nickname":"晚风","location":"中国-北京-朝阳"}