***

id: a2e8f940-0d17-4421-a9bc-ff989163b3f2
title: tap
slug: /reference/tap
description: >-
Start background call tap. Media is streamed over Websocket or RTP to customer
controlled URI.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

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

## **Properties**

<ParamField path="tap" type="object" required={true} toc={true}>
  An object that accepts the following properties.
</ParamField>

<Indent>
  <ParamField path="tap.uri" type="string" required={true} toc={true}>
    Destination of the tap media stream: `rtp://IP:port`, `ws://example.com`, or `wss://example.com`
  </ParamField>

  <ParamField path="tap.control_id" type="string" default="Auto-generated, stored in the tap_control_id variable" toc={true}>
    Identifier for this tap to use with `stop_tap`
  </ParamField>

  <ParamField path="tap.direction" type="string" toc={true}>
    speak\`\`
    Direction of the audio to tap: `speak` for what party says, `listen` for what party hears, `both` for what party hears and says
  </ParamField>

  <ParamField path="tap.codec" type="string" toc={true}>
    PCMU\`\`
    `PCMU` or `PCMA`
  </ParamField>

  <ParamField path="tap.rtp_ptime" type="integer" default="20 ms" toc={true}>
    If using a `rtp://` URI, this optional parameter can set the packetization time of the media in milliseconds. Optional. Default 20 ms.
  </ParamField>

  <ParamField path="tap.status_url" type="string" toc={true}>
    HTTP or HTTPS URL to deliver tap status events. Learn more about [status callbacks][statuscallbacks].
  </ParamField>
</Indent>

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

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.tap` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing tap-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.segment_id" type="string" toc={true}>
    The segment ID for the call leg. Present when available.
  </ParamField>

  <ParamField path="params.tag" type="string" toc={true}>
    The tag associated with the call. Present when set.
  </ParamField>

  <ParamField path="params.control_id" type="string" toc={true}>
    The control ID for this tap operation.
  </ParamField>

  <ParamField path="params.state" type="string" toc={true}>
    The current tap state. **Valid values:** `tapping`, `finished`.
  </ParamField>

  <ParamField path="params.tap" type="object" toc={true}>
    Details about the tap media stream.
  </ParamField>

  <Indent>
    <ParamField path="tap.type" type="string" toc={true}>
      The type of media being tapped (e.g., `audio`).
    </ParamField>

    <ParamField path="tap.params.direction" type="string" toc={true}>
      The direction of audio being tapped.
    </ParamField>
  </Indent>

  <ParamField path="params.device" type="object" toc={true}>
    Details about the destination device receiving the tap stream.
  </ParamField>

  <Indent>
    <ParamField path="device.type" type="string" toc={true}>
      The type of device (e.g., `rtp`, `ws`).
    </ParamField>

    <ParamField path="device.params.addr" type="string" toc={true}>
      The destination address for the tap stream.
    </ParamField>

    <ParamField path="device.params.port" type="number" toc={true}>
      The destination port for the tap stream.
    </ParamField>

    <ParamField path="device.params.codec" type="string" toc={true}>
      The audio codec used for the tap stream (e.g., `PCMU`, `PCMA`).
    </ParamField>

    <ParamField path="device.params.ptime" type="number" toc={true}>
      The packetization time in milliseconds. Present for RTP taps only.
    </ParamField>

    <ParamField path="device.params.uri" type="string" toc={true}>
      The WebSocket destination URI. Present for WebSocket taps only.
    </ParamField>
  </Indent>
</Indent>

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

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - tap:
            uri: wss://example.com/tap
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "tap": {
              "uri": "wss://example.com/tap"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>