15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

唯一客服复用后台融云配置 config.system_message_sender_user_id 指定的 APP 用户。客服昵称和头像实时读取该用户，融云身份固定为粉丝身份 tieup_fan_{user_id}。未配置客服、融云配置未启用、AppKey/AppSecret 缺失或配置用户不可用时，相关接口返回 422 业务错误。

15.0.1 获取唯一客服

GET /tieup/api/v1/customer-service
Authorization: Bearer <access_token>

请求参数：无。

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "user_id": 10001,
    "nickname": "Tieup客服",
    "avatar": "https://cdn.example.com/avatar/customer.jpg",
    "rong_user_id": "tieup_fan_10001"
  }
}

响应字段：

字段	类型	说明
`user_id`	integer	配置客服对应的 APP 用户 ID
`nickname`	string	配置用户当前昵称
`avatar`	string	配置用户当前头像 URL，未设置时为空字符串
`rong_user_id`	string	客服固定粉丝融云身份，格式 `tieup_fan_{user_id}`

15.0.2 客服 H5 登录

POST /tieup/api/v1/customer-service/h5/login
Content-Type: application/json

{
  "phone": "13800138000",
  "password": "CustomerPass123"
}

鉴权：无需 Bearer Token，也不要求 X-App-* 请求头。客服 H5 工作台接口永久排除 APP/H5 应用层加密中间件，但仍必须使用 HTTPS；服务端只校验当前配置客服本人手机号和 APP 密码。其他 APP 用户即使凭据正确也不能登录。错误手机号、错误密码和非配置用户统一返回“手机号或密码不正确”。

密码规则：客服 H5 不维护独立密码，唯一密码散列为绑定用户的 tieup_user.password_hash。管理员在后台融云配置页设置客服登录密码、用户通过 APP 找回密码或修改密码，都会更新同一 APP 用户密码；H5 随即使用最新密码。密码明文、散列或掩码不会写入融云配置，也不会通过接口返回。

请求字段：

字段	类型	必填	说明
`phone`	string	是	配置客服 APP 用户手机号，必须为 11 位中国大陆手机号
`password`	string	是	配置客服 APP 登录密码，6–64 位

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "access_token": "app_access_token",
    "refresh_token": "app_refresh_token",
    "expires_in": 7200,
    "user": {
      "id": 10001,
      "rong_user_id": "tieup_fan_10001",
      "group_code": "default",
      "channel_code": "official",
      "phone": "13800138000",
      "nickname": "Tieup客服",
      "avatar": "https://cdn.example.com/avatar/customer.jpg",
      "profile_completion_step": 2,
      "gender": 0,
      "age": null,
      "province_code": null,
      "province_name": null,
      "city_code": null,
      "city_name": null,
      "district_code": null,
      "district_name": null,
      "signature": "",
      "status": 1,
      "is_idol": 2,
      "candy_balance": "0",
      "online_status": 1,
      "current_identity": "fan",
      "available_identities": ["fan"]
    },
    "im": {
      "app_key": "rongcloud_app_key",
      "rong_user_id": "tieup_fan_10001",
      "token": "rongcloud_user_token"
    }
  }
}

响应字段：

字段	类型	说明
`access_token`	string	APP `api` Access Token，后续上下文、资料查询和退出接口使用
`refresh_token`	string	客服 H5 专用 Refresh Token，仅用于 `POST /tieup/api/v1/customer-service/h5/refresh-token`
`expires_in`	integer	Access Token 有效期，单位秒
`user`	object	完整 APP 用户资料，字段与普通 APP 登录一致；`current_identity` 固定为 `fan`
`im.app_key`	string	浏览器初始化融云 SDK 使用的 AppKey
`im.rong_user_id`	string	客服固定粉丝融云身份
`im.token`	string	浏览器连接融云使用的客户端 Token，不得记录到日志

登录失败限流：配置客服用户维度 10 分钟最多 5 次；设备 ID 或 IP 维度 10 分钟最多 10 次。

15.0.2a 刷新客服 H5 Token

POST /tieup/api/v1/customer-service/h5/refresh-token
Content-Type: application/json

{
  "refresh_token": "app_refresh_token"
}

鉴权：无需 Bearer Token，不要求 X-App-* 请求头。服务端解析 Refresh Token，并校验令牌用户仍是后台当前配置客服；换绑、清空配置、禁用客服用户或令牌用户不匹配时拒绝刷新。成功响应字段与 15.0.2 登录接口一致，返回新的 access_token、refresh_token、expires_in 和 user。

请求字段：

字段	类型	必填	说明
`refresh_token`	string	是	客服登录或上次刷新签发的 Refresh Token

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "access_token": "new_app_access_token",
    "refresh_token": "new_app_refresh_token",
    "expires_in": 7200,
    "user": {
      "id": 10001,
      "rong_user_id": "tieup_fan_10001",
      "group_code": "default",
      "channel_code": "official",
      "phone": "13800138000",
      "nickname": "Tieup客服",
      "avatar": "https://cdn.example.com/avatar/customer.jpg",
      "profile_completion_step": 2,
      "gender": 0,
      "age": null,
      "province_code": null,
      "province_name": null,
      "city_code": null,
      "city_name": null,
      "district_code": null,
      "district_name": null,
      "signature": "",
      "status": 1,
      "is_idol": 2,
      "candy_balance": "0",
      "online_status": 1,
      "current_identity": "fan",
      "available_identities": ["fan"]
    }
  }
}

响应字段：

字段	类型	说明
`access_token`	string	新签发的客服 APP Access Token
`refresh_token`	string	新签发的客服 APP Refresh Token；旧 Refresh Token 已加入黑名单
`expires_in`	integer	Access Token 有效期，单位秒
`user`	object	当前配置客服完整 APP 用户资料，字段与 15.0.2 的 `user` 一致，`current_identity` 固定为 `fan`

刷新响应不返回 im；客服工作台保留登录时的融云上下文快照，并通过 15.0.3 上下文接口定期取得最新配置。

15.0.2b 退出客服 H5

POST /tieup/api/v1/customer-service/h5/logout
Authorization: Bearer <access_token>

鉴权：需要当前配置客服的有效 Bearer Token，不要求 X-App-* 请求头。服务端校验客服资格后将 Access Token 加入黑名单；无论接口是否成功，客户端都应清理本地客服登录缓存。

请求字段：无。

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": []
}

响应字段：

字段	类型	说明
`data`	array	成功时为空数组

客服工作台最近会话说明：

最近会话和聊天历史以融云云端为权威；跨浏览器或跨设备恢复需要在融云控制台开通“单群聊消息云存储”。
会话列表、排序、未读数和聊天历史全部由融云提供；项目不使用浏览器 localStorage 或数据库缓存会话、消息正文、媒体地址或 Token。最近会话使用 IMLib 5.42.1 官方 createConversationListLoader()，聊天历史继续由 IMKit <message-list> 加载。
登录后工作台读取最近 50 个普通单聊并打开第一条合法会话；“最近会话”右侧“刷新”重新读取第一页，底部“拉取更多”继续每批读取 50 个更早会话。融云会话允许 latestMessage=null，此时展示“暂无消息”且不读取消息字段；空会话、空 targetId 和非单聊数据会被安全忽略。
融云初始化未完成并返回 35011 时，工作台等待 CONVERSATIONS_SYNCED 后有限重试；重试耗尽时保留当前列表并提示稍后刷新。实时会话事件缺少完整快照时，已有会话只合并合法更新项，新会话通过融云 getConversation() 补齐后再加入。融云成功返回空列表时不伪造会话，应核对 AppKey、客服融云 ID、单群聊消息云存储开通状态及保存期限。
会话对端 rong_user_id=tieup_fan_{user_id} 时显示“昵称 [粉丝]”，rong_user_id=tieup_artist_{artist_id} 时显示“艺人名 [艺人]”；同一用户的两种身份是两个独立会话。

15.0.3 获取客服 H5 上下文

GET /tieup/api/v1/customer-service/h5/context
Authorization: Bearer <access_token>

请求参数：无。服务端再次校验 Token 用户仍是当前配置客服；后台换绑、清空配置、禁用客服用户或禁用融云配置后，旧客服 Token 不能继续取得工作台上下文。

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "customer": {
      "user_id": 10001,
      "nickname": "Tieup客服",
      "avatar": "https://cdn.example.com/avatar/customer.jpg",
      "rong_user_id": "tieup_fan_10001"
    },
    "im": {
      "app_key": "rongcloud_app_key",
      "rong_user_id": "tieup_fan_10001",
      "token": "rongcloud_user_token"
    }
  }
}

响应字段：

字段	类型	说明
`customer`	object	最新客服公开资料，字段同 15.0.1
`im.app_key`	string	当前启用融云 AppKey
`im.rong_user_id`	string	当前客服粉丝融云身份
`im.token`	string	当前配置对应融云客户端 Token

客服 H5 首次恢复缓存和每 30 秒资格心跳均调用此接口；资格失效后必须断开融云并返回登录页。

15.0.4 批量获取客服会话用户资料

POST /tieup/api/v1/customer-service/h5/profiles
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "rong_user_ids": [
    "tieup_fan_20001",
    "tieup_artist_30001"
  ]
}

鉴权：需要配置客服的有效 APP Bearer Token；普通 APP 用户 Token 不可访问。本接口用于 IMKit 会话列表和消息区展示昵称头像，不返回手机号、密码或其他用户隐私字段。

请求字段：

字段	类型	必填	说明
`rong_user_ids`	string[]	是	去重融云用户 ID，1–50 个；支持现有 `tieup_fan_` 和 `tieup_artist_` 身份

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [
      {
        "rong_user_id": "tieup_fan_20001",
        "nickname": "用户20001",
        "avatar": "https://cdn.example.com/avatar/fan.jpg",
        "identity": "fan",
        "identity_label": "粉丝"
      },
      {
        "rong_user_id": "tieup_artist_30001",
        "nickname": "艺人昵称",
        "avatar": "https://cdn.example.com/avatar/artist.jpg",
        "identity": "artist",
        "identity_label": "艺人"
      }
    ]
  }
}

响应字段：

字段	类型	说明
`list`	array	可解析且用户状态正常的资料列表；无法解析或用户不可用的 ID 不返回
`list[].rong_user_id`	string	请求中的融云用户 ID
`list[].nickname`	string	粉丝身份使用 APP 昵称，艺人身份优先使用艺人昵称
`list[].avatar`	string	粉丝身份使用 APP 头像，艺人身份优先使用艺人头像
`list[].identity`	string	当前会话实际使用的身份：`fan`=粉丝身份、`artist`=艺人身份；严格按 `rong_user_id` 判断
`list[].identity_label`	string	身份中文标签：`粉丝` 或 `艺人`，客服工作台追加在会话昵称后展示

客服工作台消息和媒体全部由浏览器直接通过融云 Web SDK 收发：文本 RC:TxtMsg、图片 RC:ImgMsg、高清语音 RC:HQVCMsg、小视频 RC:SightMsg。媒体不调用项目上传接口，也不写本地聊天记录或上传记录。工作台承接 IMKit message-list 的 tapMessage 事件：语音可播放/暂停且切换会话自动停止，图片可站内全屏缩放旋转，视频可在站内弹层播放，收到的文件可点击下载；文件因跨域无法生成 Blob 时，经确认后在新标签打开融云地址。媒体地址只接受 HTTP(S)，HTTPS 页面拒绝 HTTP 混合内容。语音限制 AAC/M4A 1–60 秒；视频限制 H264/AAC MP4 1–120 秒；录音录像需要 HTTPS 和浏览器麦克风、摄像头权限。跨设备和长期历史保存期限以融云控制台“单群聊消息云存储”配置为准。

15. 融云 API 15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

Table of Contents

15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

15.0.1 获取唯一客服

15.0.2 客服 H5 登录

15.0.2a 刷新客服 H5 Token

15.0.2b 退出客服 H5

15.0.3 获取客服 H5 上下文

15.0.4 批量获取客服会话用户资料

15. 融云 API 15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

Table of Contents

#15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

#15.0.1 获取唯一客服

#15.0.2 客服 H5 登录

#15.0.2a 刷新客服 H5 Token

#15.0.2b 退出客服 H5

#15.0.3 获取客服 H5 上下文

#15.0.4 批量获取客服会话用户资料

15.0 单客服与独立 H5 工作台【已开发，待真实融云联调】

15.0.1 获取唯一客服

15.0.2 客服 H5 登录

15.0.2a 刷新客服 H5 Token

15.0.2b 退出客服 H5

15.0.3 获取客服 H5 上下文

15.0.4 批量获取客服会话用户资料