15. 融云 API 15.16 融云在线状态回调【未执行，需三方/真实联调】

Table of Contents

15.16 融云在线状态回调【未执行，需三方/真实联调】

POST /tieup/api/v1/webhooks/rongcloud/online-status-events
Content-Type: application/json

查询参数：

参数 类型 必填 说明
appKey string 是 融云 AppKey
nonce string 是 融云回调 nonce
timestamp string 是 融云回调时间戳
signature string 是 融云回调签名

请求参数：

参数 类型 必填 说明
userid string 否 融云用户 ID，兼容 userId
status string 否 融云在线状态，项目内会转换为本地 online_status
os string 否 客户端系统
clientIp string 否 客户端 IP，仅用于审计
sessionId string 否 融云会话 ID，仅用于审计和事件幂等，不参与在线状态计算
time string 否 事件发生时间

请求体示例：

[
  {
    "userid": "tieup_fan_6",
    "status": "1",
    "os": "iOS",
    "clientIp": "203.0.113.10",
    "sessionId": "ios-session-001",
    "time": 1781661600000
  }
]

响应字段：

字段 类型 说明
code integer 响应码，成功为 200
message string 响应提示
data.success_count integer 成功处理数量
data.ignored_count integer 因事件时间早于身份当前事件水位而忽略的数量；原始事件仍保留审计
data.failed_count integer 处理失败数量
data.duplicate_count integer 幂等重复数量
data.total_count integer 本次回调事件总数

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "success_count": 1,
    "ignored_count": 0,
    "failed_count": 0,
    "duplicate_count": 0,
    "total_count": 1
  }
}

说明：

  • 验签通过后写入 tieup_im_online_event。
  • 融云回调是在线状态唯一事实源。每条合法回调直接覆盖对应身份的 tieup_im_user_bind.online_status：status=0 写在线，status=1/2 立即写离线，不聚合历史 session。
  • 粉丝身份另外镜像 tieup_user.online_status；艺人身份只更新对应艺人绑定，不会覆盖粉丝状态。
  • 身份绑定通过 last_online_event_time_ms 按毫秒保护事件顺序；旧事件保留完整审计但标记 tieup_im_online_event.handle_status = 4，不覆盖较新状态，并计入 ignored_count。未匹配用户时 handle_status = 3。
  • sessionId、os、clientIp 等字段只用于审计，服务端不查询、不缓存本机在线会话，也不将其用于在线状态计算。
  • 服务端按 rong_user_id + session_id + event_time + status 生成 event_hash 幂等键，重复回调不重复落事件；缺少会话和时间时追加原始回调哈希兜底。
  • 测试状态：已完成代码实现、数据库升级脚本和 PHP 语法检查，待融云在线状态回调真实联调。