Web-call API & WebSocket

The web-call API runs a conversation in the browser over a WebSocket — the visitor's microphone streams to the agent and the agent's voice streams back, with no phone number involved. You start a session over REST, then connect a WebSocket to the returned URL. The same socket can also run a text conversation (no audio) if you just want a chat surface bound to a live session.

For a complete, copy-pasteable recipe see Programmatic web calls. If you only need text and don't want to manage a WebSocket at all, use the simpler Chat API instead.

Start a session

POST /api/sessions/init-web-call

This endpoint accepts three credentials, and which one you use determines where the call can legitimately be started from:

Never put an API key in browser code. It's a bearer credential for your whole organization — every agent, every call record, every number. Anything shipped to a browser is public. Mint a client token on your server instead.

Server-side (API key):

curl -X POST https://api.telenow.ai/api/sessions/init-web-call \
  -H "x-api-key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "…" }'

Browser (client token) — the body can be empty, because everything that matters is already baked into the token:

curl -X POST https://api.telenow.ai/api/sessions/init-web-call \
  -H "Authorization: Bearer eyJhbGciOi…" \
  -H "Content-Type: application/json" -d '{}'

What a client token overrides

When you authenticate with a client token, the fields below are read from the token and whatever you send in the body is discarded. This is deliberate: the body is attacker-controlled once the token is in a browser.

Fields the token doesn't pin (bearer, payload, firstResponse, clientRecording) are still read from the body. Treat them as client-supplied and don't let a tool trust them for authorization.

Request fields

Response

{
  "success": true,
  "data": {
    "sessionId": "…",
    "status": "active",
    "websocketUrl": "wss://api.telenow.ai/ws/web-agent",
    "embedSnippet": "<script>…</script>"
  }
}

Connect a browser WebSocket to websocketUrl, then send { "event": "start", "sessionId": "…" } as the first frame (see the WebSocket protocol below) — the API key stays on your server; the browser only ever holds the opaque sessionId.

Manual mode (softphone / click-to-call)

Pass mode: "manual" to place a human telephony call instead of an AI one — the bridge behind the dashboard softphone, exposed for embedding click-to-call in your own CRM. Telenow rings toNumber from fromNumber (a caller-ID your org owns — Numbers, BYOC, or a SIP trunk) and bridges the carrier leg to the browser that connects the returned websocketUrl. No agent, STT, LLM, or TTS runs.

curl -X POST https://api.telenow.ai/api/sessions/init-web-call \
  -H "x-api-key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "manual", "fromNumber": "+15550001111", "toNumber": "+15551234567" }'

With an API key, fromNumber is required; on a user JWT it defaults to the member's allocated number. The response carries the carrier-call fields:

{
  "success": true,
  "data": {
    "sessionId": "…",
    "status": "active",
    "callId": "…",
    "callMode": "manual",
    "fromNumber": "+15550001111",
    "toNumber": "+15551234567",
    "websocketUrl": "wss://api.telenow.ai/ws/web-agent"
  }
}

Hand { sessionId, websocketUrl } to the client SDK (TelenowCall({ session })) — that browser becomes the rep's mic + speaker. The call is recorded server-side and the same webhooks (call.started, call.ended, recording.ready) fire as for AI calls, so the recording URL and call data land in your CRM automatically. The sessionId also works with POST /api/sessions/{id}/transfer and DELETE /api/sessions/{id}. Works on every carrier: Plivo, Twilio, Vobiz, Exotel, Vonage, Tata Tele Smartflo, and SIP trunks. The simplest way to drive it is the backend SDK (createManual / create_manual_call).

Errors mirror the outbound-call gates: 403 if toNumber is on the Do-Not-Call list, 429 at quota/concurrency caps, 404 if fromNumber isn't owned by your org, 400 with a code when the carrier refuses for something on the account (empty wallet, incomplete KYC, missing App ID — see outbound-call errors), and 502 when the carrier itself is unwell.

WebSocket protocol

Messages are JSON text frames with an event field. Audio is base64-encoded μ-law, 8 kHz, mono, sent in small (~20 ms) frames. One message may be at most 2 MiB; a larger one closes the socket.

Server → client

Client → server

Flow (voice)

1. POST /api/sessions/init-web-call → get websocketUrl.
2. Open the WebSocket. On open (or on ready), send { "event": "start", "sessionId": … }.
3. On connected, capture mic audio, resample to μ-law 8 kHz, and stream media frames.
4. Play incoming media frames; render transcript events as needed.
5. Answer any ping with a matching pong so the socket isn't dropped as idle.
6. On session_end, stop and close.

Barge-in is built in: when the user speaks while the agent is talking, the agent stops and listens — your client just keeps streaming mic frames.

Flow (text only)

If you only want chat, skip the audio: after start/connected, send { "event": "text", "text": "…", "chat": true } and read the streamed text-response chunks. For most chat use cases the stateless Chat API is simpler — no socket to keep alive.

Files and voice notes in chat

On the public widget (sessions started with POST /api/public/widget/{slug}/session), a customer can send a voice note, a picture (PNG, JPEG, GIF, WebP), a PDF, or a Word or Excel file (DOCX, XLSX). The agent hears a voice note through its own speech-to-text provider, as on WhatsApp, and is told when an image or a document arrives (it cannot open them yet). Not on a realtime (speech-to-speech) agent.

1. The session reply carries uploads: null when files are not taken (a realtime agent), otherwise the limits to check before sending:

   Copy

   "uploads": {
     "maxVoiceNoteSecs": 600,
     "maxBytes": { "audio": 5242880, "image": 5242880, "document": 10485760 },
     "maxFiles": 20,
     "accept": "audio/*,image/png,…"
   }
   

2. Upload the file over HTTP, not the socket: POST /api/public/widget/{slug}/session/{sessionId}/attachments, the file itself as the body, its name percent-encoded in X-File-Name. No API key; the session id is the credential, and the page's origin must be one the widget allows. The type is decided from the file's bytes, whatever Content-Type says. The answer comes at once:

   Copy

   { "success": true, "data": { "attachmentId": "…", "kind": "audio", "mime": "audio/webm", "fileName": "voice-note.webm", "sizeBytes": 48211 } }
   

   Refusals: 413 too large (the message names the limit), 400 with code: "unsupported_type" or "empty_file", 429 too many (this chat's files, this connection's uploads a minute, or the account's uploads today; Retry-After says when), 409 a realtime agent, 403 the account cannot spend (the chat ends), 404 the chat is not open, 503 busy, try again shortly.

3. Send { "event": "text", "text": "<their words, or empty>", "chat": true, "attachmentId": "…" } on the socket. You get attachment-heard, then the reply as text-response. A typed message sent after it waits until it is answered, so replies come in the order sent.

Limits are the platform's settings (defaults shown above), plus a cap on files per chat and per account per day. A voice note is billed as speech-to-text at the file rate, plus the usual chat turn. Files appear in call history, and follow the account's retention window.

Embedding instead

If you don't want to build the audio plumbing, use the hosted widget — a one-line script tag does all of the above. See Embed the widget. To start sessions for the anonymous public widget (no API key), use POST /api/public/widget/{slug}/session instead of init-web-call; both return the same websocketUrl shape and speak the same protocol above.