泡泡 IM

外观

保持通话在线 ​

通话设备定时续约，服务器据此判断参与人是否仍在线。

POST /app/sdk/calls/heartbeat

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数 ​

JSON Body ​

参数类型必填说明
call_idstring是已知通话 ID，32 位小写十六进制字符串。
device_idstring是当前安装设备的稳定标识，1–128 位字母、数字、点、下划线、冒号或连字符。同一台设备持续使用同一个值。

请求示例 ​

bash
curl 'https://example.com/app/sdk/calls/heartbeat' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"call_id":"a17e596dc4f44fba9c938ebde8ca63f2","device_id":"office-ios-01"}'

使用说明 ​

  • 按 control.heartbeat_interval_ms 调用，当前周期为 15000 毫秒。
  • Body 必须且只能包含 call_id、device_id。所有操作都返回完整通话状态，界面以回包和更新版本的实时事件为准。
  • 状态流程：ringing 振铃 → answering 待确认 → connecting 连接 → active 通话 → ended 结束。不能任意跳过步骤。
  • 使用 control.server_time 校正时间差，并按回包中的截止时间处理超时，不要每次收到回包都重新开始完整倒计时。

返回参数 ​

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

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

data 字段 ​

字段类型说明
callCall当前完整通话状态。
controlCallControl服务器时间与续约间隔。

返回示例 ​

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

展开完整返回示例
json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "call": {
      "call_id": "a17e596dc4f44fba9c938ebde8ca63f2",
      "kind": "direct",
      "media": "video",
      "status": "active",
      "version": 3,
      "creator_id": "chenyue",
      "participants": [
        {
          "user": {
            "id": "1024",
            "user_id": "chenyue",
            "username": "chenyue",
            "nickname": "陈悦",
            "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
            "signature": "一起发现沿途的风景",
            "profile_updated_at": 1792301400000
          },
          "role": "caller",
          "status": "active",
          "connected_at": 1792301400000,
          "ended_at": null
        },
        {
          "user": {
            "id": "1025",
            "user_id": "linzhou",
            "username": "linzhou",
            "nickname": "林舟",
            "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
            "signature": "把每一次出发安排妥当",
            "profile_updated_at": 1792301400000
          },
          "role": "callee",
          "status": "active",
          "connected_at": 1792301400000,
          "ended_at": null
        }
      ],
      "self": {
        "role": "caller",
        "status": "active",
        "selected_device_id": "office-ios-01",
        "lease_expires_at": 1792301445000
      },
      "ring_deadline_at": 1792301430000,
      "lease_expires_at": 1792301408000,
      "answer_expires_at": null,
      "connect_expires_at": null,
      "started_at": 1792301400000,
      "ended_at": null,
      "end_reason": null,
      "ended_by": null
    },
    "control": {
      "server_time": 1792301400000,
      "pulse_interval_ms": 3000,
      "heartbeat_interval_ms": 15000
    }
  }
}

返回对象字段 ​

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

通话状态 · 通话参与人 · 用户资料 · 本人的通话状态 · 通话计时设置

通话状态（Call） ​

字段类型说明
call_idstring通话 ID，32 位小写十六进制字符串。
kindstring通话类型，当前公开创建接口为 direct 双人通话。
mediastringaudio 语音通话；video 视频通话。
statusstringringing 振铃、answering 已接听待主叫确认、connecting 连接媒体、active 通话中、ended 已结束。
versioninteger通话状态版本，随状态变化递增；避免旧回包覆盖新状态。
creator_idstring主叫的外部 user_id。
participantsCallParticipant[]参与人及各自状态。
selfCallSelf当前账号的设备与状态。
ring_deadline_atinteger | null振铃截止时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
lease_expires_atinteger | null主叫振铃续约截止时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
answer_expires_atinteger | null主叫确认接听的截止时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
connect_expires_atinteger | null建立媒体连接的截止时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
started_atinteger | null通话开始时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
ended_atinteger | null通话结束时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
end_reasonstring | null未结束时为 null。结束原因：cancelled 主叫取消、declined 被叫拒绝、ring_timeout 无人接听、caller_unreachable 主叫失联、connect_timeout 连接超时、hangup 挂断、connection_lost 通话掉线、room_closed 房间关闭、busy 忙线。
ended_bystring | null结束操作人的外部 user_id；超时等系统结束情况可为 null。

通话参与人（CallParticipant） ​

字段类型说明
userUser参与人资料。
rolestringcaller 主叫、callee 被叫、member 其他参与人；当前创建接口为双人通话。
statusstringinvited 待接听、accepted 已接受、connecting 连接中、active 已接通、declined 已拒绝、ended 已结束。
connected_atinteger | null此人接入媒体的时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
ended_atinteger | null此人结束通话的时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。

用户资料（User） ​

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

本人的通话状态（CallSelf） ​

字段类型说明
rolestring本人角色：caller 主叫、callee 被叫、member 其他参与人。
statusstring本人状态：invited、accepted、connecting、active、declined、ended，含义同参与人状态。
selected_device_idstring | null已取得通话操作权的设备 ID；尚未选定时为 null。
lease_expires_atinteger | null本人设备必须续约的截止时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。

通话计时设置（CallControl） ​

字段类型说明
server_timeinteger服务器当前时间，用于校正客户端时钟，Unix 毫秒时间戳。
pulse_interval_msinteger主叫振铃续约间隔，单位毫秒；当前为 3000。
heartbeat_interval_msinteger通话设备心跳间隔，单位毫秒；当前为 15000。

错误处理 ​

通话未找到为 1214，无操作权限为 1215，当前状态不允许为 1216，操作权属于其他设备为 1217。

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

返回音视频通话接口列表 · HTTP 请求约定

Copyright © 泡泡 IM