> This page is for Server SDKs.

> 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

> Tap call audio to an external endpoint via REST.

[tap-stop]: /docs/server-sdks/reference/python/rest/calling/tap-stop

Start tapping audio from an active call and sending it to an external endpoint
(e.g., a WebSocket or RTP destination). Pass a `control_id` to name the tap so
you can stop it later with [`tap_stop()`][tap-stop]. The response never carries
`control_id` back — omit it and you have no way to stop this tap afterward.

## **Request**

### Schema (`Calling.CallTapRequest`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    CallingCallTapRequestCommand:
      type: string
      enum:
        - calling.tap
      description: >-
        The `calling.tap` command starts tapping (capturing audio) on an active
        call.
      title: CallingCallTapRequestCommand
    CallingTapConfigType:
      type: string
      enum:
        - audio
      description: Currently only `audio` is supported.
      title: CallingTapConfigType
    Calling.PlayDirection:
      type: string
      enum:
        - listen
        - speak
        - both
      description: The direction of audio playback relative to the call participants.
      title: Calling.PlayDirection
    CallingTapConfigParams:
      type: object
      properties:
        direction:
          $ref: '#/components/schemas/Calling.PlayDirection'
          description: The direction of audio to tap.
      required:
        - direction
      description: Audio tap parameters.
      title: CallingTapConfigParams
    Calling.TapConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingTapConfigType'
          description: Currently only `audio` is supported.
        params:
          $ref: '#/components/schemas/CallingTapConfigParams'
          description: Audio tap parameters.
      required:
        - type
        - params
      description: Tap configuration — specifies what audio to capture.
      title: Calling.TapConfig
    CallingTapDeviceRtpType:
      type: string
      enum:
        - rtp
      title: CallingTapDeviceRtpType
    Calling.TapCodec:
      type: string
      enum:
        - PCMA
        - PCMU
        - pcma
        - pcmu
        - OPUS
        - opus
      description: >-
        RTP/WebSocket audio codec. Case-sensitive; accepted in both upper and
        lower case.
      title: Calling.TapCodec
    Calling.TapPtime:
      type: string
      enum:
        - '10'
        - '20'
        - '30'
        - '40'
        - '50'
        - '60'
        - '70'
        - '80'
        - '90'
        - '100'
        - '110'
        - '120'
      description: >-
        RTP packetization time in milliseconds. Must be a multiple of 10 between
        10 and 120.
      title: Calling.TapPtime
    Calling.TapRtpParams:
      type: object
      properties:
        addr:
          type: string
          description: >-
            Public IPv4 address of the RTP target. Private/reserved ranges are
            rejected.
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: UDP port of the RTP target (1-65535).
        codec:
          $ref: '#/components/schemas/Calling.TapCodec'
          description: Audio codec to request. Defaults to the call's negotiated codec.
        ptime:
          $ref: '#/components/schemas/Calling.TapPtime'
          description: >-
            Packetization time in milliseconds. Defaults to the call's
            negotiated ptime.
      required:
        - addr
        - port
      description: RTP tap target parameters.
      title: Calling.TapRtpParams
    Calling.TapDeviceType:
      type: string
      enum:
        - rtp
        - ws
      description: The type of tap device to stream audio to.
      title: Calling.TapDeviceType
    Calling.TapDeviceRtp:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Calling.TapDeviceType'
          description: The type of tap device.
        params:
          $ref: '#/components/schemas/Calling.TapRtpParams'
          description: RTP connection parameters.
      required:
        - type
        - params
      description: RTP tap device configuration.
      title: Calling.TapDeviceRtp
    CallingTapDeviceWsType:
      type: string
      enum:
        - ws
      title: CallingTapDeviceWsType
    Calling.TapWsParams:
      type: object
      properties:
        uri:
          type: string
          description: >-
            WebSocket URI of the tap target. Must start with `ws://` or
            `wss://`.
        codec:
          $ref: '#/components/schemas/Calling.TapCodec'
          description: Audio codec to request. Defaults to the call's negotiated codec.
      required:
        - uri
      description: WebSocket tap target parameters.
      title: Calling.TapWsParams
    Calling.TapDeviceWs:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Calling.TapDeviceType'
          description: The type of tap device.
        params:
          $ref: '#/components/schemas/Calling.TapWsParams'
          description: WebSocket connection parameters.
      required:
        - type
        - params
      description: WebSocket tap device configuration.
      title: Calling.TapDeviceWs
    CallingCallTapRequestParamsDevice:
      oneOf:
        - $ref: '#/components/schemas/Calling.TapDeviceRtp'
        - $ref: '#/components/schemas/Calling.TapDeviceWs'
      description: Device configuration specifying where to stream captured audio.
      title: CallingCallTapRequestParamsDevice
    CallingCallTapRequestParams:
      type: object
      properties:
        control_id:
          type: string
          description: >-
            Unique identifier for this tap operation, used to control it later.
            Must be unique per active tap on this call.
        tap:
          $ref: '#/components/schemas/Calling.TapConfig'
          description: Tap configuration specifying what audio to capture.
        device:
          $ref: '#/components/schemas/CallingCallTapRequestParamsDevice'
          description: Device configuration specifying where to stream captured audio.
        status_url:
          type: string
          format: uri
          description: HTTP or HTTPS URL that receives tap lifecycle webhooks.
      required:
        - control_id
        - tap
        - device
      description: An object of parameters that will be utilized by the active command.
      title: CallingCallTapRequestParams
    Calling.CallTapRequest:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: The unique identifying ID of an existing call.
        command:
          $ref: '#/components/schemas/CallingCallTapRequestCommand'
          description: >-
            The `calling.tap` command starts tapping (capturing audio) on an
            active call.
        params:
          $ref: '#/components/schemas/CallingCallTapRequestParams'
          description: An object of parameters that will be utilized by the active command.
      required:
        - id
        - command
        - params
      title: Calling.CallTapRequest
```

## **Response**

### Schema (`Calling.CallResponse`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    Calling.CallDirection:
      type: string
      enum:
        - inbound
        - outbound
        - outbound-api
      description: The direction of the call.
      title: Calling.CallDirection
    CallingCallLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingCallLegSource
    Calling.ChargeDetails:
      type: object
      properties:
        description:
          type: string
          description: Description for this charge.
        charge:
          type: number
          format: double
          description: Charged amount.
      required:
        - description
        - charge
      description: One itemized charge applied to the call.
      title: Calling.ChargeDetails
    Calling.CallResponseStatus:
      type: string
      enum:
        - queued
        - initiated
        - created
        - ringing
        - answered
        - ending
        - ended
        - failed
        - canceled
        - completed
      description: The status of the call throughout its lifecycle.
      title: Calling.CallResponseStatus
    CallingCallLegType0:
      type: string
      enum:
        - relay_pstn_call
      title: CallingCallLegType0
    CallingCallLegType1:
      type: string
      enum:
        - relay_sip_call
      title: CallingCallLegType1
    CallingCallLegType2:
      type: string
      enum:
        - relay_webrtc_call
      title: CallingCallLegType2
    CallingCallLegType:
      oneOf:
        - $ref: '#/components/schemas/CallingCallLegType0'
        - $ref: '#/components/schemas/CallingCallLegType1'
        - $ref: '#/components/schemas/CallingCallLegType2'
      description: Type of this call.
      title: CallingCallLegType
    Calling.CallLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingCallLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          oneOf:
            - $ref: '#/components/schemas/Calling.CallResponseStatus'
            - type: 'null'
          description: The status of the call.
        duration:
          type:
            - integer
            - 'null'
          description: The duration of the call in seconds.
        duration_ms:
          type:
            - integer
            - 'null'
          description: The duration of the call in milliseconds.
        billing_ms:
          type:
            - integer
            - 'null'
          description: The billable duration of the call in milliseconds.
        type:
          $ref: '#/components/schemas/CallingCallLegType'
          description: Type of this call.
        parent_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The parent call ID if this is a child call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - duration
        - duration_ms
        - billing_ms
        - type
        - parent_id
      description: Returned when the call is a standard PSTN, SIP, or WebRTC call.
      title: Calling.CallLeg
    CallingFabricDeviceLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingFabricDeviceLegSource
    CallingFabricDeviceLegType:
      type: string
      enum:
        - fabric_subscriber_device_leg
      description: Type of this call.
      title: CallingFabricDeviceLegType
    Calling.FabricDeviceLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingFabricDeviceLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          description: >-
            The status of the call. Always null for Fabric subscriber device
            legs.
        type:
          $ref: '#/components/schemas/CallingFabricDeviceLegType'
          description: Type of this call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - type
      description: >-
        Returned when the call is a Fabric subscriber device leg. The `status`
        field is always null for this type.
      title: Calling.FabricDeviceLeg
    Calling.CallResponse:
      oneOf:
        - $ref: '#/components/schemas/Calling.CallLeg'
        - $ref: '#/components/schemas/Calling.FabricDeviceLeg'
      title: Calling.CallResponse
```

## **Example**

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

client.calling.tap(
    call_id="call-id-xxx",
    control_id="tap-1",
    tap={"type": "audio", "params": {"direction": "both"}},
    device={"type": "ws", "params": {"uri": "wss://example.com/tap"}},
)
```