Skip to navigation
Calling

tap

View as MarkdownOpen in Claude

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

For an inbound call that hasn’t been answered and isn’t ending, the method attempts to answer it before starting the tap.

Properties

tap
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. For RTP, IP must be a public IPv4 address followed by a port; hostnames, private addresses, and IPv6 addresses aren’t accepted.

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
stringDefaults to speak

Direction of the audio to tap: speak for what party says, listen for what party hears, both for what party hears and says. Also accepts a SWML variable reference that resolves to one of these values.

tap.codec
stringDefaults to PCMU

PCMU or PCMA. Also accepts a SWML variable reference that resolves to one of these values.

tap.rtp_ptime
integer | stringDefaults 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. Must be a multiple of 10 from 10 to 120. A number outside this range is rejected even when uri is a WebSocket URI, where rtp_ptime otherwise has no effect. Also accepts a SWML variable reference.

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, in milliseconds, of the tapped call’s audio when the tap started. This isn’t necessarily the packetization time of the tap stream; for RTP destinations, rtp_ptime sets that separately.
  • tap_codec: (out) Codec in the tap stream.
  • tap_rate: (out) Sample rate of the tapped call’s audio when the tap started. This isn’t necessarily the sample rate of the tap stream.

StatusCallbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

A POST request will be sent to status_url when the tap changes state, with a JSON payload like the following:

event_type
string

The type of event. calling.call.tap for tap state notifications.

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.

params.tap.type
string

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

params.tap.params.direction
string

The direction of audio being tapped.

params.device
object

Details about the destination device receiving the tap stream.

params.device.type
string

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

params.device.params.addr
string

The destination address for the tap stream: the public IPv4 address from your rtp:// URI. Present for RTP taps only.

params.device.params.port
number

The destination port for the tap stream. Present for RTP taps only.

params.device.params.codec
string

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

params.device.params.ptime
number

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

params.device.params.uri
string

The WebSocket destination URI. Present for WebSocket taps only.

If the tap request fails, SignalWire can instead POST a calling.error event to status_url, with the error details in params.error. Not every failure produces this event.

Raw JSON example

In this example, x.x.x.x stands for the public IPv4 address from the tap’s rtp:// URI.

{
"event_type": "calling.call.tap",
"event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": 1640000000.123,
"project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"params": {
"call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"segment_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"state": "tapping",
"tap": {
"type": "audio",
"params": {
"direction": "both"
}
},
"device": {
"type": "rtp",
"params": {
"addr": "x.x.x.x",
"port": 12345,
"codec": "PCMU",
"ptime": 20
}
}
}
}

Examples

Start WSS tap

version: 1.0.0
sections:
main:
- tap:
uri: wss://example.com/tap