stream

Stream the call’s audio to a WebSocket endpoint you control. The stream runs in the background: execution continues to the next instruction while audio is delivered to your endpoint in real time, which is useful for live transcription, voice analytics, or other custom media processing.

The stream keeps running until you stop it with stop_stream or the call ends. You can run more than one stream at once by giving each its own control_id.

For an inbound call that hasn’t been answered and isn’t ending, the method attempts to answer it before starting the stream.

Properties

objectRequired

An object that accepts the following properties.

stream.url

stringRequired

The secure WebSocket URI (wss://) to stream the call’s audio to.

stream.control_id

stringDefaults to Auto-generated, stored in the stream_control_id variable

Identifier for this stream, used to stop it later with stop_stream. Must be unique among the active streams on the call.

stream.name

string

A friendly name to identify this stream. Included in the stream’s status events.

stream.track

stringDefaults to inbound_track

Which side of the call’s audio to stream: inbound_track for what the caller says, outbound_track for what the caller hears, or both_tracks for both. Also accepts a SWML variable reference that resolves to one of these values.

stream.codec

stringDefaults to PCMU

Codec for the streamed audio. Possible values: PCMU (8 kHz G.711 µ-law), L16@16000h (16-bit linear PCM at 16 kHz), L16@24000h (16-bit linear PCM at 24 kHz). Use L16@16000h or L16@24000h when your speech model expects linear PCM, and always include the rate: a bare L16 is 8 kHz. If SignalWire doesn’t accept the codec, the stream doesn’t start. To choose one based on the call’s own codec, see Choose a stream codec for the call.

stream.status_url

string

HTTP or HTTPS URL to deliver stream status events. Also accepts a SWML variable reference that resolves to an HTTP or HTTPS URL. Learn more about status callbacks.

stream.status_url_method

stringDefaults to POST

Has no effect on stream status callbacks: SignalWire always sends calling.call.stream events to status_url with POST, whatever this is set to, so you can leave it unset. Possible values: GET, POST. Also accepts a SWML variable reference that resolves to one of these values.

stream.authorization_bearer_token

string

Bearer token sent in the Authorization header when connecting to the WebSocket endpoint.

stream.custom_parameters

object

Custom key-value pairs included in the first message sent to your WebSocket endpoint when the stream connects.

Variables

stream_result

success | failed

Whether the stream started successfully.

stream_control_id

string

Identifier assigned to this stream. stop_stream uses it to stop the right one.

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.

When you set status_url, SignalWire POSTs a calling.call.stream event to it whenever the stream changes state, whatever status_url_method is set to: params.state is streaming when the stream starts and finished when it ends.

Payload

{
  "event_type": "calling.call.stream",
  "event_channel": "swml:451ed9ff-e568-4222-8af9-4f9ab7428d09",
  "timestamp": 1777565701.5623918,
  "project_id": "4d0d6f16-5881-4fcc-92a4-02c51a91954d",
  "space_id": "451ed9ff-e568-4222-8af9-4f9ab7428d09",
  "params": {
    "call_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
    "node_id": "a0d4e6e5-5d07-413d-9668-55542992eec0",
    "segment_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
    "control_id": "stream-control-1",
    "state": "streaming",
    "url": "wss://example.com/stream"
  }
}

See the Stream status callback webhook page for the full field reference.

Examples

Stream to a WebSocket endpoint

version: 1.0.0
sections:
  main:
    - stream:
        url: wss://example.com/audio-stream

Stream both tracks with status callbacks

version: 1.0.0
sections:
  main:
    - stream:
        url: wss://example.com/audio-stream
        name: live-transcription
        track: both_tracks
        status_url: https://example.com/stream-status
        custom_parameters:
          customer_tier: gold