tap
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
An object that accepts the following properties.
tap.uri
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
Identifier for this tap to use with stop_tap
tap.direction
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
PCMU or PCMA.
Also accepts a SWML variable reference that resolves to one of these values.
tap.rtp_ptime
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
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_ptimesets 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 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
The type of event. calling.call.tap for tap state notifications.
event_channel
The channel for the event, includes the SWML session ID.
timestamp
Unix timestamp (float) when the event was generated.
project_id
The project ID associated with the call.
space_id
The Space ID associated with the call.
params
An object containing tap-specific parameters.
params.call_id
The call ID.
params.node_id
The node handling the call.
params.segment_id
The segment ID for the call leg. Present when available.
params.tag
The tag associated with the call. Present when set.
params.control_id
The control ID for this tap operation.
params.state
The current tap state. Valid values: tapping, finished.
params.tap
Details about the tap media stream.
params.tap.type
The type of media being tapped (e.g., audio).
params.tap.params.direction
The direction of audio being tapped.
params.device
Details about the destination device receiving the tap stream.
params.device.type
The type of device (e.g., rtp, ws).
params.device.params.addr
The destination address for the tap stream: the public IPv4 address from your rtp:// URI. Present for RTP taps only.
params.device.params.port
The destination port for the tap stream. Present for RTP taps only.
params.device.params.codec
The audio codec used for the tap stream (e.g., PCMU, PCMA).
params.device.params.ptime
The packetization time in milliseconds. Present for RTP taps only.
params.device.params.uri
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.