WebSocket API

连接 RustPBX

RustPBX 使用 WebSocket 连接

地址

RustPBX 的监听地址，在 RustPBX 的 config.toml 中配置：

http_addr = "0.0.0.0:8080"

路径

不同的路径对应不同的语音通话类型：

• /call: 音频流通过 WebSocket 传输
• /call/sip: 音频流通过 SIP/RTP 传输
• /call/webrtc: 音频流通过 WebRTC RTP 传输

参数

• id (可选，字符串)： 会话 ID。默认由服务端生成 UUID。（接听时应设置为 dialogId）
• dump (可选， bool， 默认： true)：是否启用 dump
• pingInterval (可选, int, 单位：秒，默认：20): WebSocket Ping 周期，开启后会定时收到 SessionEvent::Ping 事件
• serverSideTrack (可选， 字符串， 默认： serverSideTrack): 设置服务端 TrackID

示例

• ws://localhost:8080/call/sip?id=session123&dump=true

命令

命令通过 WebSocket 连接以 JSON 消息形式发送，command 字段指示命令类型。

协议新增能力（2026 版本）

近期版本扩展了通话中的命令集。在经典语音助手流程之外新增:

事件侧,dtmf_tone 上报对端按键活动,ivr_exec_completed 携带结构化的 IVR 结果。

随路数据头已改为逐键形态:用户数据以逐键 X-<key>: value SIP 头携带(例如 X-taskid),不再使用单个聚合的 X-User-Data 头——聚合形态已废止。如果你的服务端仍在解析聚合头,请迁移到逐键读取。

Invite - 发起呼叫

用途： 发起新的呼叫。

示例：

{
    "command": "invite",
    "option": {
        "denoise": true,
        "callee": "sip:alice@192.168.3.197:12345",
        "caller": "sip:192.168.3.197:3050",
`        "vad": {
            "type": "silero",
            "silenceTimeout": 5000
        },
        "asr": {
            "provider": "tencent"
        },
        "tts": {
            "provider": "tencent",
            "speaker": "601003"
        },
        "sip": {}`
    }
}

参数：

Accept - 接听来电

用途： 接听来电。

示例：

{
    "command": "accept",
    "option": {
        "denoise": true,
        "vad": {
            "type": "silero",
            "silenceTimeout": 5000
        },
        "asr": {
            "provider": "tencent"
        },
        "tts": {
            "provider": "tencent",
            "speaker": "601003"
        }
    }
}

参数：

Reject - 拒绝来电

用途： 拒绝来电。

示例：

{
  "command": "reject",
  "reason": "Busy Here",
  "code": 486
}

参数：

Ringing - 振铃

用途： 为来电发送振铃响应。(180 Ringing)

示例：

{
  "command": "ringing",
  "recorder": {
    "recorderFile": "/path/to/recording.wav",
    "samplerate": 16000,
    "ptime": 200
  },
  "earlyMedia": true,
  "ringtone": "http://example.com/ringtone.wav"
}

参数：

TTS - 文字转语音

用途： 将文本转换为语音并播放音频。

示例：

{
  "command": "tts",
  "text": "Hello, this is a test message",
  "speaker": "xiaoyan",
  "playId": "unique_play_id",
  "autoHangup": false,
  "streaming": false,
  "endOfStream": false,
  "waitInputTimeout": 30,
  "option": {
    "provider": "tencent",
    "volume": 5,
    "speed": 1.0
  }
}

参数：

Play - 播放音频

用途： 从 URL 播放音频。

示例：

{
  "command": "play",
  "url": "http://example.com/audio.mp3",
  "autoHangup": false,
  "waitInputTimeout": 30
}

参数：

Interrupt - 打断播放

用途： 中断当前的 TTS 或音频播放。

示例：

{
  "command": "interrupt",
  "graceful": false
}

参数：

Refer - 转接通话

用途： 将通话转移给另一方（SIP REFER）。

示例：

{
  "command": "refer",
  "caller": "sip:alice@example.com",
  "callee": "sip:charlie@example.com",
  "options": {
    "denoise": true,
    "timeout": 30,
    "moh": "http://example.com/hold_music.wav",
    "autoHangup": true
  }
}

参数：

Mute - 静音

用途： 静音所有或者指定的 Track。

示例：

{
  "command": "mute",
  "trackId": "track-123"
}

参数：

Unmute - 取消静音

用途： 取消被静音的 Track。

示例：

{
  "command": "unmute",
  "trackId": "track-123"
}

参数：

Hangup - 挂断

用途： 结束通话。

示例：

{
  "command": "hangup",
  "reason": "user_requested",
  "initiator": "user"
}

参数：

事件

事件以 JSON 格式从服务端接收，所有时间戳均以毫秒为单位，每个事件都包含一个 event 字段来表示事件类型，大多数事件还包括 trackId 字段来表示相关的 Track。

Incoming - 来电事件

触发时机： 接收到来电时（仅限 SIP 通话）。

示例：

{
  "event": "incoming",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "caller": "sip:alice@example.com",
  "callee": "sip:bob@example.com",
  "sdp": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\n..."
}

字段：

Answer - 接听事件

触发时机： 通话被接听且 SDP 协商完成时。

示例：

{
  "event": "answer",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "sdp": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\n..."
}

字段：

Reject - 拒绝事件

触发时机： 呼叫被拒绝时。

示例：

{
  "event": "reject",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "reason": "Busy",
  "code": 486
}

字段：

Ringing - 振铃事件

触发时机： 通话振铃时（仅限 SIP 通话）。

示例：

{
  "event": "ringing",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "earlyMedia": false
}

字段：

Hangup - 挂断事件

触发时机： 通话结束时。

示例：

{
  "event": "hangup",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "reason": "user_requested",
  "initiator": "user",
  "startTime": "2024-01-01T12:00:00Z",
  "hangupTime": "2024-01-01T12:05:30Z",
  "answerTime": "2024-01-01T12:00:05Z",
  "from": {
    "username": "alice",
    "realm": "example.com",
    "source": "sip:alice@example.com"
  }
}

字段：

Speaking - 说话事件

触发时机： 当 VAD 检测到说话时。Call Option 需配置 VAD

示例：

{
  "event": "speaking",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "startTime": 1640995200000
}

字段：

Silence - 静音事件

触发时机： 从当前语音开始超过 speechPadding 毫秒，且距离上一次触发 Silence 事件超过 silencePadding 毫秒 (如果有)。Call Option 需配置 VAD。

示例：

{
  "event": "silence",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "startTime": 1640995195000,
  "duration": 5000
}

字段：

AsrFinal - ASR 最终事件

触发时机： 语音识别的稳定结果。

示例：

{
  "event": "asrFinal",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "index": 1,
  "startTime": 1640995200000,
  "endTime": 1640995205000,
  "text": "Hello, how can I help you today?"
}

字段：

AsrDelta - ASR 增量事件

触发时机： 语音识别的中间结果 (可能还会变动)。

示例：

{
  "event": "asrDelta",
  "trackId": "track-abc123",
  "index": 1,
  "timestamp": 1640995200000,
  "text": "Hello, how can"
}

字段：

TrackStart - Track 开始事件

触发时机： Track开始时（RTP，TTS、文件播放等）。

示例：

{
  "event": "trackStart",
  "trackId": "track-tts-456",
  "timestamp": 1640995200000,
  "playId": "llm-001"
}

字段：

TrackEnd - 轨道结束事件

触发时机： Track结束时（RTP 结束，TTS 完成、文件播放完成等）。

示例：

{
  "event": "trackEnd",
  "trackId": "track-tts-456",
  "timestamp": 1640995230000,
  "duration": 30000,
  "ssrc": 1234567890,
  "playId": "llm-001"
}

字段：

Interruption - 打断事件

触发时机： 当收到 Interrupt 命令，且有未播放完毕的 TTS 命令。

示例：

{
  "event": "interruption",
  "trackId": "track-tts-456",
  "timestamp": 1640995215000,
  "playId": "llm-001",
  "subtitle": "Hello, this is a long message that was interrupted",
  "position": 5,
  "totalDuration": 30000,
  "current": 15000
}

字段：

Dtmf - DTMF 事件

触发时机： 检测到按键时。

示例：

{
  "event": "dtmf",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "digit": "1"
}

字段：

Metrics - 指标事件

触发时机： 性能指标可用时。

示例：

{
  "event": "metrics",
  "timestamp": 1640995200000,
  "key": "ttfb.asr.tencent",
  "duration": 150,
  "data": {
    "index": 1,
    "provider": "tencent"
  }
}

字段：

Error - 错误事件

触发时机： 处理过程中发生错误时。

示例：

{
  "event": "error",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "sender": "asr",
  "error": "Connection timeout to ASR service",
  "code": 408
}

字段：

Binary - 二进制事件

触发时机： 发送二进制音频数据时（仅限 WebSocket 通话）。

示例：

{
  "event": "binary",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "data": []
}

字段：

Ping - Ping 事件

触发时机： 定时发送 Ping 消息时（如果在连接 url 中设置了 pingInterval 参数），参见 连接 RustPBX。

示例：

{
  "event": "ping",
  "timestamp": 1640995200000,
  "payload": "optional_payload"
}

字段：

Other - 其他事件

触发时机： 生成自定义或扩展事件时。

示例：

{
  "event": "other",
  "trackId": "track-abc123",
  "timestamp": 1640995200000,
  "sender": "custom_plugin",
  "extra": {
    "custom_field": "custom_value"
  }
}

字段：

选项

CallOption

CallOption 对象用于 Invite 和 Accept 命令，包含通话的配置。

示例：

{
  "denoise": true,
  "offer": "SDP offer string",
  "callee": "sip:callee@example.com",
  "caller": "sip:caller@example.com",
  "codec": "g722",
  "recorder": {
    "recorderFile": "/path/to/recording.wav",
    "samplerate": 16000
  },
  "asr": {
    "provider": "tencent",
    "language": "zh-CN"
  },
  "tts": {
    "provider": "tencent",
    "speaker": "xiaoyan"
  }
}

字段：

RecorderOption

通话录音配置选项。

示例：

{
  "recorderFile": "/path/to/recording.wav",
  "samplerate": 16000,
  "ptime": 200
}

字段：

TranscriptionOption

语音识别 (ASR) 配置选项。

示例：

{
  "provider": "tencent",
  "language": "zh-CN",
  "appId": "app_id",
  "secretId": "your_secret_id",
  "secretKey": "your_secret_key",
  "modelType": "16k_zh",
  "samplerate": 16000,
  "startWhenAnswer": true
}

字段：

SynthesisOption

文字转语音（TTS） 配置选项。

示例：

{
  "provider": "tencent",
  "speaker": "xiaoyan",
  "volume": 5,
  "speed": 1.0,
  "emotion": "neutral",
  "samplerate": 16000
}

字段：

VADOption

语音活动检测（VAD）配置选项。

示例：

{
  "type": "webrtc",
  "samplerate": 16000,
  "speechPadding": 250,
  "silencePadding": 100,
  "voiceThreshold": 0.5,
  "maxBufferDurationSecs": 50
}

字段：

MediaPassOption

媒体透传配置选项，使用 WebSocket 服务完全接管语音处理。

RustPBX 会将所有语音数据发送到配置的 WebSocket 服务，并将从该服务接受到的语音播放到语音连接对方。

参见：Media Pass

示例：

{
  "url": "ws://localhost:9090/media",
  "inputSampleRate": 16000,
  "outputSampleRate": 16000,
  "packetSize": 2560
}

字段：

ReferOption

转接配置选项。

示例：

{
  "denoise": true,
  "timeout": 30,
  "moh": "http://example.com/hold_music.wav",
  "asr": {
    "provider": "tencent",
    "language": "zh-CN"
  },
  "autoHangup": true,
  "sip": {
    "username": "transfer_user",
    "password": "transfer_password"
  }
}

字段：

SipOption

SIP 协议配置选项。

示例：

{
  "username": "user",
  "password": "password",
  "realm": "example.com",
  "headers": {
    "X-Custom-Header": "value"
  }
}

字段：

Attendee

通话参与者信息。

示例：

{
  "username": "alice",
  "realm": "example.com",
  "source": "sip:alice@example.com"
}

字段：

REST API 端点

列出活跃通话

端点： GET /call/lists

描述： 返回活跃通话的列表。

响应：

{
  "calls": [
    {
      "id": "session-id",
      "call_type": "webrtc",
      "created_at": "2024-01-01T12:00:00Z",
      "option": {
        "caller": "1234567890",
        "callee": "0987654321"
      }
    }
  ]
}

用法：

curl http://localhost:8080/call/lists

终止通话

端点： POST /call/kill/{id}

描述： 终止特定的活跃通话。

参数：

• id（路径参数，字符串）：要终止的通话的会话 ID

响应：

true

用法：

curl -X POST http://localhost:8080/call/kill/session123

获取 ICE 服务器

端点： GET /iceservers

描述： 返回 WebRTC 连接的 ICE 服务器配置。

响应：

[
  {
    "urls": ["stun:restsend.com:3478"],
    "username": null,
    "credential": null
  },
  {
    "urls": ["turn:restsend.com:3478"],
    "username": "username",
    "credential": "password"
  }
]

用法：

curl http://localhost:8080/iceservers

错误处理

所有端点都返回适当的 HTTP 状态代码：

• 200 OK：成功
• 400 Bad Request：无效参数
• 404 Not Found：资源未找到
• 500 Internal Server Error：服务器错误

注意事项

• 所有 WebSocket 端点都支持实时双向通信
• 当 WebSocket 连接关闭时，通话会话会自动清理
• 可以通过设置 dump=false 参数来禁用事件转储
• ICE 服务器根据环境变量自动配置
• 音频编解码器根据功能自动协商
• VAD（语音活动检测）事件用于语音检测
• ASR（自动语音识别）提供实时转录
• TTS（文本转语音）支持流式合成
• 所有时间戳均以毫秒为单位
• trackId 用于标识哪个Track生成了事件
• playId 在使用相同 ID 时防止中断之前的 TTS 播放。对于 TTS 命令，playId 是指定的标识符；对于播放命令，playId 是 URL
• autoHangup 在 TTS/Play 完成后自动结束通话