> This page is for SWML.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# tap

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

[statuscallbacks]: #statuscallbacks

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

## **Properties**

**`tap`** `object` — required

An object that accepts the following properties.

---

**`tap.uri`** `string` — required

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

---

**`tap.control_id`** `string` — default: 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`** `integer` — default: 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][statuscallbacks].

---

## **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**

> **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](/docs/platform/webhooks#status-callback-reliability).

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

```json
{
  "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": "192.168.1.100",
        "port": 12345,
        "codec": "PCMU",
        "ptime": 20
      }
    }
  }
}
```

---

## **Examples**

### Start WSS tap

#### YAML

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

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "tap": {
          "uri": "wss://example.com/tap"
        }
      }
    ]
  }
}
```