Call from a browser

VoiceWebRTC browser calling

Place a call from a web page into the same flow a phone reaches.

call-fabrictokens

The claim

WebRTC calling needs two things a static page cannot hold: a credential and a destination. A small server mints a Subscriber Access Token for the signed-in user (POST /api/fabric/subscribers/tokens). The Browser SDK v4 connects with that token and dials a phone number, or a Fabric address such as /public/support. A Fabric address can land on a SWML script, an AI agent or another subscriber. The project API token never leaves the server.

How it works

Server (python/app.py):

client.fabric.tokens.create_subscriber_token(reference=user_id, display_name="Dana")   # -> {"token": ..., "refresh_token": ...}

Browser (typescript/index.ts):

const { token, destination } = await (await fetch("/token", { method: "POST", ... })).json();
const client = new SignalWire(new StaticCredentialProvider({ token }));
await client.connect();
const call = await client.dial(destination, { audio: true, video: false });
call.remoteStream$.subscribe((s) => { if (s) audio.srcObject = s; });
call.state$.subscribe((state) => status.textContent = state);

A Subscriber Access Token identifies one user and can also receive calls after client.register(). See receive-calls-in-the-browser. For an anonymous visitor who should reach exactly one destination, mint a Guest token instead (get-a-webrtc-token-with-restricted-dial-targets). For a button with no backend at all, use the embeddable widget (embed-a-call-widget-with-no-backend). Tokens expire; the companion refresh_token is how a long session rolls over.

What to change first

Set DIAL_DESTINATION to the address of an AI agent (route-a-call-to-an-ai-agent) and the button talks to the agent instead of a person.

Where this sits

Issue a browser calling token restricted to chosen destinations

Create a video room and join from the browser Route a call to an AI agent

typescript/index.ts

// Call from a browser with the SignalWire Browser SDK v4.
// The page asks our server for a Subscriber Access Token (python/app.py: POST
// /token), connects, and dials a phone number or a Resource address. The
// project API token never leaves the server.
import { SignalWire, StaticCredentialProvider } from "@signalwire/js";

const params = new URLSearchParams(location.search);
const TO = params.get("to") ?? "/public/support"; // or a phone number: "+15551234567"

async function placeCall(status: HTMLElement): Promise<void> {
  const res = await fetch("/token", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ user: "demo-user", to: TO }),
  });
  const { token, destination } = (await res.json()) as {
    token: string;
    destination: string;
  };

  const client = new SignalWire(new StaticCredentialProvider({ token }));
  await client.connect();

  // Audio-only call to a phone number or a Fabric address such as /public/support.
  const call = await client.dial(destination, { audio: true, video: false });

  const audio = document.createElement("audio");
  audio.autoplay = true;
  document.body.appendChild(audio);
  call.remoteStream$.subscribe((stream: MediaStream | undefined) => {
    if (stream) audio.srcObject = stream;
  });
  call.status$.subscribe((state) => {
    status.textContent = `${destination}: ${state}`; // 'ringing', 'connected', ...
  });

  document.getElementById("mute")?.addEventListener("click", () => {
    void call.self?.toggleMute(); // self is null until the call is connected
  });
  document.getElementById("hangup")?.addEventListener("click", () => {
    void call.hangup();
  });
}

placeCall(document.getElementById("status")!).catch((err) =>
  console.error("call failed", err),
);

"""Call from a browser - the server half.

A browser cannot hold your project API token, so a small server mints a
Subscriber Access Token for the signed-in user and hands it to the page. The
page (typescript/) uses the token to connect and dial a phone number or a
Resource address over WebRTC.

Written against signalwire-sdk 3.0.1 (RestClient.fabric.tokens) and Flask.
"""
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire.rest import RestClient

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

app = Flask(__name__)
client = RestClient()

DEFAULT_DESTINATION = os.getenv("DIAL_DESTINATION", "/public/support")


def token_for(user_reference, display_name=None):
    """A Subscriber Access Token identifies one signed-in user; it can dial
    anywhere the user may reach and can receive inbound calls too."""
    body = {"reference": user_reference}
    if display_name:
        body["display_name"] = display_name
    return client.fabric.tokens.create_subscriber_token(**body)


@app.post("/token")
def token():
    # In a real app, `reference` is the authenticated user's id from your session.
    body = request.json or {}
    t = token_for(body.get("user", "demo-user"), body.get("display_name"))
    return jsonify(token=t["token"], destination=body.get("to", DEFAULT_DESTINATION))


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python && pip install -r requirements.txt
export SIGNALWIRE_SPACE=... SIGNALWIRE_PROJECT_ID=... SIGNALWIRE_API_TOKEN=... DIAL_DESTINATION=/public/support
python app.py

cd ../typescript && npm ci && npm start     # a page with #status, #mute, #hangup; proxy /token to the Flask app

Open the page with ?to=+15551234567 to dial a phone number instead.

Verify it

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

With the HTTP layer recorded, the verifier asserts both halves:

/token makes one documented POST to /api/fabric/subscribers/tokens with the required reference, checked against tools/openapi/rest.json
that route returns only the minted token
the TypeScript client fetches its token from the server, connects, and dials with the documented v4 calls

When typescript/node_modules is present the client is also type-checked with tsc.

Report an issue

Call from a browser

The claim

How it works

What to change first

Where this sits

Related

Next

Seen in a build

Seen in a build

Seen in a build

Seen in a build