> 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. Start tapping audio from an active call and sending it to an external endpoint (e.g., a WebSocket or RTP destination). `control_id` is a caller-chosen identifier for this operation, unique per active operation of this kind on the call. The TypeScript SDK types it as optional, but the API requires it — a request that omits it is rejected. Keep it to stop the tap later. ## **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** ```typescript {9-15} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const controlId = "tap-1"; await client.calling.tap( "call-id-xxx", { type: "audio", params: { direction: "both" } }, { type: "ws", params: { uri: "wss://example.com/tap" } }, { control_id: controlId }, ); ``` > Tap call audio to an external endpoint via REST.