Web Voice Channel

Overview

Toggle util-web-channel on a useragent and a single REST call (POST /UserAgent/Realtime/WebStart) returns everything the browser needs to open an authenticated WebSocket and stream microphone audio straight to the agent. The same agent can also pick up phone calls via Twilio Voice — the two channels share the same realtime runtime and end up in the same Call History.

Skill that powers this channel:

• util-web-channel — browser voice channel. Bundled on the Voice Receptionist and Voice Sales Rep presets; toggle it on for any other agent via POST /UserAgent/SkillsApply.

Agents that typically enable this channel:

• Voice Receptionist — phone + browser receptionist.
• Voice Sales Rep — outbound sales rep with an "Open mic" CTA.
• Custom agents that need a voice button on a website or web app.

Web channel vs Twilio channel — pick by where the caller comes from:

Availability

Prerequisites

• A Wiro API key — Authentication.
• A deployed agent in status: 4 (Running) — Agent Overview. Voice Receptionist / Voice Sales Rep presets work out of the box; for custom agents, enable util-web-channel via POST /UserAgent/SkillsApply.
• A browser that can capture microphone audio at 24 kHz mono PCM (every evergreen browser via getUserMedia + Web Audio).

Setup

Step 1: Start a session — POST /UserAgent/Realtime/WebStart

Issues two opaque, one-time handles, both valid until expiresAt (5 minutes after issue): a sessionToken the browser presents to the WebSocket on first connect, and a cancelToken for Realtime/Cancel. No API key ever needs to reach the browser.

curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/WebStart" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "session_metadata": {
      "page_url": "https://yourapp.com/agents/sales-rep",
      "display_identifier": "Acme Inc."
    }
  }'

Response:

{
  "result": true,
  "correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa",
  "wsUrl": "wss://socket.wiro.ai/v1/AgentRealtime/Web",
  "sessionToken": "<opaque one-time session handle>",
  "cancelToken": "<opaque one-time cancel handle>",
  "expiresAt": 1748212800000,
  "estimatedReadyMs": 8000
}

Step 2: Connect the WebSocket

Open a WebSocket to the returned wsUrl and send the session_start JSON frame within 10 seconds. After that, frame microphone audio as 24 kHz mono PCM int16 with a <correlationId>| text prefix. Server-sent binary audio frames use the same prefix shape — you must strip it before feeding the bytes to Web Audio.

The example below boots a working voice call end-to-end: it acquires the mic, mounts an AudioWorklet that emits 24 kHz Int16 PCM, opens the WebSocket, presents the token, handles every server frame the bridge actually sends, and plays the agent's audio back through AudioContext. Drop it into a page paired with the worklet at audio-processor.js shown below.

// ===== voice-client.js — runs in the browser =====

// 1. POST /UserAgent/Realtime/WebStart from YOUR backend, then pass the
//    correlationId / wsUrl / sessionToken / cancelToken down to the page.
//    Never expose your Wiro API key to the page.
const { correlationId, wsUrl, sessionToken, cancelToken } = await fetch("/api/voice/start").then((r) => r.json());

const audioCtx = new AudioContext({ sampleRate: 24000 });
await audioCtx.audioWorklet.addModule("/audio-processor.js");
let playbackCursor = 0;
const scheduledNodes = new Set();
let interruptActive = false;

function playPcmInt16(pcm) {
  const f32 = new Float32Array(pcm.length);
  for (let i = 0; i < pcm.length; i++) f32[i] = pcm[i] / 32768;
  const buf = audioCtx.createBuffer(1, f32.length, 24000);
  buf.copyToChannel(f32, 0);
  const node = audioCtx.createBufferSource();
  node.buffer = buf;
  node.connect(audioCtx.destination);
  const startAt = playbackCursor < audioCtx.currentTime ? audioCtx.currentTime : playbackCursor;
  scheduledNodes.add(node);
  node.onended = () => scheduledNodes.delete(node);
  node.start(startAt);
  playbackCursor = startAt + buf.duration;
}

function flushPlayback() {
  for (const node of scheduledNodes) { try { node.stop(); } catch {} }
  scheduledNodes.clear();
  playbackCursor = audioCtx.currentTime;
}

// 2. Open the WebSocket and present the token as the first message.
const ws = new WebSocket(wsUrl);
ws.binaryType = "arraybuffer";

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({ type: "session_start", sessionToken }));
});

ws.addEventListener("message", async (event) => {
  if (event.data instanceof ArrayBuffer) {
    if (interruptActive) return;
    const u8 = new Uint8Array(event.data);
    const pipe = u8.indexOf(0x7c); // '|'
    if (pipe < 0) return;
    const pcmBytes = u8.subarray(pipe + 1);
    const pcm = new Int16Array(pcmBytes.buffer, pcmBytes.byteOffset, pcmBytes.byteLength / 2);
    playPcmInt16(pcm);
    return;
  }
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "connecting":   onConnecting?.(); break;
    case "ready":        await startMicCapture(); break;
    case "transcript":
      appendTranscript(msg.role, msg.text, msg.ts); // role: "user"|"ai"
      break;
    case "clear":
      flushPlayback();
      interruptActive = true;
      break;
    case "resume":
      interruptActive = false;
      break;
    case "session_end":
      onEnded?.(msg.reason, msg.message || msg.error);
      try { ws.close(); } catch {}
      break;
  }
});

// 3. Mic capture pipeline.
let micStream, workletNode;
async function startMicCapture() {
  micStream = await navigator.mediaDevices.getUserMedia({
    audio: { echoCancellation: true, noiseSuppression: true, sampleRate: 24000 },
  });
  const source = audioCtx.createMediaStreamSource(micStream);
  workletNode = new AudioWorkletNode(audioCtx, "pcm-24k-processor");
  source.connect(workletNode);

  const sessionMarker = new TextEncoder().encode(correlationId);
  workletNode.port.onmessage = (e) => {
    const pcmBytes = new Uint8Array(e.data);
    const frame = new Uint8Array(sessionMarker.length + 1 + pcmBytes.byteLength);
    frame.set(sessionMarker, 0);
    frame[sessionMarker.length] = 0x7c; // '|'
    frame.set(pcmBytes, sessionMarker.length + 1);
    if (ws.readyState === WebSocket.OPEN) ws.send(frame);
  };
}

// 4. UI hooks.
function muteMic(on) {
  // Mute is purely client-side — the bridge has no server-side mute handler.
  micStream?.getAudioTracks().forEach((t) => (t.enabled = !on));
}
function bargeIn() { ws.send(JSON.stringify({ type: "interrupt" })); }
function endCall() { ws.send(JSON.stringify({ type: "end" })); }

// ===== audio-processor.js — served from your origin, registered above =====
class PCM24kProcessor extends AudioWorkletProcessor {
  constructor() { super(); this.buffer = new Float32Array(0); }
  process(inputs) {
    const input = inputs[0]?.[0];
    if (!input) return true;
    const merged = new Float32Array(this.buffer.length + input.length);
    merged.set(this.buffer);
    merged.set(input, this.buffer.length);
    this.buffer = merged;
    while (this.buffer.length >= 4800) {
      const chunk = this.buffer.slice(0, 4800);
      this.buffer = this.buffer.slice(4800);
      const i16 = new Int16Array(chunk.length);
      for (let i = 0; i < chunk.length; i++) {
        const s = Math.max(-1, Math.min(1, chunk[i]));
        i16[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
      }
      this.port.postMessage(i16.buffer, [i16.buffer]);
    }
    return true;
  }
}
registerProcessor("pcm-24k-processor", PCM24kProcessor);

Step 3 (optional): Cancel a stale session — POST /UserAgent/Realtime/Cancel

If the browser can't progress past WebStart (mic permission denied, user navigated away, tab crashed), call Realtime/Cancel so the server-side agent prep tears down immediately instead of waiting on the 5-minute cleanup guard. Send the cancelToken from WebStart, authenticated as the user who called WebStart; each cancel handle works once.

curl -X POST "https://api.wiro.ai/v1/UserAgent/Realtime/Cancel" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "cancelToken": "CANCEL_TOKEN_FROM_WEBSTART"
  }'

Response:

{ "result": true, "correlationId": "voice_3fK9xQ2LmVb7TzR1pWc8NdYa", "cancelled": true }

WebSocket Protocol

The browser bridge lives at wss://<env>/v1/AgentRealtime/Web. The same prefix hosts the Twilio Media Streams handler at /v1/AgentRealtime/Twilio, but you never call that directly — Twilio's auto-configured VoiceUrl points at it.

First message (text frame)

{ "type": "session_start", "sessionToken": "<sessionToken-from-WebStart>" }

Must arrive within 10 seconds of the WebSocket open event. Late or malformed → the server closes the socket with no further messages. The handle works once and only until expiresAt; an unknown, used or expired handle closes the socket the same way. The URL carries no session identifier.

Audio frames (binary, both directions)

The bridge transcodes server-side if a downstream model needs a different sample rate, so you always send 24 kHz from the browser.

Browser → server control frames (text)

Server → browser frames

Session lifetime

• The sessionToken handle is valid for 300 seconds from issue (until expiresAt) and works once, so the browser must send session_start before then. To connect again, call WebStart for fresh handles — there's no in-band refresh.
• The WebStart-armed 5-minute pre-WS cleanup guard is cancelled the moment the bridge accepts your session_start frame, so a live call is never torn down by it. Live call audio is billed through int-wiro-aimodels against your own Wiro AI Models balance — the pre-WS prep window carries no audio charge.

Rate Limits

• 60 sessions / hour per operator (fixed window). The operator identity is hashed and never logged raw.
• Fast-fail sessions (prep timeout, model rejecting the realtime session, WS upgrade error) decrement the counter back so a flaky downstream doesn't burn through quota during an incident.
• Origin allow-list (Bearer auth path only) — https://wiro.ai / https://www.wiro.ai (plus http://localhost:3000 / http://localhost:8080 in non-production). The API-key path skips the Origin check because key + IP whitelist already authenticated the caller.

Common Errors

Multi-Tenant Architecture

Every WebStart call is scoped by:

• One-time handles — sessionToken and cancelToken are opaque, random and single-use, valid until expiresAt. Nothing readable travels in the handle or the WS URL — same "single endpoint, first-message token" pattern Wiro uses for its native realtime models.
• useragentguid + caller uuid — kept on the server behind the handle, never sent to the browser; the bridge re-checks the agent when the browser connects.
• Origin allow-list (Bearer path only) — defence-in-depth against a stolen localStorage Bearer being weaponised from a third-party site.
• Per-operator rate-limit key — hashed, so logs never carry the raw operator identity.
• Channel-isolated upgrade handlers — /v1/AgentRealtime/Web and /v1/AgentRealtime/Twilio are distinct upgrade handlers on the same process; one cannot read the other's session state. Adding a new provider in the future is a single new handler under the same /v1/AgentRealtime/<NewChannel> prefix — no nginx config churn.

Related

• Twilio Voice — pair the same agent with a real phone number for inbound PSTN calls. Both channels surface in the same Call History feed.
• Realtime Voice Conversation — the underlying model-level realtime protocol (used by wiro.ai/models/openai/gpt-realtime-mini, etc.). Web Channel is the agent-aware wrapper around it.
• Agent Overview — useragent statuses, token-based credit metering, and the rest of the agent surface.
• Agent Skills — toggling util-web-channel on any agent.
• Agent Use Cases — Voice Receptionist — preset that ships Web + Twilio channels on by default.