联犀开发者文档

应用控制与邀请

约 1633 字大约 5 分钟

2026-10-16

先读控制公共规则，再按 Topic、method 和方向查阅。应用侧使用鉴权命令提交、事件拉取与确认；事件结构不表示已启用 WebSocket 推送。能力可用性见支持范围。

interaction.control · APP↑

  • 方向：应用→平台；应答：interaction.result。
  • 触发、权限与状态：沿用鉴权API，服务端由登录态定位参与端，不能在arguments自报操作者。云端命令直接处理；设备执行命令转发并记录应用token与设备token映射。HTTP202后interaction.result.data.result原样给对应成功状态正文，失败仍顶层code/data.reason；独立状态经interaction.controlState投递。
  • 超时、幂等、迟到及清理采用本页公共行为和公共约定；成功应答不能代替独立完成状态。
  • 场景：录音录像与媒体播放、门铃告警与多端接听。
字段类型必填条件值与含义
commandstring必填本章设备Control/Update/Sync、capabilityReport/sessionAccept/sessionReject及inputSend/toolCallSubmit/audioStart/audioStop/respCancel；另有云端专属recordingConsent/recordingContent；禁止递归包装
argumentsobject必填对应设备命令正文；下述云端专属子命令不向设备转发
{
  "msgToken": "s15-42",
  "method": "interaction.control",
  "sessionId": "s-player",
  "params": {
    "command": "playbackControl",
    "arguments": {
      "operation": "load",
      "expectedRevision": 0,
      "playbackId": "player-1",
      "contentRef": "<authorized-recording>"
    }
  }
}

对应录音录像与媒体播放：M13；其他操作按条件字段校验。

云端录制应用子命令

子命令arguments 严格字段权限、关联和效果
recordingConsent / grantoperation=grant、recordingId、policyId、expiresAt（绝对毫秒，当前时点后且最多一小时）JWT本人且属于当前正式参与者；返回consentId/revision/expiresAt/sourceTrackIds/policyRevision。绑定原会话、原器、媒体代次、全员加入epoch和策略代次；不接受自报userId。
recordingConsent / revokeoperation=revoke、recordingId、consentId、expectedRevision仅该凭证本人；先阻断实际写入再持久撤销。重放原请求不刷新撤销时间。
recordingControl本章原start/pause/resume/stop字段原录制发起者控制；start/resume核验当前全部真实凭证。新成员加入先停副本，重新全员同意后必须显式resume。
recordingContentrecordingId原端点、当前设备权限、本人所有权、ready、策略和未撤销/未到期同意均重读；不接收URL、对象路径或存储桶。

interaction.result.data 的录制受理正文固定有 operation=interaction.control、command、recordingId，并按上述子命令携带凭证元数据或录制 state/revision。受理完成和原 interaction.controlState(recordingState) 不是同一事件；文件只有实际封装、逐轨解码、私有上传及读回校验成功才进入 ready。停止后首次固定60秒封装截止，迟到产物不允许复活终态。

录制控制在受理前确认的修订冲突、原 token 不同正文冲突或合法 resume 引用失效授权集合，原 Commands HTTP 业务信封返回 code=409、固定脱敏消息 requestConflict；HTTP 状态仍沿原入口，不返回 accepted，也不等待异步 recordingState 才判断拒绝。此类拒绝不新增操作、授权或恢复副本。非法结构与其他接口错误保持原分类，未知存储错误不能冒充确定冲突；旧 AI、IM 与 action 的共享错误适配不改变。

撤权、保留到期、当前权限失败或组件未装配时，本条内容读取投影 code=403、state=failed、reason=permissionDenied，只保留 operation/command/recordingId/revision，不夹带旧contentRef/URL；无关事件仍正常交付。签名装饰内部失败用 code=500/reason=internalError。已签发URL可能在原30秒有效窗口内仍可用，后台按实际删除确认收口；不承诺撤权能回收已被客户端下载的文件。

interaction.controlState · APP↓

  • 方向：平台→应用；应答：—。
  • 触发、权限与状态：应用独立事件携带顶层sessionId/eventSeq；与设备状态同一事实来源，不冒充请求ACK。新邀请走interaction.invite，不能用纯通知代替用户接听。
  • 超时、幂等、迟到及清理采用本页公共行为和公共约定；成功应答不能代替独立完成状态。
  • 场景：录音录像与媒体播放。
字段类型必填条件值与含义
commandstring必填对应State/Snapshot/Updated方法
resultobject必填对应正文，不丢字段
{
  "msgToken": "recording-ready-app",
  "method": "interaction.controlState",
  "sessionId": "s15-session",
  "eventSeq": 3,
  "data": {
    "command": "recordingState",
    "result": {
      "state": "ready",
      "revision": 6,
      "recordingId": "rec-1",
      "contentRef": "<authorized-recording>",
      "durationMs": 30000
    }
  }
}

对应录音录像与媒体播放：M11；其他操作按条件字段校验。

interaction.invite · APP↓

  • 方向：平台→应用；应答：interaction.control(sessionAccept/sessionReject)。
  • 触发、权限与状态：应用收到完整邀请；msgToken就是邀请token，sessionId是本端候选腿。通过interaction.control答复时沿用token；服务端原子选中首个合格接听者，其余端只撤销候选腿，不挂断胜出者。
  • 超时、幂等、迟到及清理采用本页公共行为和公共约定；成功应答不能代替独立完成状态。
  • 场景：门铃告警与多端接听。
字段类型必填条件值与含义
invitationobject必填与sessionInvite.params完全一致
endpointIdstring必填此用户的目标登录终端
callGroupIdstring必填统一呼叫组
{
  "msgToken": "invite-a",
  "method": "interaction.invite",
  "sessionId": "door-leg-a",
  "data": {
    "invitation": {
      "purpose": "humanCall",
      "callType": "video",
      "admission": "accept",
      "transport": "webrtc",
      "expiresAt": 1900000000000,
      "tracks": [
        {
          "trackId": "video-new",
          "kind": "video",
          "sourceId": "front",
          "sourceType": "camera",
          "direction": "recvonly",
          "codec": "H264",
          "state": "requested"
        }
      ],
      "callGroupId": "door-call",
      "sourceEventId": "door-event"
    },
    "endpointId": "phone-a",
    "callGroupId": "door-call"
  },
  "eventSeq": 1
}

对应门铃告警与多端接听：M01；其他操作按条件字段校验。

更新日志

2026/10/17 03:27
查看所有更新日志
  • d04e1-docs(AI与音视频): 按公共主线与场景分支整合接入手册于