WebSocket API

连接 RustPBX

RustPBX 使用 WebSocket 连接

地址

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

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 字段指示命令类型。

Invite - 发起呼叫

用途： 发起新的呼叫。

信息

SIP 通话需要设置 option.caller 和 option.callee 分别主叫和被叫的 SIP 地址
WebRTC 通话需要设置 option.offer 为呼叫的 SDP offer

示例：

{
    "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": {}`
    }
}

参数：

字段	类型	必填	描述
`command`	string	✓	必须为 `"invite"`
`option`	CallOption	✓	通话配置参数，详见 CallOption

Accept - 接听来电

用途： 接听来电。

信息

接听电话需要设置连接 url 参数中的 id 为 dialogId，dialogId 由 webhook 请求给出。参见:

接听来电
- 连接 RustPBX

示例：

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

参数：

字段	类型	必填	描述
`command`	string	✓	必须为 `"accept"`
`option`	CallOption	✓	通话配置参数，详见 CallOption

Reject - 拒绝来电

用途： 拒绝来电。

信息

请求失败响应码列表: Request Failure 4xx

示例：

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

参数：

字段	类型	必填	默认值	描述
`command`	string	✓	-	必须为 `"reject"`
`reason`	string	✓	-	拒绝原因
`code`	number	✗	-	SIP 响应代码

Ringing - 振铃

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

注意

如果在 Ringing 命令中设置了 recorder，后续 Accept 命令中的 recorder 选项将不会覆盖振铃阶段的录音设置。

示例：

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

参数：

字段	类型	必填	默认值	描述
`command`	string	✓	-	必须为 `"ringing"`
`recorder`	RecorderOption	✗	-	通话录音配置
`earlyMedia`	boolean	✗	`false`	在振铃期间启用早期媒体
`ringtone`	string	✗	-	自定义铃声 URL

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
  }
}

参数：

字段	类型	必填	默认值	描述
`command`	string	✓	-	必须为 `"tts"`
`text`	string	✓	-	要合成的文本
`speaker`	string	✗	-	音色类型，参见各提供商音色列表
`playId`	string	✗	-	TTS Track 的标识符。
`autoHangup`	boolean	✗	`false`	TTS 播放完成后是否自动挂断通话
`streaming`	boolean	✗	`false`	是否启用流式 tts
`endOfStream`	boolean	✗	`false`	是否为当前同一 playId 的最后一条命令
`waitInputTimeout`	number	✗	-	等待用户输入的最大时间，单位: 秒
`option`	SynthesisOption	✗	-	TTS 提供商特定选项，可配置音色格式采样率等
`base64`	boolean	✗	`false`	是否使用 base64 编码

提示

启用流式 TTS， TTS 命令将在同一个 websocket 连接中发送。
设置 endOfStream = true, playId 的所有 TTS 命令已经发送完毕。TTS Track 将在所有命令结果播放完毕之后退出，并且发送 Track End 事件。
设置 base64=true 通过 text 传如 base64 编码的 PCM 编码音频。
如果设置了 playId，在该 TTS Track 发送的 Track End 事件会包含该 playId。
如果当前 playId 和之前的 TTS 命令 playId 相同，则会复用之前的 TTS Track，否则会终止之前的 TTS Track 并创建一个新的 TTS Track。

详见 TTS(Text-to-Speech)

Play - 播放音频

用途： 从 URL 播放音频。

示例：

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

参数：

字段	类型	必填	默认值	描述
`command`	string	✓	-	必须为 `"play"`
`url`	string	✓	-	要播放的音频文件 URL（支持 HTTP/HTTPS）。此 URL 将在 trackEnd 事件中作为 playId 返回
`autoHangup`	boolean	✗	`false`	如果为 true，播放完成后将自动挂断通话
`waitInputTimeout`	number	✗	-	等待用户输入的最大时间，单位秒

Interrupt - 打断播放

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

信息

如果当前 TTS 结果未播放完毕，将触发 Interruption 事件，事件包含已播放时间和从 TTS 提供商收到音频的事件。如果提供商支持字幕，还会包含已播放文字的推算位置。
如果设置 graceful = true，则会等待当前 tts 命令结果播放完毕才退出，参见打断。

示例：

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

参数：

字段	类型	必填	默认值	描述
`command`	string	✓	-	必须为 `"interrupt"`
`graceful`	boolean	✗	`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
  }
}

参数：

字段	类型	必填	描述
`command`	string	✓	必须为 `"refer"`
`caller`	string	✓	转移的主叫 SIP 地址 (当前接通的本地 SIP 地址，例如: `sip:{本地ip}:13050`)
`callee`	string	✓	转移目标的 SIP URI（例如，`sip:bob@example.com`）
`options`	ReferOption	✗	转接配置，详见 ReferOption

Mute - 静音

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

信息

如果指定 trackId，静音对应的 Track，否则静音所有的 Track。

示例：

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

参数：

字段	类型	必填	描述
`command`	string	✓	必须为 `"mute"`
`trackId`	string	✗	要静音的轨道 ID（如果未指定，则静音所有轨道）

Unmute - 取消静音

用途： 取消被静音的 Track。

信息

如果指定 trackId，取消对应 Track 的静音，否则取消所有 Track 的静音。

示例：

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

参数：

字段	类型	必填	描述
`command`	string	✓	必须为 `"unmute"`
`trackId`	string	✗	要取消静音的轨道 ID（如果未指定，则取消静音所有轨道）

Hangup - 挂断

用途： 结束通话。

示例：

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

参数：

字段	类型	必填	描述
`command`	string	✓	必须为 `"hangup"`
`reason`	string	✗	挂断原因
`initiator`	string	✗	发起挂断的一方（user、system 等）

事件

事件以 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..."
}

字段：

字段	类型	描述
`event`	string	始终为 `"incoming"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`caller`	string	主叫的 SIP 地址
`callee`	string	被叫的 SIP 地址
`sdp`	string	来自主叫的 SDP offer

Answer - 接听事件

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

信息

如果是 SIP 通话，当收到 200 OK 时，触发 Answer 事件。

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"answer"`
`trackId`	string	Track 的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`sdp`	string	来自被叫的 SDP answer

Reject - 拒绝事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"reject"`
`trackId`	string	Track 的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`reason`	string	拒绝原因
`code`	number	SIP 响应代码（可选）

信息

请求失败响应码列表: Request Failure 4xx

Ringing - 振铃事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"ringing"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`earlyMedia`	boolean	是否有早期媒体可用

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"
  }
}

字段：

字段	类型	描述
`event`	string	始终为 `"hangup"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`reason`	string	挂断原因（可选）
`initiator`	string	发起挂断的一方（可选）
`startTime`	string	通话开始的 ISO 8601 时间戳
`hangupTime`	string	通话结束的 ISO 8601 时间戳
`answerTime`	string	通话接听的 ISO 8601 时间戳（可选）
`ringingTime`	string	通话开始振铃的 ISO 8601 时间戳（可选）
`from`	Attendee	主叫信息（可选）
`to`	Attendee	被叫信息（可选）
`extra`	object	额外的通话元数据（可选）

Speaking - 说话事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"speaking"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`startTime`	number	语音开始的时间（毫秒）

Silence - 静音事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"silence"`
`trackId`	string	Track 的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`startTime`	number	静音开始的时间（毫秒）
`duration`	number	静音持续时间（毫秒）

AsrFinal - ASR 最终事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"asrFinal"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`index`	number	ASR 结果序列号
`startTime`	number	语音开始时间（毫秒，可选）
`endTime`	number	语音结束时间（毫秒，可选）
`text`	string	语音识别结果

AsrDelta - ASR 增量事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"asrDelta"`
`trackId`	string	Track的唯一标识符
`index`	number	ASR 结果序列号
`timestamp`	number	事件时间戳（毫秒）
`startTime`	number	语音开始时间（毫秒，可选）
`endTime`	number	语音结束时间（毫秒，可选）
`text`	string	语音识别结果(会变动)

TrackStart - Track 开始事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"trackStart"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`playId`	string	TTS 命令的 playId (可选) 或者 Play 命令的 URL（可选）

信息

TTS 命令和 Play 命令都会创建对应的 Track。TrackStart 中的 playId 为:

TTS Track: TTS 命令的 playId (可选)
Play Track: Play 命令的 URL

TrackEnd - 轨道结束事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"trackEnd"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`duration`	number	轨道持续时间（毫秒）
`ssrc`	number	RTP 同步源标识符
`playId`	string	TTS 命令的 playId (可选) 或者 Play 命令的 URL（可选）

信息

TTS 命令和 Play 命令都会创建对应的 Track。TrackEnd 中的 playId 为:

TTS Track: TTS 命令的 playId (可选)
Play Track: Play 命令的 URL

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
}

字段：

字段	类型	描述
`event`	string	始终为 `"interruption"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`playId`	string	对于 TTS 命令，这是来自 TTS 命令的 playId（可选）
`subtitle`	string	中断时正在播放的当前 TTS 文本（可选）
`position`	number	中断时字幕中的单词索引位置（可选）
`totalDuration`	number	TTS 内容的总持续时间（毫秒）
`current`	number	中断时自 TTS 开始以来经过的时间（毫秒）

Dtmf - DTMF 事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"dtmf"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`digit`	string	DTMF 数字（0-9, *, #, A-D）

Metrics - 指标事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"metrics"`
`timestamp`	number	事件时间戳（毫秒）
`key`	string	指标键（例如，"ttfb.asr.tencent"）
`duration`	number	持续时间（毫秒）
`data`	object	额外的指标数据

Error - 错误事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"error"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`sender`	string	生成错误的组件（asr、tts、media 等）
`error`	string	错误消息描述
`code`	number	错误代码（可选）

Binary - 二进制事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"binary"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`data`	array	二进制音频数据字节

Ping - Ping 事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"ping"`
`timestamp`	number	事件时间戳（毫秒）
`payload`	string	可选的载荷数据（可选）

Other - 其他事件

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

示例：

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

字段：

字段	类型	描述
`event`	string	始终为 `"other"`
`trackId`	string	Track的唯一标识符
`timestamp`	number	事件时间戳（毫秒）
`sender`	string	生成事件的组件
`extra`	object	额外事件数据（可选）

选项

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"
  }
}

字段：

字段	类型	必填	默认值	描述
`denoise`	boolean	✗	`false`	启用音频处理降噪
`offer`	string	✗	-	用于 WebRTC/SIP 协商的 SDP offer 字符串
`callee`	string	✗	-	被叫的 SIP URI 或电话号码（例如，"sip:bob@example.com"）
`caller`	string	✗	-	主叫的 SIP URI 或电话号码（例如，"sip:alice@example.com"）
`codec`	string	✗	`"pcmu"`	音频编解码器：`"pcmu"`, `"pcma"`, `"g722"`, `"pcm"`（仅用于 WebSocket 通话）
`recorder`	RecorderOption	✗	-	通话录音配置
`vad`	VADOption	✗	-	语音活动检测配置
`asr`	TranscriptionOption	✗	-	语音识别 (ASR)配置
`tts`	SynthesisOption	✗	-	文字转语音配置
`mediaPass`	MediaPassOption	✗	-	Media Pass 配置
`handshakeTimeout`	string	✗	-	连接握手超时（例如，"30s"）
`enableIpv6`	boolean	✗	`false`	启用 IPv6 支持
`sip`	SipOption	✗	-	SIP 注册账号、密码和域配置
`extra`	object	✗	-	补充参数

RecorderOption

通话录音配置选项。

示例：

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

字段：

字段	类型	必填	默认值	描述
`recorderFile`	string	✓	-	录音文件路径
`samplerate`	number	✗	`16000`	录音采样率，单位 Hz
`ptime`	number	✗	`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
}

字段：

字段	类型	必填	默认值	描述
`provider`	string	✗	-	ASR 提供商：`tencent`, `aliyun`, `Deepgram` 等
`language`	string	✗	-	语言（例如，"zh-CN", "en-US"） (具体参见对应提供商文档)
`appId`	string	✗	-	腾讯云的 appId
`secretId`	string	✗	-	腾讯云的 secretId
`secretKey`	string	✗	-	腾讯云的 secretKey，或者其他提供商的 API Key
`modelType`	string	✗	-	ASR 模型类型（例如，"16k_zh", "8k_en"），具体参见提供商的文档
`bufferSize`	number	✗	-	音频缓冲区大小，单位：字节
`samplerate`	number	✗	`16000`	采样率
`endpoint`	string	✗	-	自定义服务端点 URL
`extra`	object	✗	-	提供商特定参数
`startWhenAnswer`	boolean	✗	`false`	呼叫接通后再请求 ASR 服务

SynthesisOption

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

示例：

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

字段：

字段	类型	必填	默认值	描述
`provider`	string	✗	-	TTS 提供商：`"tencent"`, `"aliyun"`, `"deepgram"`, `"voiceapi"`
`speaker`	string	✗	-	音色，参见提供商文档
`volume`	number	✗	`5`	音量（1-10）
`speed`	number	✗	`1.0`	语速
`samplerate`	number	✗	`16000`	采样率，单位：hz
`appId`	string	✗	-	腾讯云的 appId
`secretId`	string	✗	-	腾讯云的 secretId
`secretKey`	string	✗	-	腾讯云的 secretKey，或者其他提供商的 API Key
`codec`	string	✗	-	编码格式
`subtitle`	boolean	✗	`false`	是否启用字幕
`endpoint`	string	✗	-	自定义 TTS 服务端点 URL
`extra`	object	✗	-	额外的提供商特定参数
`maxConcurrentTasks`	number	✗	-	非流式 TTS 命令的最大并发任务数，默认为 1

VADOption

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

示例：

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

字段：

字段	类型	必填	默认值	描述
`type`	string	✗	`"webrtc"`	VAD 算法类型：`"silero"` , `"ten"` ，`"webrtc"`
`samplerate`	number	✗	`16000`	采样率
`speechPadding`	number	✗	`250`	语音开始 `speechPadding` 毫秒后开始检测
`silencePadding`	number	✗	`100`	Silence 事件触发间隔，单位毫秒
`ratio`	number	✗	`0.5`	语音检测比率阈值
`voiceThreshold`	number	✗	`0.5`	语音能量阈值
`maxBufferDurationSecs`	number	✗	`50`	最大缓冲区持续时间，单位秒
`silenceTimeout`	number	✗	-	静音检测超时，单位毫秒
`endpoint`	string	✗	-	自定义 VAD 服务端点
`secretKey`	string	✗	-	VAD 服务身份验证密钥
`secretId`	string	✗	-	VAD 服务身份验证 ID

MediaPassOption

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

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

参见：Media Pass

示例：

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

字段：

字段	类型	必填	默认值	描述
`url`	string	✓	-	用于媒体流的 WebSocket 连接 URL
`inputSampleRate`	number	✓	-	从 WebSocket 服务器接收的音频采样率（也是轨道的采样率）
`outputSampleRate`	number	✓	-	发送到 WebSocket 服务器的音频采样率
`packetSize`	number	✗	`2560`	发送到 WebSocket 服务器的数据包大小，单位字节

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"
  }
}

字段：

字段	类型	必填	默认值	描述
`denoise`	boolean	✗	`false`	在转接期间启用降噪
`timeout`	number	✗	-	转接超时时间，单位秒
`moh`	string	✗	-	转接期间播放的等待音乐 URL
`asr`	TranscriptionOption	✗	-	自动语音识别配置
`autoHangup`	boolean	✗	`false`	转接完成后自动挂断
`sip`	SipOption	✗	-	SIP 配置

SipOption

SIP 协议配置选项。

示例：

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

字段：

字段	类型	必填	默认值	描述
`username`	string	✗	-	SIP 用户名，用于身份验证
`password`	string	✗	-	SIP 密码，用于身份验证
`realm`	string	✗	-	SIP 域/领域，用于身份验证
`headers`	object	✗	-	额外的 SIP 协议头（键值对）

Attendee

通话参与者信息。

示例：

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

字段：

字段	类型	描述
`username`	string	SIP URI 的用户名部分
`realm`	string	SIP URI 的域/领域部分
`source`	string	完整的 SIP URI 或电话号码

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 完成后自动结束通话

连接 RustPBX​

命令​

Invite - 发起呼叫​

Accept - 接听来电​

Reject - 拒绝来电​

Ringing - 振铃​

TTS - 文字转语音​

Play - 播放音频​

Interrupt - 打断播放​

Refer - 转接通话​

Mute - 静音​

Unmute - 取消静音​

Hangup - 挂断​

事件​

Incoming - 来电事件​

Answer - 接听事件​

Reject - 拒绝事件​

Ringing - 振铃事件​

Hangup - 挂断事件​

Speaking - 说话事件​

Silence - 静音事件​

AsrFinal - ASR 最终事件​

AsrDelta - ASR 增量事件​

TrackStart - Track 开始事件​

TrackEnd - 轨道结束事件​

Interruption - 打断事件​

Dtmf - DTMF 事件​

Metrics - 指标事件​

Error - 错误事件​

Binary - 二进制事件​

Ping - Ping 事件​

Other - 其他事件​

选项​

CallOption​

RecorderOption​

TranscriptionOption​

SynthesisOption​

VADOption​

MediaPassOption​

ReferOption​

SipOption​

Attendee​

REST API 端点​

列出活跃通话​

终止通话​

获取 ICE 服务器​

错误处理​

注意事项​

连接 RustPBX

命令

Invite - 发起呼叫

Accept - 接听来电

Reject - 拒绝来电

Ringing - 振铃

TTS - 文字转语音

Play - 播放音频

Interrupt - 打断播放

Refer - 转接通话

Mute - 静音

Unmute - 取消静音

Hangup - 挂断

事件

Incoming - 来电事件

Answer - 接听事件

Reject - 拒绝事件

Ringing - 振铃事件

Hangup - 挂断事件

Speaking - 说话事件

Silence - 静音事件

AsrFinal - ASR 最终事件

AsrDelta - ASR 增量事件

TrackStart - Track 开始事件

TrackEnd - 轨道结束事件

Interruption - 打断事件

Dtmf - DTMF 事件

Metrics - 指标事件

Error - 错误事件

Binary - 二进制事件

Ping - Ping 事件

Other - 其他事件

选项

CallOption

RecorderOption

TranscriptionOption

SynthesisOption

VADOption

MediaPassOption

ReferOption

SipOption

Attendee

REST API 端点

列出活跃通话

终止通话

获取 ICE 服务器

错误处理

注意事项