跳转到内容

通话控制 API

使用控制 WebSocket 处理通话控制信令命令与事件流。获得呼叫独占所有权的客户端可附加独立的 JSON PCM 媒体 Socket。 Rust Crate 架构 详细介绍了各模块分工与依赖。

接口路由与状态快照

所有接口均需要在 HTTP Authorization 头部中携带具有对应账号 calls 作用域的 Bearer 令牌(包含 WebSocket Upgrade 握手)。路径中的各类标识符必须经过 URL 编码;严禁将令牌或机密暴露在 URL 查询参数中。

请求方式请求路径响应说明
GET/v1/accounts/{account}/calls/current获取当前通话快照 JSON
WebSocket/v1/accounts/{account}/calls/socketJSON 双向通话控制信令
WebSocket/v1/accounts/{account}/calls/{callId}/media带版本号的 JSON 控制流与 Base64 PCM 音频
Terminal window
curl -sS -H "Authorization: Bearer $TOKEN" \
"$BASE/v1/accounts/$ACCOUNT/calls/current"
{
"conferenceInvitations": [{
"invitationId": "invitation-example",
"revision": 1,
"groupId": "group@chatroom",
"callerId": "contact-a"
}],
"capabilities": {
"directAudio": true,
"conferenceCreate": true,
"conferenceJoin": true,
"conferenceInvite": true,
"conferenceAudio": true
},
"availability": {
"busy": false,
"ownedByThisClient": false
},
"currentOffer": null,
"currentPendingOffer": null,
"currentCall": null,
"audioFormat": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
}
}
字段含义说明
capabilities声明支持的特性标志;缺失标志代表能力不可用;{} 代表完全未开启通话
conferenceInvitations全新的不透明会议邀请 ID 与版本号、所属群聊与邀请人;不含房间凭据
currentPendingOffer处于等待接听就绪或预处理状态的候选来电;此时尚不可直接接听
currentOffer可立即应答的来电邀请;在认领或通话结束后清空
currentCall活跃中的通话元数据,包含种类 (kind)、类型 (type)、状态、会议参会人名册或单聊控制项
audioFormat客户端与守护进程之间交互的标准 PCM 采样格式,独立于微信内部使用的编码

上报的群语音会议参会人包含 participantId、contactId 与 membership(joined 已加入、invited 已邀请、left 已离会或 unknown 未知)。当服务端提供麦克风状态时,microphoneEnabled 为 true 或 false;省略该字段表示状态未知。参会人静音麦克风不会导致其被移出房间。

若存在 status 字段,会在快照与 participant.updated 事件中添加 {code, kind}。它独立于参会成员状态描述信令进度:

codekind成员资格含义
0undefined未知
1joined已加入会议
2invited已邀请,尚未加入
3acknowledged已收到邀请确认,尚未加入
4left已离开会议
5cancelled邀请已被取消
6busy对方忙碌无法接听
7rejected对方已拒绝邀请
8no_response对方无应答
其他unknown保留原始 code;不推断加入或离会状态

取消、忙碌、拒绝与无应答本身并不代表之前已在会成员离会。麦克风状态依然保持独立。例如,已确认收到邀请但未接通的成员具有 membership: "invited" 与 status: {"code": 3, "kind": "acknowledged"}。

同一账号下的观察者可以看到通话元数据,但无法拿到所有者机密令牌,亦无法访问音频流。 普通 HTTP 查询的 ownedByThisClient 恒为 false:所有权严格归属于建立控制连接的 WebSocket 会话。 busy 的作用域限定于当前账号,包含任何阻塞新通话发起的未决呼叫结果。每个账号拥有各自独立的通话控制器。

会议信令命令

  1. 根据所需执行的操作检查 conferenceCreate、conferenceJoin、conferenceInvite 与 conferenceAudio 能力。在创建或加入会议前,必须先声明外呼就绪状态。

  2. 创建群语音通话时,提供群聊 ID 以及 1 到 100 个受邀联系人 ID:

    {
    "type": "call.dial",
    "requestId": "create-1",
    "target": {
    "kind": "conference",
    "groupId": "group@chatroom",
    "invitees": ["contact-a", "contact-b"]
    },
    "callType": "voice"
    }

    若需加入既有的群聊通话,从 conferenceInvitations 列表中选择对应条目,并发送其确切的 ID 与版本号:

    {
    "type": "call.join",
    "requestId": "join-1",
    "invitationId": "invitation-example",
    "invitationRevision": 1
    }

    过期、撤回或已被使用过的邀请将被服务端以 offer_expired 拒绝。加入操作绝不会擅自新建会议房间。会议邀请使用 call.join 命令,而非单聊来电使用的 call.answer 命令。

  3. 保持拥有所有权的控制 Socket 处于开启状态。创建与加入命令会返回包含通话 ID 与所有者令牌的 command.result;等待 call.state 变为 connected。 在接通后如需邀请更多联系人参会,发送:

    {
    "type": "call.invite",
    "requestId": "invite-1",
    "callId": "example-conference",
    "contactIds": ["contact-c", "contact-d"]
    }

call.invitation_result 会独立汇报初始或后续各个联系人的邀请提交结果;它不代表联系人已经加入会议。participant.updated 汇报成员状态与麦克风变更。call.mute 控制我们自己的麦克风;call.hangup 仅使本机退出会议,而不会终止其他参会人的通话。 针对同一个由本机持有的通话,退会操作在参会名册发生变动时依然有效。在挂断清理期间重复发送退会指令不会发起二次操作。经确认的先前离会会在本地直接完成;未确认的网络结果将保持未决状态。 提交命令前请先核查上报的能力。当前版本暂不支持单聊通话直接升级为群聊会议。

协议版本

在控制 Socket 连接建立后的 5 秒内,向服务端声明所支持的协议版本:

{"type": "call.hello", "supportedProtocolVersions": [2]}

等待服务端的 hello 响应并在发送命令前检查 protocolVersion。当前守护进程仅支持版本 2。省略该声明默认为版本 1;服务端不提供向下兼容降级。若版本不匹配,服务端将在以 WebSocket 状态码 1002 关闭连接前返回如下错误:

{"type":"protocol.error","code":"unsupported_protocol_version","clientVersions":[1],"serverVersions":[2]}

空列表、null、重复项或格式错误的版本列表将返回 invalid_protocol_version。CLI 与 OpenClaw 插件均声明版本 2,并会主动拒绝不受支持的服务端。媒体通道的连接独立进行版本协商。

客户端信令命令 (Client messages)

在控制 WebSocket 上发送以下 JSON 文本消息。完成版本协商后,每个命令均需携带 requestId;仅在完全相同的重试时才复用它。接听/拒绝/取消/挂断时请传入最近接收到的 expectedRevision 版本号。

注册就绪状态 (Readiness)

在准备好本地音频链路后,向服务端声明就绪状态。仅建立连接保持被动监听。

声明外呼就绪:

{
"type": "call.ready",
"requestId": "ready-outgoing",
"ready": true,
"format": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
},
"scope": {
"kind": "outgoing"
}
}

声明针对某个特定待处理来电就绪:

{
"type": "call.ready",
"requestId": "ready-offer",
"ready": true,
"format": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
},
"scope": {
"kind": "offer",
"callId": "example-call",
"expectedRevision": 1
}
}

声明全局就绪(呼入与外呼)或撤销就绪:

{
"type": "call.ready",
"requestId": "ready-all",
"ready": true,
"format": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
},
"scope": {
"kind": "all"
}
}
{
"type": "call.ready",
"requestId": "not-ready",
"ready": false,
"format": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
}
}

省略 scope 默认等同于 all。

发起与应答 (Start or answer)

发起呼叫:

{
"type": "call.dial",
"requestId": "dial-1",
"target": {
"kind": "direct",
"contactId": "example-contact"
},
"callType": "voice"
}

应答来电:

{
"type": "call.answer",
"requestId": "answer-1",
"callId": "example-call",
"expectedRevision": 3
}

发起呼叫的 Socket 自然拥有外呼所有权。对于呼入来电,首个成功应答的客户端胜出;并发应答的其他客户端将收到 already_claimed。

拒绝、取消与挂断 (Reject, cancel or hang up)

拒绝来电邀请、在外呼接听前取消呼叫,或在通话中执行挂断:

{
"type": "call.reject",
"requestId": "reject-1",
"callId": "example-call",
"expectedRevision": 3
}
{
"type": "call.cancel",
"requestId": "cancel-1",
"callId": "example-call",
"expectedRevision": 4
}
{
"type": "call.hangup",
"requestId": "hangup-1",
"callId": "example-call",
"expectedRevision": 5
}

音频控制 (Audio controls)

静音外发音频(发送 muted: false 取消静音)。在打断回复时清空已排队的外发音频(参见音频代际机制)。call.mute 在守护进程侧抑制该客户端的外发流。对于会议通话,它还会向房间请求我们的麦克风状态。它无法控制其他参会人的麦克风。变更静音状态会清空已排队的音频并推进发送代际,效果与 call.clear_audio 一致。

{
"type": "call.mute",
"requestId": "mute-1",
"callId": "example-call",
"muted": true
}
{
"type": "call.clear_audio",
"requestId": "clear-1",
"callId": "example-call"
}

服务端推送事件 (Server messages)

以下 JSON 文本消息由控制 Socket 推送送达。媒体附加过程有其独立的 media.ready 响应。

初始握手 (Hello)

连接建立时的首个事件包含分配的 clientId 以及当前状态快照:

{
"type": "hello",
"protocolVersion": 2,
"clientId": "example-client",
"conferenceInvitations": [{
"invitationId": "invitation-example",
"revision": 1,
"groupId": "group@chatroom",
"callerId": "contact-a"
}],
"capabilities": {
"directAudio": true,
"conferenceCreate": true,
"conferenceJoin": true,
"conferenceInvite": true,
"conferenceAudio": true
},
"availability": {
"busy": false,
"ownedByThisClient": false
},
"currentOffer": null,
"currentPendingOffer": null,
"currentCall": null,
"audioFormat": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
}
}

会议邀请与结果通知 (Conference invitations and results)

conference.invitations 会全量替换当前的邀请列表。空数组表示清空邀请;邀请 ID 仅在当前账号下有效,且不含任何房间凭据。

{
"type": "conference.invitations",
"invitations": [{
"invitationId": "invitation-example",
"revision": 1,
"groupId": "group@chatroom",
"callerId": "contact-a"
}]
}

所有者会收到关联到创建或邀请命令 requestId 的各联系人操作结果。例如,后续的 invite-1 命令可能会产生如下事件:

{
"type": "call.invitation_result",
"callId": "example-conference",
"requestId": "invite-1",
"results": [
{
"contactId": "contact-c",
"status": "submitted",
"serviceCode": 0,
"verificationRequired": false
},
{
"contactId": "contact-d",
"status": "unknown",
"verificationRequired": false
}
]
}
状态 (Status)含义说明
submitted服务端已接收邀请提交
rejected提交被拒绝
unknown服务端未返回针对该联系人的明确结果
uncertain操作可能已抵达服务端;请勿盲目自动重试

若无可用信息则省略 serviceCode。verificationRequired: true 表示服务端要求进行验证;事件本身不包含验证 URL 亦无法完成验证步骤。邀请结果与房间成员状态保持独立。

命令执行结果 (Command results)

根据 requestId 匹配你发出的命令。声明就绪执行成功无需认领通话:

{
"type": "command.result",
"requestId": "ready-outgoing",
"status": "accepted",
"callId": null,
"ownerToken": null,
"code": null
}

成功认领通话包含用于附加媒体通道的保密所有者凭据 ownerToken:

{
"type": "command.result",
"requestId": "dial-1",
"status": "accepted",
"callId": "example-call",
"ownerToken": "<保密 ownerToken>",
"code": null
}

创建与加入群语音会议以相同方式认领所有权。成功的 join-1 响应如下:

{
"type": "command.result",
"requestId": "join-1",
"status": "accepted",
"callId": "example-conference",
"ownerToken": "<保密 ownerToken>",
"code": null
}

接受执行 (accepted) 代表开始处理操作,并不意味着已经接通。完全相同的请求可能会返回 replayed。被拒绝的命令返回 error 及固定的错误码:

{
"type": "command.result",
"requestId": "ready-outgoing",
"status": "replayed",
"callId": null,
"ownerToken": null,
"code": null
}
{
"type": "command.result",
"requestId": "answer-1",
"status": "error",
"callId": null,
"ownerToken": null,
"code": "already_claimed"
}

待处理与可应答来电 (Pending and actionable offers)

等待接听就绪的候选来电阶段为 waiting_for_ready 或 preparing:

{
"type": "call.pending",
"offer": {
"callId": "example-call",
"revision": 1,
"kind": "direct",
"callType": "voice",
"callerId": "example-contact",
"phase": "waiting_for_ready"
}
}
{
"type": "call.pending",
"offer": null
}

可立即接听或拒绝的正式邀请包含版本号 revision:

{
"type": "call.offered",
"offer": {
"callId": "example-call",
"revision": 3,
"kind": "direct",
"callType": "voice",
"callerId": "example-contact"
}
}

状态迁移与全局可用性 (State and availability)

会议状态包含所属群聊与最新参会人名单。以下示例中 contact-a 尚未上报麦克风状态;contact-b 仍在会但麦克风处于关闭状态:

{
"type": "call.state",
"call": {
"callId": "example-conference",
"revision": 5,
"kind": "conference",
"callType": "voice",
"direction": "outgoing",
"state": "connected",
"ownedByThisClient": true,
"groupId": "group@chatroom",
"participants": [
{"participantId": "member-4", "contactId": "contact-a", "membership": "joined"},
{"participantId": "member-5", "contactId": "contact-b", "membership": "joined", "microphoneEnabled": false}
]
}
}

参会名册发生变化会推进通话版本号并向同账号客户端推送 participant.updated 事件,随后推送更新后的通话快照:

{
"type": "participant.updated",
"callId": "example-conference",
"revision": 6,
"participant": {
"participantId": "member-5",
"contactId": "contact-b",
"membership": "left",
"status": {"code": 4, "kind": "left"}
}
}

在关联音轨时请使用上报的 participantId;切勿假定它等同于联系人 ID。被移出的参会人可能会触发 membership: "left",并从快照的当前名册中消失。

单聊呼叫继续沿用如下结构:

{
"type": "call.state",
"call": {
"callId": "example-call",
"revision": 5,
"kind": "direct",
"callType": "voice",
"direction": "incoming",
"state": "connected",
"ownedByThisClient": true,
"controls": [
{
"participantId": "example-contact",
"control": {
"kind": "microphone",
"muted": false
}
}
]
}
}
{
"type": "call.state",
"call": {
"callId": "example-call",
"revision": 6,
"kind": "direct",
"callType": "voice",
"direction": "incoming",
"state": "ending",
"ownedByThisClient": true
}
}
{
"type": "call.state",
"call": {
"callId": "example-call",
"revision": 7,
"kind": "direct",
"callType": "voice",
"direction": "incoming",
"state": "ended",
"ownedByThisClient": true
}
}
{
"type": "calls.availability",
"availability": {
"busy": false,
"ownedByThisClient": false
}
}

通话状态依次包含:offered(来电)、dialing(呼出中)、ringing(对方振铃)、connecting(接通协商中)、connected(已接通)、ending(正在挂断清理)、ended(已结束)以及 uncertain(未决)。在 ending 阶段必须立即停止发送音频;保持控制连接直到守护进程完成挂断清理。uncertain 标识后端遇到了未确认的结果,底层收据即使在本地会话关闭后依然会被完整保留。

参与者控制事件 (Participant control events)

对于单聊呼叫,call.control 汇报参与者的硬件控制状态。当前控制类型为 microphone(麦克风);muted: true 表示静音,false 表示未静音。participantId 为单聊呼叫目标或呼入邀请使用的联系人 ID。

{
"type": "call.control",
"callId": "example-call",
"participantId": "example-contact",
"control": {
"kind": "microphone",
"muted": true
}
}
{
"type": "call.control",
"callId": "example-call",
"participantId": "example-contact",
"control": {
"kind": "microphone",
"muted": false
}
}

该事件会推送给所有者和同账号观察者,无需回复,客户端亦可忽略。麦克风状态重复未变时不产生事件。最新已知的值也会展示在 HTTP 快照、hello 和 call.state 的 currentCall.controls 中;省略 controls 表示尚未上报任何状态。控制状态更新不推进版本号 revision,不改变 PCM 音频格式,不会结束通话,亦不中断对向音频。 群语音会议的麦克风变更展示在 participants 与 participant.updated 中;省略 microphoneEnabled 表示状态未知,而非 false。

音频代际与错误处理 (Audio generation and errors)

在成功执行 call.clear_audio 或变更静音状态后,发送轨道的音频代际将推进递增:

{
"type": "track.updated",
"callId": "example-call",
"track": {
"id": 1,
"generation": 2,
"direction": "send",
"format": {
"sampleRate": 16000,
"channels": 1,
"frameMs": 20
}
}
}

接收音轨的 track.added 与 track.removed 示例及其与音频数据的保序规范请参考媒体参考规范。

控制 Socket 发生协议级异常时推送 call.error:

{
"type": "call.error",
"code": "forbidden"
}

错误码包括:invalid_request、busy、already_claimed、offer_expired、not_owner、unsupported、media_not_ready、outcome_unknown、capacity、stale、forbidden 和 closed。响应丢失不代表可以盲目自动重试。