WebSocket API

Connect to Active Call

Active Call uses WebSocket connections

Address

The listening address of Active Call is configured in Active Call’s config.toml:

http_addr = "0.0.0.0:8080"

Paths

Different paths correspond to different voice call types:

• /call: Audio stream transmitted via WebSocket
• /call/sip: Audio stream transmitted via SIP/RTP
• /call/webrtc: Audio stream transmitted via WebRTC RTP

Parameters

• id (optional, string): Session ID. Defaults to server-generated UUID. (Should be set to dialogId when answering)
• dump (optional, bool, default: true): Whether to enable dump
• pingInterval (optional, int, unit: seconds, default: 20): WebSocket Ping interval. When enabled, will periodically receive SessionEvent::Ping events
• serverSideTrack (optional, string, default: serverSideTrack): Set server-side TrackID

Example

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

Commands

Commands are sent over the WebSocket connection as JSON messages, with the command field indicating the command type.

Invite - Initiate Call

Purpose: Initiate a new call.

Example:

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

Parameters:

Accept - Answer Incoming Call

Purpose: Answer an incoming call.

Example:

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

Parameters:

Reject - Reject Incoming Call

Purpose: Reject an incoming call.

Example:

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

Parameters:

Ringing - Ringing

Purpose: Send ringing response for incoming call. (180 Ringing)

Example:

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

Parameters:

TTS - Text-to-Speech

Purpose: Convert text to speech and play audio.

Example:

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

Parameters:

Play - Play Audio

Purpose: Play audio from URL.

Example:

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

Parameters:

Interrupt - Interrupt Playback

Purpose: Interrupt current TTS or audio playback.

Example:

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

Parameters:

Refer - Transfer Call

Purpose: Transfer call to another party (SIP REFER).

Example:

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

Parameters:

Mute - Mute

Purpose: Mute all or specified Tracks.

Example:

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

Parameters:

Unmute - Unmute

Purpose: Unmute muted Tracks.

Example:

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

Parameters:

Hangup - Hangup

Purpose: End the call.

Example:

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

Parameters:

Events

Events are received from the server in JSON format. All timestamps are in milliseconds. Each event contains an event field indicating the event type, and most events also include a trackId field indicating the related Track.

Incoming - Incoming Call Event

Trigger: When an incoming call is received (SIP calls only).

Example:

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

Fields:

Answer - Answer Event

Trigger: When the call is answered and SDP negotiation is complete.

Example:

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

Fields:

Reject - Reject Event

Trigger: When the call is rejected.

Example:

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

Fields:

Ringing - Ringing Event

Trigger: When the call is ringing (SIP calls only).

Example:

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

Fields:

Hangup - Hangup Event

Trigger: When the call ends.

Example:

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

Fields:

Speaking - Speaking Event

Trigger: When VAD detects speech. Call Option must configure VAD

Example:

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

Fields:

Silence - Silence Event

Trigger: When more than speechPadding milliseconds have passed since the current speech started, and more than silencePadding milliseconds have passed since the last Silence event was triggered (if any). Call Option must configure VAD.

Example:

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

Fields:

AsrFinal - ASR Final Event

Trigger: Stable result of speech recognition.

Example:

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

Fields:

AsrDelta - ASR Delta Event

Trigger: Intermediate result of speech recognition (may change).

Example:

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

Fields:

TrackStart - Track Start Event

Trigger: When a Track starts (RTP, TTS, file playback, etc.).

Example:

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

Fields:

TrackEnd - Track End Event

Trigger: When a Track ends (RTP ends, TTS completes, file playback completes, etc.).

Example:

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

Fields:

Interruption - Interruption Event

Trigger: When an Interrupt command is received and there are unfinished TTS commands.

Example:

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

Fields:

Dtmf - DTMF Event

Trigger: When a keypress is detected.

Example:

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

Fields:

Metrics - Metrics Event

Trigger: When performance metrics are available.

Example:

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

Fields:

Error - Error Event

Trigger: When an error occurs during processing.

Example:

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

Fields:

Binary - Binary Event

Trigger: When binary audio data is sent (WebSocket calls only).

Example:

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

Fields:

Ping - Ping Event

Trigger: When periodic Ping messages are sent (if the pingInterval parameter is set in the connection URL), see Connect to Active Call.

Example:

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

Fields:

Other - Other Event

Trigger: When custom or extended events are generated.

Example:

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

Fields:

Options

CallOption

The CallOption object is used in Invite and Accept commands, containing call configuration.

Example:

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

Fields:

RecorderOption

Call recording configuration options.

Example:

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

Fields:

TranscriptionOption

Automatic Speech Recognition (ASR) configuration options.

Example:

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

Fields:

SynthesisOption

Text-to-Speech (TTS) configuration options.

Example:

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

Fields:

VADOption

Voice Activity Detection (VAD) configuration options.

Example:

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

Fields:

MediaPassOption

Media pass-through configuration options, using WebSocket service to completely take over audio processing.

Active Call will send all audio data to the configured WebSocket service and play audio received from that service to the other party of the audio connection.

See: Media Pass

Example:

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

Fields:

ReferOption

Transfer configuration options.

Example:

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

Fields:

SipOption

SIP protocol configuration options.

Example:

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

Fields:

Attendee

Call participant information.

Example:

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

Fields:

REST API Endpoints

List Active Calls

Endpoint: GET /call/lists

Description: Returns a list of active calls.

Response:

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

Usage:

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

Terminate Call

Endpoint: POST /call/kill/{id}

Description: Terminate a specific active call.

Parameters:

• id (path parameter, string): Session ID of the call to terminate

Response:

true

Usage:

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

Get ICE Servers

Endpoint: GET /iceservers

Description: Returns ICE server configuration for WebRTC connections.

Response:

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

Usage:

curl http://localhost:8080/iceservers

Error Handling

All endpoints return appropriate HTTP status codes:

• 200 OK: Success
• 400 Bad Request: Invalid parameters
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

Notes

• All WebSocket endpoints support real-time bidirectional communication
• When WebSocket connection closes, call sessions are automatically cleaned up
• Event dumping can be disabled by setting the dump=false parameter
• ICE servers are automatically configured based on environment variables
• Audio codecs are automatically negotiated based on functionality
• VAD (Voice Activity Detection) events are used for speech detection
• ASR (Automatic Speech Recognition) provides real-time transcription
• TTS (Text-to-Speech) supports streaming synthesis
• All timestamps are in milliseconds
• trackId is used to identify which Track generated the event
• playId prevents interrupting previous TTS playback when using the same ID. For TTS commands, playId is the specified identifier; for Play commands, playId is the URL
• autoHangup automatically ends the call after TTS/Play completes