tap

Start background call tap. Media is streamed over Websocket or RTP to customer controlled URI.

Properties

objectRequired

An object that accepts the following properties.

tap.uri

stringRequired

Destination of the tap media stream: rtp://IP:port, ws://example.com, or wss://example.com

tap.control_id

stringDefaults to Auto-generated, stored in the tap_control_id variable

Identifier for this tap to use with stop_tap

tap.direction

string

speak“ Direction of the audio to tap: speak for what party says, listen for what party hears, both for what party hears and says

tap.codec

string

PCMU“ PCMU or PCMA

tap.rtp_ptime

integerDefaults to 20 ms

If using a rtp:// URI, this optional parameter can set the packetization time of the media in milliseconds. Optional. Default 20 ms.

tap.status_url

string

HTTP or HTTPS URL to deliver tap status events. Learn more about status callbacks.

Variables

Set by the method:

tap_uri: (out) The destination URI of the newly started tap.
tap_result: (out) success | failed.
tap_control_id: (out) Control ID of this tap.
tap_rtp_src_addr: (out) If RTP, source address of the tap stream.
tap_rtp_src_port: (out) If RTP, source port of the tap stream.
tap_ptime: (out) Packetization time of the tap stream.
tap_codec: (out) Codec in the tap stream.
tap_rate: (out) Sample rate in the tap stream.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.tap for this method.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing tap-specific parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.segment_id

string

The segment ID for the call leg. Present when available.

params.tag

string

The tag associated with the call. Present when set.

params.control_id

string

The control ID for this tap operation.

params.state

string

The current tap state. Valid values: tapping, finished.

params.tap

object

Details about the tap media stream.

tap.type

string

The type of media being tapped (e.g., audio).

tap.params.direction

string

The direction of audio being tapped.

params.device

object

Details about the destination device receiving the tap stream.

device.type

string

The type of device (e.g., rtp, ws).

device.params.addr

string

The destination address for the tap stream.

device.params.port

number

The destination port for the tap stream.

device.params.codec

string

The audio codec used for the tap stream (e.g., PCMU, PCMA).

device.params.ptime

number

The packetization time in milliseconds. Present for RTP taps only.

device.params.uri

string

The WebSocket destination URI. Present for WebSocket taps only.

Raw JSON example

1 {
2   "event_type": "calling.call.tap",
3   "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4   "timestamp": 1640000000.123,
5   "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6   "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7   "params": {
8     "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9     "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10     "segment_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11     "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
12     "state": "tapping",
13     "tap": {
14       "type": "audio",
15       "params": {
16         "direction": "both"
17       }
18     },
19     "device": {
20       "type": "rtp",
21       "params": {
22         "addr": "192.168.1.100",
23         "port": 12345,
24         "codec": "PCMU",
25         "ptime": 20
26       }
27     }
28   }
29 }

Examples

Start WSS tap

1 version: 1.0.0
2 sections:
3   main:
4     - tap:
5         uri: wss://example.com/tap