Stream call audio to a WebSocket that checks a bearer token

Voiceauthenticated media streaming over WebSocket

Send one side of a call, or both, to your own WebSocket over TLS, with a bearer token on the connection and your own metadata attached.

restmedia-streaming

The claim

tap copies a call’s audio to a URI. calling.stream does the same job for an endpoint that has opinions. It insists on TLS and authenticates. It lets you pick a side of the conversation, and it hands your endpoint metadata when the connection opens.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority.

calling.stream requires control_id and url. The url “must start with wss:// (TLS is required; plain ws:// is rejected)“, so the recipe refuses a ws:// url before sending one.
track is inbound_track, outbound_track or both_tracks.
authorization_bearer_token is “included as Authorization: Bearer <token> when establishing the WebSocket connection”.
custom_parameters is an “arbitrary JSON object passed through to the WebSocket endpoint as connection metadata”, which is how a stream says which ticket it belongs to.
status_url receives the lifecycle webhooks, with status_url_method of GET or POST.
calling.stream.stop requires control_id.

Use tap when the destination is an RTP address or a plain socket you control. Use stream when the endpoint authenticates the connection, or when only one side of the call should leave the platform.

How it works

def start(call_id, url, track="both_tracks", control_id=CONTROL_ID,
          status_url=None, tag=None):
    if not url.startswith("wss://"):
        raise ValueError(...)
    params = {"control_id": control_id, "url": url, "track": track,
              "codec": "PCMU", "name": "support"}
    if STREAM_TOKEN:
        params["authorization_bearer_token"] = STREAM_TOKEN
    if tag:
        params["custom_parameters"] = {"tag": tag}
    return client.calling.stream(call_id, **params)

What the platform receives:

{"command": "calling.stream",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"control_id": "support-audio",
            "url": "wss://media.example.com/calls",
            "track": "both_tracks",
            "codec": "PCMU",
            "name": "support",
            "authorization_bearer_token": "…",
            "custom_parameters": {"tag": "ticket-4417"},
            "status_url": "https://media.example.com/stream-events",
            "status_url_method": "POST"}}

The token is read from the environment, so it is never a literal in the code the page shows. Your endpoint checks the Authorization header on the upgrade request and refuses anything else, which is the point of sending it.

codec is freeform in the spec, which lists PCMU, PCMA and OPUS as common values. What your endpoint accepts is the real constraint.

Limitations

The verifier proves the requests, not the socket. Whether your endpoint accepts the upgrade, and what it does with the audio, is yours to build.

The bearer token is sent to the platform in the clear inside the command body, which is a TLS request to the API. Treat it as a credential your endpoint issues, and rotate it like one.

What to change first

Point start at a ws:// url and run the verifier. It raises before the request, which is the point. The spec rejects plain WebSocket, and the check belongs in your code rather than in a 400.

Where this sits

Before this

Stream call audio to your own server

Start live transcription and consume the webhook Transcribe a call in the background End or transfer a live call over REST

python/app.py

"""Stream call audio to a WebSocket that checks a bearer token.

`calling.stream` opens a WebSocket to your endpoint and sends the call's audio
down it. The spec requires `wss://`, so plain `ws://` is refused here before it
is sent. `authorization_bearer_token` becomes the `Authorization: Bearer`
header on the connection, `track` picks which side of the call to send, and
`custom_parameters` reach your endpoint as connection metadata.
`calling.stream.stop` ends it by control id.

Written against signalwire-sdk 3.0.1 (RestClient.calling).

    python app.py start <call_id> wss://media.example.com/calls
    python app.py stop <call_id>
"""
import os
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

# one id names this stream, and stop names it again
CONTROL_ID = "support-audio"

# the token your endpoint checks on the upgrade request
STREAM_TOKEN = os.getenv("STREAM_BEARER_TOKEN", "")

# the spec's three tracks
TRACKS = ("inbound_track", "outbound_track", "both_tracks")


def start(call_id, url, track="both_tracks", control_id=CONTROL_ID,
          status_url=None, tag=None):
    """Open the stream. Returns whatever the platform says about the command."""
    if not url.startswith("wss://"):
        # the spec: TLS is required, and plain ws:// is rejected
        raise ValueError(f"stream url must start with wss://, not {url!r}")
    if track not in TRACKS:
        raise ValueError(f"track must be one of {TRACKS}, not {track!r}")
    params = {"control_id": control_id, "url": url, "track": track,
              "codec": "PCMU", "name": "support"}
    if STREAM_TOKEN:
        # arrives at your endpoint as Authorization: Bearer <token>
        params["authorization_bearer_token"] = STREAM_TOKEN
    if tag:
        # your own metadata, handed to the endpoint when it connects
        params["custom_parameters"] = {"tag": tag}
    if status_url:
        params["status_url"] = status_url
        params["status_url_method"] = "POST"
    return client.calling.stream(call_id, **params)


def stop(call_id, control_id=CONTROL_ID):
    """End the stream. The call carries on."""
    return client.calling.stream_stop(call_id, control_id=control_id)


if __name__ == "__main__":
    args = sys.argv[1:]
    cmd = args[0] if args else "help"
    call_id = args[1] if len(args) > 1 else ""
    rest = args[2:]
    if not call_id:
        print(__doc__)
    elif cmd == "start":
        print(start(call_id, *rest))
    elif cmd == "stop":
        print(stop(call_id))
    else:
        print(__doc__)

/**
 * Stream call audio to a WebSocket that checks a bearer token.
 *
 * `calling.stream` opens a WebSocket to your endpoint and sends the call's
 * audio down it. The spec requires `wss://`, so plain `ws://` is refused here
 * before it is sent. `authorization_bearer_token` becomes the
 * `Authorization: Bearer` header on the connection, `track` picks which side of
 * the call to send, and `custom_parameters` reach your endpoint as connection
 * metadata. `calling.stream.stop` ends it by control id.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.calling).
 *
 *     npm start start <call_id> wss://media.example.com/calls
 *     npm start stop <call_id>
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// one id names this stream, and stop names it again
export const CONTROL_ID = "support-audio";

// the token your endpoint checks on the upgrade request
export const STREAM_TOKEN = process.env["STREAM_BEARER_TOKEN"] ?? "";

// the spec's three tracks
export const TRACKS = ["inbound_track", "outbound_track", "both_tracks"] as const;
export type Track = (typeof TRACKS)[number];

/** Open the stream. Returns whatever the platform says about the command. */
export function start(callId: string, url: string, track: Track = "both_tracks",
                      controlId = CONTROL_ID, statusUrl?: string, tag?: string) {
  if (!url.startsWith("wss://")) {
    // the spec: TLS is required, and plain ws:// is rejected
    throw new Error(`stream url must start with wss://, not '${url}'`);
  }
  if (!TRACKS.includes(track)) {
    throw new Error(`track must be one of ${TRACKS.join(", ")}, not '${track}'`);
  }
  const params: Record<string, unknown> = {
    control_id: controlId, url, track, codec: "PCMU", name: "support",
  };
  if (STREAM_TOKEN) {
    // arrives at your endpoint as Authorization: Bearer <token>
    params["authorization_bearer_token"] = STREAM_TOKEN;
  }
  if (tag) {
    // your own metadata, handed to the endpoint when it connects
    params["custom_parameters"] = { tag };
  }
  if (statusUrl) {
    params["status_url"] = statusUrl;
    params["status_url_method"] = "POST";
  }
  return client.calling.stream(callId, params);
}

/** End the stream. The call carries on. */
export function stop(callId: string, controlId = CONTROL_ID) {
  return client.calling.streamStop(callId, { control_id: controlId });
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, callId, url] = process.argv.slice(2);
  if (!callId) {
    console.log("usage: npm start <start|stop> <call_id> [wss url]");
  } else if (cmd === "start") {
    console.log(await start(callId, url));
  } else if (cmd === "stop") {
    console.log(await stop(callId));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py start <call_id> wss://media.example.com/calls
python app.py stop <call_id>

The TypeScript surface is the same two commands on @signalwire/sdk, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start start <call_id> wss://media.example.com/calls

Set STREAM_BEARER_TOKEN in .env to whatever your endpoint expects. Leave it unset and the param is absent.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier swaps the SDK’s HTTP layer for a recorder, calls the helpers, and asserts the following.

a ws:// url and an unknown track both raise before any request is made
calling.stream requires control_id and url, and the spec’s own text carries the TLS rule, the metadata rule and the Authorization: Bearer behaviour
the track enum is exactly the three documented values, and the recipe’s list matches it
status_url_method is GET or POST
the first body carries the token, the custom parameters and the status URL, and the second carries none of them, as absent keys rather than nulls
calling.stream.stop requires only control_id
the TypeScript surface sends those same three bodies and refuses ws:// too

Report an issue