Embedded Web Calls

Overview

An embedded web call puts your assistant on a page you host. A visitor clicks, talks, and the agent answers — with SMS, bookings and live handoff working exactly as they do on a call placed from the Voxworks app. Two requests make it work. Your server mints a session; the visitor’s browser uses it to reach the Voxworks media edge over SIP-over-WebSocket.

your server ──POST /api/v1/create-web-session──▶ api.voxworks.ai   (API key)
            ◀──── session token + SIP bootstrap ────

your page ──── SIP over WSS, audio both ways ───▶ Voxworks media edge ──▶ agent

Audio goes browser-to-edge directly. Nothing proxies it, and the API never sees it. This page covers the developer integration. For web calls placed inside the Voxworks app — the In Browser option in the Test Call dialog — see Web Calls.

What the session token is

create-web-session returns a single-use token, valid for about two minutes, for one call on one script — chosen by your server, not by the page. The script, contact and destination are fixed when your server mints the token. A page holding it cannot point it at a different script, and cannot start a second call with it. That’s what makes it safe to hand to a browser. The connection bootstrap in the same response is not a credential and grants no access on its own — the token is what authorises the call. Treat it as configuration, not as a secret.

Mint the session on your own server so your API key never reaches a browser. An API key can read your calls and contacts and start outbound ones; anything in a page bundle is public.

1. Find your `script_id`

Open Call Scripts, select the script the call should run, go to its Settings tab, and read the Script UUID field on the Call Settings card. You’ll also need an API key — see API Quickstart if you haven’t generated one.

2. Mint a session on your server

Check the endpoint works before wiring anything up:

curl -X POST https://api.voxworks.ai/api/v1/create-web-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "participant_identity": "visitor-4821"
  }'

A successful call returns 201 Created:

{
  "success": true,
  "session_id": "8f52322d-5402-469a-a042-69dac09bf375",
  "session_token": "8f52322d-5402-469a-a042-69dac09bf375.4kCQhASFG9t1_bC9Dvim7Kmg",
  "expires_at": "2026-09-02T09:46:11Z",
  "script_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "contact_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "did": null,
  "max_concurrent": 10,
  "ws_url": "wss://MEDIA_EDGE_HOST",
  "sip_domain": "MEDIA_EDGE_HOST",
  "sip_username": "SIP_USERNAME",
  "sip_password": "SIP_PASSWORD",
  "target": "sip:web@MEDIA_EDGE_HOST",
  "headers": { "...": "..." }
}

Everything from ws_url down is connection bootstrap. Your page passes it straight to the browser client in the next step — you never need to read, construct or understand any of it. The response has no call_id. The call doesn’t exist until the visitor actually connects; it shows up in your call log at that point. Now expose that as an endpoint of your own. Your page calls your endpoint; only your server holds the API key.

Node — Express

import express from 'express';

const app = express();

app.post('/api/voice-session', async (req, res) => {
  const response = await fetch('https://api.voxworks.ai/api/v1/create-web-session', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VOXWORKS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      script_id: process.env.VOXWORKS_SCRIPT_ID,
      participant_identity: req.body?.visitorId,
    }),
  });

  res.status(response.status).json(await response.json());
});

TypeScript — Next.js route handler

// app/api/voice-session/route.ts
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { visitorId } = await request.json().catch(() => ({}));

  const response = await fetch('https://api.voxworks.ai/api/v1/create-web-session', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VOXWORKS_API_KEY!}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      script_id: process.env.VOXWORKS_SCRIPT_ID,
      participant_identity: visitorId,
    }),
  });

  return NextResponse.json(await response.json(), { status: response.status });
}

Python — FastAPI

import os

import httpx
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()


@app.post("/api/voice-session")
async def voice_session(request: Request):
    body = await request.json()

    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.post(
            "https://api.voxworks.ai/api/v1/create-web-session",
            headers={"Authorization": f"Bearer {os.environ['VOXWORKS_API_KEY']}"},
            json={
                "script_id": os.environ["VOXWORKS_SCRIPT_ID"],
                "participant_identity": body.get("visitorId"),
            },
        )

    return JSONResponse(status_code=response.status_code, content=response.json())

Python — Flask

import os

import requests
from flask import Flask, jsonify, request

app = Flask(__name__)


@app.post("/api/voice-session")
def voice_session():
    response = requests.post(
        "https://api.voxworks.ai/api/v1/create-web-session",
        headers={"Authorization": f"Bearer {os.environ['VOXWORKS_API_KEY']}"},
        json={
            "script_id": os.environ["VOXWORKS_SCRIPT_ID"],
            "participant_identity": (request.get_json(silent=True) or {}).get("visitorId"),
        },
        timeout=10,
    )

    return jsonify(response.json()), response.status_code

Mint the session when the visitor clicks, not when the page loads. The token expires in about two minutes.

3. Connect the browser

The browser speaks SIP over a secure WebSocket. JsSIP handles that:

npm install jssip

Fetch a session from your endpoint, then dial the media edge with the values it returned:

import JsSIP from 'jssip';

async function startCall() {
  const response = await fetch('/api/voice-session', { method: 'POST' });
  const session = await response.json();

  if (!response.ok || !session.success) {
    throw new Error(session.message || `Session endpoint returned ${response.status}`);
  }

  const audio = document.createElement('audio');
  audio.autoplay = true;
  document.body.append(audio);

  const ua = new JsSIP.UA({
    sockets: [new JsSIP.WebSocketInterface(session.ws_url)],
    uri: `sip:${session.sip_username}@${session.sip_domain}`,
    authorization_user: session.sip_username,
    password: session.sip_password,
    register: false,
    session_timers: false,
  });

  ua.on('connected', () => {
    const call = ua.call(session.target, {
      mediaConstraints: { audio: true, video: false },
      extraHeaders: Object.entries(session.headers).map(([k, v]) => `${k}: ${v}`),
      pcConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
      rtcOfferConstraints: { offerToReceiveAudio: true, offerToReceiveVideo: false },
    });

    // The peer connection may already exist by the time call() returns, in which
    // case the 'peerconnection' event has already fired. Check for it first or
    // the visitor gets a connected call with no audio.
    const attach = (pc) => {
      pc.addEventListener('track', (event) => {
        audio.srcObject = event.streams[0];
      });
    };

    if (call.connection) attach(call.connection);
    else call.on('peerconnection', ({ peerconnection }) => attach(peerconnection));

    call.on('confirmed', () => console.log('connected'));
    call.on('failed', (data) => console.error('call failed', data.cause));
  });

  ua.start();
  return ua;
}

Hang up by calling ua.stop().

A complete page

Everything above, as a page you can serve and click:

<!doctype html>
<meta charset="utf-8">
<title>Talk to the agent</title>

<button id="talk">Start call</button>
<button id="hangup" disabled>Hang up</button>
<span id="state">idle</span>

<script type="importmap">
  { "imports": { "jssip": "https://esm.sh/jssip@3.13.8" } }
</script>
<script type="module">
  import JsSIP from 'jssip';

  const talk = document.querySelector('#talk');
  const hangup = document.querySelector('#hangup');
  const label = document.querySelector('#state');
  let ua = null;

  talk.onclick = async () => {
    label.textContent = 'connecting';
    talk.disabled = true;
    hangup.disabled = false;

    const response = await fetch('/api/voice-session', { method: 'POST' });
    const session = await response.json();

    const audio = document.createElement('audio');
    audio.autoplay = true;
    document.body.append(audio);

    ua = new JsSIP.UA({
      sockets: [new JsSIP.WebSocketInterface(session.ws_url)],
      uri: `sip:${session.sip_username}@${session.sip_domain}`,
      authorization_user: session.sip_username,
      password: session.sip_password,
      register: false,
      session_timers: false,
    });

    ua.on('connected', () => {
      const call = ua.call(session.target, {
        mediaConstraints: { audio: true, video: false },
        extraHeaders: Object.entries(session.headers).map(([k, v]) => `${k}: ${v}`),
        pcConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
        rtcOfferConstraints: { offerToReceiveAudio: true, offerToReceiveVideo: false },
      });

      const attach = (pc) => {
        pc.addEventListener('track', (e) => { audio.srcObject = e.streams[0]; });
      };
      if (call.connection) attach(call.connection);
      else call.on('peerconnection', ({ peerconnection }) => attach(peerconnection));
      call.on('confirmed', () => { label.textContent = 'connected'; });
      call.on('ended', () => { label.textContent = 'ended'; });
      call.on('failed', (d) => { label.textContent = d.cause || 'failed'; });
    });

    ua.start();
  };

  hangup.onclick = () => {
    ua?.stop();
    talk.disabled = false;
    hangup.disabled = true;
    label.textContent = 'ended';
  };
</script>

The page must be served over HTTPS or from localhost — browsers only grant microphone access to a secure context.

React

import { useCallback, useRef, useState } from 'react';
import JsSIP from 'jssip';

type CallState = 'idle' | 'connecting' | 'connected' | 'ended' | 'failed';

export function useVoxworksCall() {
  const [state, setState] = useState<CallState>('idle');
  const uaRef = useRef<JsSIP.UA | null>(null);

  const start = useCallback(async () => {
    setState('connecting');

    const response = await fetch('/api/voice-session', { method: 'POST' });
    const session = await response.json();

    if (!response.ok || !session.success) {
      setState('failed');
      return;
    }

    const audio = document.createElement('audio');
    audio.autoplay = true;
    document.body.append(audio);

    const ua = new JsSIP.UA({
      sockets: [new JsSIP.WebSocketInterface(session.ws_url)],
      uri: `sip:${session.sip_username}@${session.sip_domain}`,
      authorization_user: session.sip_username,
      password: session.sip_password,
      register: false,
      session_timers: false,
    });

    ua.on('connected', () => {
      const call = ua.call(session.target, {
        mediaConstraints: { audio: true, video: false },
        extraHeaders: Object.entries(session.headers).map(([k, v]) => `${k}: ${v}`),
        pcConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },
        rtcOfferConstraints: { offerToReceiveAudio: true, offerToReceiveVideo: false },
      });

      const attach = (pc: RTCPeerConnection) => {
        pc.addEventListener('track', (e: RTCTrackEvent) => {
          audio.srcObject = e.streams[0];
        });
      };

      if (call.connection) attach(call.connection);
      else call.on('peerconnection', ({ peerconnection }: any) => attach(peerconnection));
      call.on('confirmed', () => setState('connected'));
      call.on('ended', () => setState('ended'));
      call.on('failed', () => setState('failed'));
    });

    ua.start();
    uaRef.current = ua;
  }, []);

  const hangup = useCallback(() => {
    uaRef.current?.stop();
    uaRef.current = null;
    setState('ended');
  }, []);

  return { state, start, hangup };
}

Always configure an ICE server

The pcConfig block in every example above is not optional:

pcConfig: { iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] },

Until a visitor has granted microphone permission, browsers withhold the local network details needed to set up the audio path. Without an ICE server there’s nothing to fall back on and the call cannot connect. The symptom is easy to misread: the call fails on a visitor’s first click and works on the next one, because by then the permission grant is persistent. Configure a STUN server and it works the first time. If your visitors sit behind restrictive corporate networks, supply a TURN server here as well.

Ask for microphone permission on a click. Browsers only prompt in response to a user gesture, and a call started without a gesture cannot play the agent’s audio back.

Request options

Field	Required	What it does
`script_id`	yes	Which agent script the call runs. Must belong to your team.
`did`	no	One of your team’s numbers, used as the AI-side number identity on the call record. Omit for a browser-only call.
`contact_id`	no	Attach the call to a known contact. Omitted uses your team’s shared web contact.
`participant_identity`	no	A label for the visitor, carried through to the transcript.
`objects`	no	Objects to link to the contact, same shape as the `objects` field on `create-phone-call`.

Response fields

Field	What it’s for
`session_token`	The single-use token authorising this one call. Already included in `headers`.
`expires_at`	When the token stops being redeemable, about two minutes after minting.
`ws_url`, `sip_domain`, `sip_username`, `sip_password`, `target`	Connection bootstrap. Pass through to the browser client unchanged.
`headers`	Call metadata to forward verbatim. Don’t construct these yourself.
`max_concurrent`	Your team’s concurrent-call ceiling.

Read ws_url, sip_domain, sip_username, sip_password and target from the response on every call — never hardcode them. They can change without notice, and a page pinned to stale values fails with nothing more than a generic connection error, which is very hard to diagnose.

Errors worth handling

Status	Meaning
`400`	The body isn’t valid JSON, `script_id` is missing or malformed, `contact_id` is malformed, or `objects` failed validation.
`404`	`script_id` — or `contact_id`, if you sent one — isn’t yours.
`429`	Your team is at its concurrent-call limit. The response carries `max_concurrent`.
`500`	The external web-call path isn’t configured for this environment.

Every error uses the standard shape:

{
  "success": false,
  "message": "script_id not found or does not belong to your team"
}

Limits

The token expires in about two minutes. Mint it when the visitor clicks, not on page load.
One token, one call. Reloading the page needs a new session.
Concurrency is per team and shared with phone calls. A team at its ceiling on outbound calls cannot start a web call either.
The page must be a secure context — HTTPS, or localhost while developing.

Next Steps

Web Calls

How web calls behave once connected — the Call Log, web contacts, handoff, and recordings.

API Quickstart

Generate a key, create a contact, and run your first request against the API.

Live handoff

Hand a web call to a human, dialled on one of your team’s numbers.

Rate Limits & Request Limits

Rate-limit buckets, the 429 headers, and the request body size cap.

API Basics

Endpoints

Embedded Web Calls

Overview

What the session token is

1. Find your `script_id`

2. Mint a session on your server

Node — Express

TypeScript — Next.js route handler

Python — FastAPI

Python — Flask

3. Connect the browser

A complete page

React

Always configure an ICE server

Request options

Response fields

Errors worth handling

Limits

Next Steps

Web Calls

API Quickstart

Live handoff

Rate Limits & Request Limits

​Overview

​What the session token is

​1. Find your script_id

​2. Mint a session on your server

​Node — Express

​TypeScript — Next.js route handler

​Python — FastAPI

​Python — Flask

​3. Connect the browser

​A complete page

​React

​Always configure an ICE server

​Request options

​Response fields

​Errors worth handling

​Limits

​Next Steps

Web Calls

API Quickstart

Live handoff

Rate Limits & Request Limits

Overview

What the session token is

1. Find your `script_id`

2. Mint a session on your server

Node — Express

TypeScript — Next.js route handler

Python — FastAPI

Python — Flask

3. Connect the browser

A complete page

React

Always configure an ICE server

Request options

Response fields

Errors worth handling

Limits

Next Steps