通话控制 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/socket | JSON 双向通话控制信令 |
| WebSocket | /v1/accounts/{account}/calls/{callId}/media | 带版本号的 JSON 控制流与 Base64 PCM 音频 |
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}。它独立于参会成员状态描述信令进度:
code | kind | 成员资格含义 |
|---|---|---|
| 0 | undefined | 未知 |
| 1 | joined | 已加入会议 |
| 2 | invited | 已邀请,尚未加入 |
| 3 | acknowledged | 已收到邀请确认,尚未加入 |
| 4 | left | 已离开会议 |
| 5 | cancelled | 邀请已被取消 |
| 6 | busy | 对方忙碌无法接听 |
| 7 | rejected | 对方已拒绝邀请 |
| 8 | no_response | 对方无应答 |
| 其他 | unknown | 保留原始 code;不推断加入或离会状态 |
取消、忙碌、拒绝与无应答本身并不代表之前已在会成员离会。麦克风状态依然保持独立。例如,已确认收到邀请但未接通的成员具有 membership: "invited" 与 status: {"code": 3, "kind": "acknowledged"}。
同一账号下的观察者可以看到通话元数据,但无法拿到所有者机密令牌,亦无法访问音频流。
普通 HTTP 查询的 ownedByThisClient 恒为 false:所有权严格归属于建立控制连接的 WebSocket 会话。
busy 的作用域限定于当前账号,包含任何阻塞新通话发起的未决呼叫结果。每个账号拥有各自独立的通话控制器。
会议信令命令
-
根据所需执行的操作检查
conferenceCreate、conferenceJoin、conferenceInvite与conferenceAudio能力。在创建或加入会议前,必须先声明外呼就绪状态。 -
创建群语音通话时,提供群聊 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命令。 -
保持拥有所有权的控制 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。响应丢失不代表可以盲目自动重试。