泡泡 IM

外观

获取 IM Token ​

宿主后端确认用户已登录后，调用此接口获取用户的 IM Token，再把结果交给客户端 SDK。每次调用都会创建或同步该用户的公开资料。

POST /app/sdk/token

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

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

请求参数 ​

JSON Body ​

参数类型必填说明
user_idstring是宿主账号的稳定、唯一 ID，1–64 字符，不含控制字符和首尾空白。昵称改变时不要改变此 ID。
nicknamestring是用户昵称，1–80 字符，不含控制字符和首尾空白。
usernamestring | null否用于账号搜索，非空时 1–64 字符。不传或传 null 会将该值同步为空。
avatarstring | null否头像地址，最长 1024 字符。不传、空字符串或 null 使用默认头像。
signaturestring | null否个性签名，最长 255 字符。不传或 null 同步为空字符串。
platformstring条件条件必填。选择推送应用的平台：ios、android、harmony。与 manufacturer、package_name 一起提交；也可三项都不传。
manufacturerstring条件条件必填。厂商标识，1–64 位小写字母或数字开头，后续允许点、下划线、连字符。iOS 固定 apple；未知厂商使用 unknown。
package_namestring条件条件必填。应用包名或 Bundle ID，最长 255 字符。iOS 用点分字母、数字、连字符；Android/HarmonyOS 各段以字母开头，后续允许字母、数字、下划线。

标有条件的必填项，只在相应操作或配置下需要提交。

请求示例 ​

bash
curl 'https://example.com/app/sdk/token' \
  -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":"一起发现沿途的风景","platform":"ios","manufacturer":"apple","package_name":"com.example.office"}'

使用说明 ​

  • sdkSecret 只保存在宿主后端，不能放到网页、App 或小程序中。
  • 资料由宿主管理时，每次提交最新完整资料，避免昵称或账号被旧值覆盖。
  • 推送应用优先按包名精确匹配，找不到时使用默认应用；精确匹配到已关闭的应用时不会回退。

返回参数 ​

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

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

data 字段 ​

字段类型说明
userUser同步后的用户资料。
tokenstring用户的 IM Token，供 SDK 登录以及调用用户接口。
expire_atintegerToken 过期时间，Unix 秒时间戳。
pushPush当前应用可使用的客户端推送配置。

返回示例 ​

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

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "user": {
      "id": "1024",
      "user_id": "chenyue",
      "username": "chenyue",
      "nickname": "陈悦",
      "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
      "signature": "一起发现沿途的风景",
      "profile_updated_at": 1792301400000
    },
    "token": "<签名后的 IM Token>",
    "expire_at": 1792305000,
    "push": {
      "enabled": false,
      "provider": null,
      "alias": "u_1024",
      "alias_type": "im_user",
      "ios": null,
      "android": null,
      "harmony": null
    }
  }
}

返回对象字段 ​

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

用户资料 · 客户端推送配置 · iOS 客户端推送配置 · Android / HarmonyOS 客户端推送配置

用户资料（User） ​

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

客户端推送配置（Push） ​

字段类型说明
enabledboolean是否选到了已启用的推送配置。
providerstring | null启用时为 umeng，未启用时为 null。
aliasstring服务器分配的账号别名，例如 u_1024；请直接使用返回值。
alias_typestring别名类型，当前固定为 im_user。
iosPushIOS | null选中的 iOS 配置；没有可用配置时为 null。
androidPushAndroid | null选中的 Android 配置；没有可用配置时为 null。
harmonyPushAndroid | null选中的 HarmonyOS 配置；没有可用配置时为 null。
android_appsobject | null仅未提交 platform、manufacturer、package_name 的兼容返回中出现。键为 Android 包名，值为 PushAndroid 配置或 null；没有包名配置时为 null。

iOS 客户端推送配置（PushIOS） ​

字段类型说明
app_keystring友盟客户端 AppKey。
channelstring分发渠道，当前为 App Store。

Android / HarmonyOS 客户端推送配置（PushAndroid） ​

字段类型说明
app_keystring友盟客户端 AppKey。
message_secretstring友盟客户端 Message Secret，用于客户端推送接入。
channelstring分发渠道，当前为 official。

错误处理 ​

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

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

Copyright © 泡泡 IM