@callagent/web-sdk

Classes

AudioPlayer

Defined in: apps/web-sdk/src/audio/player.ts:31

Constructors

Constructor

new AudioPlayer(options): AudioPlayer;

Defined in: apps/web-sdk/src/audio/player.ts:42

Parameters

Parameter	Type
options	AudioPlayerOptions

Returns

AudioPlayer

Accessors

context

Get Signature

get context(): AudioContext | null;

Defined in: apps/web-sdk/src/audio/player.ts:55

Returns

AudioContext | null

generation

Get Signature

get generation(): number;

Defined in: apps/web-sdk/src/audio/player.ts:74

Increments once per interruption; exposed so specs can assert the boundary moved.

Returns

number

isSpeaking

Get Signature

get isSpeaking(): boolean;

Defined in: apps/web-sdk/src/audio/player.ts:46

Returns

boolean

pendingSourceCount

Get Signature

get pendingSourceCount(): number;

Defined in: apps/web-sdk/src/audio/player.ts:51

Queued-but-unplayed sources. Exposed so specs can assert an interrupt drained.

Returns

number

Methods

clear()

clear(): void;

Defined in: apps/web-sdk/src/audio/player.ts:120

Stop immediately and discard everything queued. Called on the gateway's clear control frame and on hangup.

Returns

void

close()

close(): Promise<void>;

Defined in: apps/web-sdk/src/audio/player.ts:146

Returns

Promise<void>

enqueue()

enqueue(pcm): void;

Defined in: apps/web-sdk/src/audio/player.ts:78

Parameters

Parameter	Type
pcm	Int16Array

Returns

void

resume()

resume(): Promise<void>;

Defined in: apps/web-sdk/src/audio/player.ts:63

Must be called from a user gesture on Safari and Chrome, otherwise the context starts suspended and the first assistant reply is silent.

Returns

Promise<void>

setVolume()

setVolume(volume): void;

Defined in: apps/web-sdk/src/audio/player.ts:68

Parameters

Parameter	Type
volume	number

Returns

void

---

Backoff

Defined in: apps/web-sdk/src/backoff.ts:14

Exponential backoff with jitter, deterministic under an injected RNG so the reconnection specs can assert exact delays instead of sleeping.

Constructors

Constructor

new Backoff(options?, random?): Backoff;

Defined in: apps/web-sdk/src/backoff.ts:23

Parameters

Parameter	Type	Default value
options	BackoffOptions	{}
random	() => number	Math.random

Returns

Backoff

Accessors

attempt

Get Signature

get attempt(): number;

Defined in: apps/web-sdk/src/backoff.ts:32

Returns

number

exhausted

Get Signature

get exhausted(): boolean;

Defined in: apps/web-sdk/src/backoff.ts:36

Returns

boolean

Methods

next()

next(): number;

Defined in: apps/web-sdk/src/backoff.ts:45

Consumes one attempt and returns how long to wait before it.

Returns

number

reset()

reset(): void;

Defined in: apps/web-sdk/src/backoff.ts:40

Returns

void

---

Call

Defined in: apps/web-sdk/src/call.ts:55

One live session: voice or chat, WebRTC or WebSocket.

The public surface is deliberately small — mute, unmute, send, stop and the event stream — because everything else about the conversation is decided server-side where it can be logged, billed and replayed.

Extends

• Emitter<CallEvents>

Constructors

Constructor

new Call(deps, startOptions): Call;

Defined in: apps/web-sdk/src/call.ts:75

Parameters

Parameter	Type
deps	CallDependencies
startOptions	StartCallOptions

Returns

Call

Overrides

Emitter.constructor

Accessors

id

Get Signature

get id(): string;

Defined in: apps/web-sdk/src/call.ts:81

Returns

string

isAssistantSpeaking

Get Signature

get isAssistantSpeaking(): boolean;

Defined in: apps/web-sdk/src/call.ts:106

True while assistant audio is actually reaching the speakers.

Returns

boolean

isMuted

Get Signature

get isMuted(): boolean;

Defined in: apps/web-sdk/src/call.ts:97

Returns

boolean

mode

Get Signature

get mode(): "voice" | "chat";

Defined in: apps/web-sdk/src/call.ts:101

Returns

"voice" | "chat"

sessionId

Get Signature

get sessionId(): string;

Defined in: apps/web-sdk/src/call.ts:85

Returns

string

state

Get Signature

get state(): 
  | "created"
  | "queued"
  | "ringing"
  | "connecting"
  | "connected"
  | "listening"
  | "user_speaking"
  | "thinking"
  | "tool_executing"
  | "assistant_speaking"
  | "on_hold"
  | "transferring"
  | "human_queue"
  | "human_connected"
  | "ending"
  | "ended"
  | "failed";

Defined in: apps/web-sdk/src/call.ts:89

Returns

| "created" | "queued" | "ringing" | "connecting" | "connected" | "listening" | "user_speaking" | "thinking" | "tool_executing" | "assistant_speaking" | "on_hold" | "transferring" | "human_queue" | "human_connected" | "ending" | "ended" | "failed"

transport

Get Signature

get transport(): TransportKind;

Defined in: apps/web-sdk/src/call.ts:93

Returns

TransportKind

Methods

emit()

emit<K>(event, payload): void;

Defined in: apps/web-sdk/src/emitter.ts:47

A throwing listener must never take the call down with it — customer page code is on the other end of these callbacks.

Type Parameters

Type Parameter
K extends keyof CallEvents

Parameters

Parameter	Type
event	K
payload	CallEvents[K]

Returns

void

Inherited from

Emitter.emit

listenerCount()

listenerCount<K>(event): number;

Defined in: apps/web-sdk/src/emitter.ts:39

Type Parameters

Type Parameter
K extends keyof CallEvents

Parameters

Parameter	Type
event	K

Returns

number

Inherited from

Emitter.listenerCount

mute()

mute(): void;

Defined in: apps/web-sdk/src/call.ts:212

Returns

void

off()

off<K>(event, listener): void;

Defined in: apps/web-sdk/src/emitter.ts:31

Type Parameters

Type Parameter
K extends keyof CallEvents

Parameters

Parameter	Type
event	K
listener	Listener<CallEvents[K]>

Returns

void

Inherited from

Emitter.off

on()

on<K>(event, listener): () => void;

Defined in: apps/web-sdk/src/emitter.ts:13

Type Parameters

Type Parameter
K extends keyof CallEvents

Parameters

Parameter	Type
event	K
listener	Listener<CallEvents[K]>

Returns

() => void

Inherited from

Emitter.on

once()

once<K>(event, listener): () => void;

Defined in: apps/web-sdk/src/emitter.ts:23

Type Parameters

Type Parameter
K extends keyof CallEvents

Parameters

Parameter	Type
event	K
listener	Listener<CallEvents[K]>

Returns

() => void

Inherited from

Emitter.once

removeAllListeners()

removeAllListeners(): void;

Defined in: apps/web-sdk/src/emitter.ts:35

Returns

void

Inherited from

Emitter.removeAllListeners

send()

send(content): void;

Defined in: apps/web-sdk/src/call.ts:225

Sends a typed message. Works in both chat and voice mode.

Parameters

Parameter	Type
content	string

Returns

void

sendDtmf()

sendDtmf(digits): void;

Defined in: apps/web-sdk/src/call.ts:232

The gateway takes one digit per frame, so a string is sent digit by digit.

Parameters

Parameter	Type
digits	string

Returns

void

setMuted()

setMuted(muted): void;

Defined in: apps/web-sdk/src/call.ts:220

Parameters

Parameter	Type
muted	boolean

Returns

void

setVolume()

setVolume(volume): void;

Defined in: apps/web-sdk/src/call.ts:238

0…1. Applies to both the WebSocket player and the WebRTC element.

Parameters

Parameter	Type
volume	number

Returns

void

stop()

stop(reason?): Promise<void>;

Defined in: apps/web-sdk/src/call.ts:206

Parameters

Parameter	Type	Default value
reason	string	'client_hangup'

Returns

Promise<void>

unmute()

unmute(): void;

Defined in: apps/web-sdk/src/call.ts:216

Returns

void

---

CallAgent

Defined in: apps/web-sdk/src/client.ts:33

The entry point.

const client = new CallAgent({ publicKey, apiUrl });
client.on('client-tool', async ({ name, arguments: args }) => { … });
const call = await client.start({ assistantId, variables });

One client can start many calls; it owns the token lifecycle and the client-tool registry, both of which outlive an individual call.

Extends

• Emitter<CallAgentEvents>

Constructors

Constructor

new CallAgent(options): CallAgent;

Defined in: apps/web-sdk/src/client.ts:41

Parameters

Parameter	Type
options	CallAgentOptions

Returns

CallAgent

Overrides

Emitter.constructor

Accessors

activeCall

Get Signature

get activeCall(): Call | null;

Defined in: apps/web-sdk/src/client.ts:78

Returns

Call | null

apiUrl

Get Signature

get apiUrl(): string;

Defined in: apps/web-sdk/src/client.ts:74

Returns

string

Methods

dispose()

dispose(): void;

Defined in: apps/web-sdk/src/client.ts:168

Releases the refresh timer. Call it when the page tears the client down.

Returns

void

emit()

emit<K>(event, payload): void;

Defined in: apps/web-sdk/src/emitter.ts:47

A throwing listener must never take the call down with it — customer page code is on the other end of these callbacks.

Type Parameters

Type Parameter
K extends keyof CallAgentEvents

Parameters

Parameter	Type
event	K
payload	CallAgentEvents[K]

Returns

void

Inherited from

Emitter.emit

listenerCount()

listenerCount<K>(event): number;

Defined in: apps/web-sdk/src/emitter.ts:39

Type Parameters

Type Parameter
K extends keyof CallAgentEvents

Parameters

Parameter	Type
event	K

Returns

number

Inherited from

Emitter.listenerCount

off()

off<K>(event, listener): void;

Defined in: apps/web-sdk/src/emitter.ts:31

Type Parameters

Type Parameter
K extends keyof CallAgentEvents

Parameters

Parameter	Type
event	K
listener	Listener<CallAgentEvents[K]>

Returns

void

Inherited from

Emitter.off

on()

on<K>(event, listener): () => void;

Defined in: apps/web-sdk/src/client.ts:98

Type Parameters

Type Parameter
K extends keyof CallAgentEvents

Parameters

Parameter	Type
event	K
listener	(payload) => void

Returns

() => void

Overrides

Emitter.on

once()

once<K>(event, listener): () => void;

Defined in: apps/web-sdk/src/emitter.ts:23

Type Parameters

Type Parameter
K extends keyof CallAgentEvents

Parameters

Parameter	Type
event	K
listener	Listener<CallAgentEvents[K]>

Returns

() => void

Inherited from

Emitter.once

registerTool()

registerTool(name, handler): () => void;

Defined in: apps/web-sdk/src/client.ts:91

Registers a handler for a specific client-side tool (§32). Named registration wins over a generic on('client-tool') handler.

Parameters

Parameter	Type
name	string
handler	ClientToolHandler

Returns

() => void

removeAllListeners()

removeAllListeners(): void;

Defined in: apps/web-sdk/src/emitter.ts:35

Returns

void

Inherited from

Emitter.removeAllListeners

start()

start(options?): Promise<Call>;

Defined in: apps/web-sdk/src/client.ts:117

Parameters

Parameter	Type
options	StartCallOptions

Returns

Promise<Call>

startChat()

startChat(options?): Promise<Call>;

Defined in: apps/web-sdk/src/client.ts:158

Chat-only session: same protocol, same events, no microphone or speaker.

Parameters

Parameter	Type
options	Omit<StartCallOptions, "mode">

Returns

Promise<Call>

stop()

stop(reason?): Promise<void>;

Defined in: apps/web-sdk/src/client.ts:162

Parameters

Parameter	Type	Default value
reason	string	'client_hangup'

Returns

Promise<void>

---

CallAgentError

Defined in: apps/web-sdk/src/errors.ts:38

Extends

• Error

Constructors

Constructor

new CallAgentError(options): CallAgentError;

Defined in: apps/web-sdk/src/errors.ts:44

Parameters

Parameter	Type
options	CallAgentErrorOptions

Returns

CallAgentError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
cause?	public	unknown	-	Error.cause	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
code	readonly	CallAgentErrorCode	-	-	apps/web-sdk/src/errors.ts:39
details?	readonly	Record<string, unknown>	-	-	apps/web-sdk/src/errors.ts:42
documentationUrl?	readonly	string	-	-	apps/web-sdk/src/errors.ts:41
message	public	string	-	Error.message	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077
name	public	string	-	Error.name	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076
retryable	readonly	boolean	-	-	apps/web-sdk/src/errors.ts:40
stack?	public	string	-	Error.stack	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078
stackTraceLimit	static	number	The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)). The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	Error.stackTraceLimit	node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:68

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
targetObject	object
constructorOpt?	Function

Returns

void

Inherited from

Error.captureStackTrace

from()

static from(value, fallback?): CallAgentError;

Defined in: apps/web-sdk/src/errors.ts:53

Parameters

Parameter	Type	Default value
value	unknown	undefined
fallback	CallAgentErrorCode	'server_error'

Returns

CallAgentError

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:56

Parameters

Parameter	Type
err	Error
stackTraces	CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

---

Emitter

Defined in: apps/web-sdk/src/emitter.ts:10

Extended by

• CallAgent
• Call

Type Parameters

Type Parameter
Events extends Record<string, unknown>

Constructors

Constructor

new Emitter<Events>(): Emitter<Events>;

Returns

Emitter<Events>

Methods

emit()

emit<K>(event, payload): void;

Defined in: apps/web-sdk/src/emitter.ts:47

A throwing listener must never take the call down with it — customer page code is on the other end of these callbacks.

Type Parameters

Type Parameter
K extends string | number | symbol

Parameters

Parameter	Type
event	K
payload	Events[K]

Returns

void

listenerCount()

listenerCount<K>(event): number;

Defined in: apps/web-sdk/src/emitter.ts:39

Type Parameters

Type Parameter
K extends string | number | symbol

Parameters

Parameter	Type
event	K

Returns

number

off()

off<K>(event, listener): void;

Defined in: apps/web-sdk/src/emitter.ts:31

Type Parameters

Type Parameter
K extends string | number | symbol

Parameters

Parameter	Type
event	K
listener	Listener<Events[K]>

Returns

void

on()

on<K>(event, listener): () => void;

Defined in: apps/web-sdk/src/emitter.ts:13

Type Parameters

Type Parameter
K extends string | number | symbol

Parameters

Parameter	Type
event	K
listener	Listener<Events[K]>

Returns

() => void

once()

once<K>(event, listener): () => void;

Defined in: apps/web-sdk/src/emitter.ts:23

Type Parameters

Type Parameter
K extends string | number | symbol

Parameters

Parameter	Type
event	K
listener	Listener<Events[K]>

Returns

() => void

removeAllListeners()

removeAllListeners(): void;

Defined in: apps/web-sdk/src/emitter.ts:35

Returns

void

---

FrameAccumulator

Defined in: apps/web-sdk/src/audio/pcm.ts:57

Accumulates arbitrary-length chunks and emits exactly frameSamples at a time.

Constructors

Constructor

new FrameAccumulator(frameSamples): FrameAccumulator;

Defined in: apps/web-sdk/src/audio/pcm.ts:61

Parameters

Parameter	Type
frameSamples	number

Returns

FrameAccumulator

Methods

push()

push(chunk): Float32Array<ArrayBufferLike>[];

Defined in: apps/web-sdk/src/audio/pcm.ts:65

Parameters

Parameter	Type
chunk	Float32Array

Returns

Float32Array<ArrayBufferLike>[]

reset()

reset(): void;

Defined in: apps/web-sdk/src/audio/pcm.ts:89

Returns

void

---

Microphone

Defined in: apps/web-sdk/src/audio/microphone.ts:95

Constructors

Constructor

new Microphone(options): Microphone;

Defined in: apps/web-sdk/src/audio/microphone.ts:106

Parameters

Parameter	Type
options	MicrophoneOptions

Returns

Microphone

Accessors

muted

Get Signature

get muted(): boolean;

Defined in: apps/web-sdk/src/audio/microphone.ts:114

Returns

boolean

stream

Get Signature

get stream(): MediaStream | null;

Defined in: apps/web-sdk/src/audio/microphone.ts:110

Returns

MediaStream | null

Methods

close()

close(): Promise<void>;

Defined in: apps/web-sdk/src/audio/microphone.ts:222

Returns

Promise<void>

open()

open(): Promise<MediaStream>;

Defined in: apps/web-sdk/src/audio/microphone.ts:130

Acquires the device. Throws a CallAgentError with an actionable message.

Returns

Promise<MediaStream>

setMuted()

setMuted(muted): void;

Defined in: apps/web-sdk/src/audio/microphone.ts:213

Parameters

Parameter	Type
muted	boolean

Returns

void

setTargetSampleRate()

setTargetSampleRate(sampleRate): void;

Defined in: apps/web-sdk/src/audio/microphone.ts:122

The gateway announces the negotiated rate after the handshake, which may differ from what we asked for; the resampler has to follow it or we send the wrong pitch.

Parameters

Parameter	Type
sampleRate	number

Returns

void

startCapture()

startCapture(onFrame): Promise<void>;

Defined in: apps/web-sdk/src/audio/microphone.ts:173

Starts pumping PCM frames. Only used by the WebSocket fallback — under WebRTC the MediaStream goes straight onto a peer connection and the browser does the encoding, which is both cheaper and better sounding.

Parameters

Parameter	Type
onFrame	(pcm) => void

Returns

Promise<void>

---

SessionSocket

Defined in: apps/web-sdk/src/transport/socket.ts:50

Constructors

Constructor

new SessionSocket(options): SessionSocket;

Defined in: apps/web-sdk/src/transport/socket.ts:63

Parameters

Parameter	Type
options	SessionSocketOptions

Returns

SessionSocket

Accessors

reconnectAttempts

Get Signature

get reconnectAttempts(): number;

Defined in: apps/web-sdk/src/transport/socket.ts:74

Returns

number

state

Get Signature

get state(): SocketState;

Defined in: apps/web-sdk/src/transport/socket.ts:70

Returns

SocketState

Methods

close()

close(code?, reason?): void;

Defined in: apps/web-sdk/src/transport/socket.ts:94

Parameters

Parameter	Type	Default value
code	number	1000
reason	string	'client_closed'

Returns

void

connect()

connect(): Promise<void>;

Defined in: apps/web-sdk/src/transport/socket.ts:78

Returns

Promise<void>

send()

send(frame): void;

Defined in: apps/web-sdk/src/transport/socket.ts:83

Parameters

Parameter	Type
frame	ClientFrame

Returns

void

sendAudio()

sendAudio(payload): void;

Defined in: apps/web-sdk/src/transport/socket.ts:87

Parameters

Parameter	Type
payload	ArrayBuffer

Returns

void

---

TokenManager

Defined in: apps/web-sdk/src/auth.ts:160

Constructors

Constructor

new TokenManager(options): TokenManager;

Defined in: apps/web-sdk/src/auth.ts:174

Parameters

Parameter	Type
options	TokenManagerOptions

Returns

TokenManager

Accessors

expiresAtMs

Get Signature

get expiresAtMs(): number;

Defined in: apps/web-sdk/src/auth.ts:195

Returns

number

token

Get Signature

get token(): string | null;

Defined in: apps/web-sdk/src/auth.ts:191

Returns

string | null

Methods

getToken()

getToken(): Promise<string>;

Defined in: apps/web-sdk/src/auth.ts:200

Returns a token that is valid now, fetching or refreshing if necessary.

Returns

Promise<string>

refresh()

refresh(): Promise<string>;

Defined in: apps/web-sdk/src/auth.ts:205

Returns

Promise<string>

stop()

stop(): void;

Defined in: apps/web-sdk/src/auth.ts:213

Returns

void

---

WebRtcMedia

Defined in: apps/web-sdk/src/transport/webrtc.ts:40

Constructors

Constructor

new WebRtcMedia(options): WebRtcMedia;

Defined in: apps/web-sdk/src/transport/webrtc.ts:47

Parameters

Parameter	Type
options	WebRtcMediaOptions

Returns

WebRtcMedia

Accessors

connectionState

Get Signature

get connectionState(): RTCPeerConnectionState;

Defined in: apps/web-sdk/src/transport/webrtc.ts:51

Returns

RTCPeerConnectionState

Methods

acceptAnswer()

acceptAnswer(sdp): Promise<void>;

Defined in: apps/web-sdk/src/transport/webrtc.ts:107

Parameters

Parameter	Type
sdp	string

Returns

Promise<void>

addRemoteCandidate()

addRemoteCandidate(candidate): Promise<void>;

Defined in: apps/web-sdk/src/transport/webrtc.ts:117

Parameters

Parameter	Type
candidate	RTCIceCandidateInit | null

Returns

Promise<void>

close()

close(): void;

Defined in: apps/web-sdk/src/transport/webrtc.ts:131

Returns

void

start()

start(localStream): Promise<void>;

Defined in: apps/web-sdk/src/transport/webrtc.ts:55

Parameters

Parameter	Type
localStream	MediaStream | null

Returns

Promise<void>

Interfaces

AudioPlayerOptions

Defined in: apps/web-sdk/src/audio/player.ts:19

Assistant audio playback with exact interruption (§21).

The design constraint that shapes everything here: when the gateway says the assistant was interrupted, sound must stop within a few tens of milliseconds. So playback never hands a long buffer to the browser — it schedules short segments back to back on an AudioContext timeline and keeps every live source node so clear() can stop(0) all of them and drop what has not been scheduled yet.

A generation counter guards the boundary: clear() bumps it, and the next frame starts a new one. The gateway stops writing the instant it sends clear and the socket is ordered, so nothing from the interrupted utterance can arrive afterwards — but generation is what makes that assumption explicit and testable rather than implied.

Properties

Property	Type	Description	Defined in
audioContextFactory?	(sampleRate) => AudioContext	Injected in tests; in a browser this is window.AudioContext.	apps/web-sdk/src/audio/player.ts:22
onDrained?	() => void	-	apps/web-sdk/src/audio/player.ts:26
onStarted?	() => void	-	apps/web-sdk/src/audio/player.ts:25
sampleRate	number	-	apps/web-sdk/src/audio/player.ts:20
scheduleAheadSeconds?	number	How far ahead of currentTime to schedule. Lower = tighter barge-in, more risk of gaps.	apps/web-sdk/src/audio/player.ts:24

---

BackoffOptions

Defined in: apps/web-sdk/src/backoff.ts:1

Properties

Property	Type	Description	Defined in
factor?	number	-	apps/web-sdk/src/backoff.ts:4
initialMs?	number	-	apps/web-sdk/src/backoff.ts:2
jitter?	number	0…1. Full jitter at 1.0; a fleet of widgets reconnecting in lockstep is a DDoS.	apps/web-sdk/src/backoff.ts:6
maxAttempts?	number	-	apps/web-sdk/src/backoff.ts:7
maxMs?	number	-	apps/web-sdk/src/backoff.ts:3

---

CallAgentEvents

Defined in: apps/web-sdk/src/client.ts:12

@callagent/web-sdk — browser voice and chat client (§60).

Zero runtime dependencies by design: this ships inside a <script> tag on other people's pages, so every kilobyte is somebody else's Largest Contentful Paint.

Extends

• Record<string, unknown>

Indexable

[key: string]: unknown

Properties

Property	Type	Defined in
call-end	{ callId: string; reason: string; }	apps/web-sdk/src/client.ts:15
call-end.callId	string	apps/web-sdk/src/client.ts:15
call-end.reason	string	apps/web-sdk/src/client.ts:15
call-start	Call	apps/web-sdk/src/client.ts:14
client-tool	ClientToolInvocation	apps/web-sdk/src/client.ts:16
error	CallAgentError	apps/web-sdk/src/client.ts:13

---

CallAgentOptions

Defined in: apps/web-sdk/src/types.ts:83

Properties

Property	Type	Description	Defined in
apiUrl?	string	Control-plane origin, e.g. https://api.callagent.dev.	apps/web-sdk/src/types.ts:89
internals?	{ audioContextFactory?: (sampleRate) => AudioContext; clearTimeoutImpl?: (handle) => void; disableRemoteAudioElement?: boolean; fetchImpl?: { (input, init?): Promise<Response>; (input, init?): Promise<Response>; }; mediaDevices?: MediaDevices; now?: () => number; peerConnectionFactory?: PeerConnectionFactory; random?: () => number; setTimeoutImpl?: (handler, ms) => unknown; webSocketFactory?: WebSocketFactory; }	Test seams. Not part of the supported surface; they exist so the specs are real.	apps/web-sdk/src/types.ts:104
internals.audioContextFactory?	(sampleRate) => AudioContext	-	apps/web-sdk/src/types.ts:108
internals.clearTimeoutImpl?	(handle) => void	-	apps/web-sdk/src/types.ts:113
internals.disableRemoteAudioElement?	boolean	Skips <audio> element creation, for headless environments.	apps/web-sdk/src/types.ts:115
internals.fetchImpl?	{ (input, init?): Promise<Response>; (input, init?): Promise<Response>; }	-	apps/web-sdk/src/types.ts:105
internals.mediaDevices?	MediaDevices	-	apps/web-sdk/src/types.ts:109
internals.now?	() => number	-	apps/web-sdk/src/types.ts:110
internals.peerConnectionFactory?	PeerConnectionFactory	-	apps/web-sdk/src/types.ts:107
internals.random?	() => number	-	apps/web-sdk/src/types.ts:111
internals.setTimeoutImpl?	(handler, ms) => unknown	-	apps/web-sdk/src/types.ts:112
internals.webSocketFactory?	WebSocketFactory	-	apps/web-sdk/src/types.ts:106
publicKey?	string	Public key from Settings → API Keys. A private key is rejected locally.	apps/web-sdk/src/types.ts:85
reconnect?	{ factor?: number; initialMs?: number; jitter?: number; maxAttempts?: number; maxMs?: number; }	-	apps/web-sdk/src/types.ts:96
reconnect.factor?	number	-	apps/web-sdk/src/types.ts:99
reconnect.initialMs?	number	-	apps/web-sdk/src/types.ts:97
reconnect.jitter?	number	-	apps/web-sdk/src/types.ts:100
reconnect.maxAttempts?	number	-	apps/web-sdk/src/types.ts:101
reconnect.maxMs?	number	-	apps/web-sdk/src/types.ts:98
token?	string	A JWT your own backend minted. Mutually exclusive with publicKey.	apps/web-sdk/src/types.ts:87
tokenRefreshSkewMs?	number	Refresh the client JWT this many ms before it expires.	apps/web-sdk/src/types.ts:95
transports?	TransportKind[]	Ordered transport preference. Defaults to WebRTC then WebSocket.	apps/web-sdk/src/types.ts:93
userId?	string	Opaque identifier for the end user; lands in the JWT's user claim.	apps/web-sdk/src/types.ts:91

---

CallEndedEvent

Defined in: apps/web-sdk/src/types.ts:47

Properties

Property	Type	Defined in
callId	string	apps/web-sdk/src/types.ts:48
reason	string	apps/web-sdk/src/types.ts:49
state	| "created" | "queued" | "ringing" | "connecting" | "connected" | "listening" | "user_speaking" | "thinking" | "tool_executing" | "assistant_speaking" | "on_hold" | "transferring" | "human_queue" | "human_connected" | "ending" | "ended" | "failed"	apps/web-sdk/src/types.ts:50

---

CallEvents

Defined in: apps/web-sdk/src/types.ts:68

Extends

• Record<string, unknown>

Indexable

[key: string]: unknown

Properties

Property	Type	Defined in
connected	{ callId: string; sessionId: string; transport: TransportKind; }	apps/web-sdk/src/types.ts:75
connected.callId	string	apps/web-sdk/src/types.ts:75
connected.sessionId	string	apps/web-sdk/src/types.ts:75
connected.transport	TransportKind	apps/web-sdk/src/types.ts:75
ended	CallEndedEvent	apps/web-sdk/src/types.ts:76
error	CallAgentError	apps/web-sdk/src/types.ts:74
message	ConversationMessage	apps/web-sdk/src/types.ts:70
reconnected	{ attempt: number; }	apps/web-sdk/src/types.ts:78
reconnected.attempt	number	apps/web-sdk/src/types.ts:78
reconnecting	ReconnectingEvent	apps/web-sdk/src/types.ts:77
server-error	ServerError	apps/web-sdk/src/types.ts:80
speech-end	SpeechEvent	apps/web-sdk/src/types.ts:72
speech-start	SpeechEvent	apps/web-sdk/src/types.ts:71
state	StateEvent	apps/web-sdk/src/types.ts:73
tool-call	ClientToolInvocation	apps/web-sdk/src/types.ts:79
transcript	TranscriptEvent	apps/web-sdk/src/types.ts:69

---

ClientToolInvocation

Defined in: apps/web-sdk/src/types.ts:57

Properties

Property	Type	Defined in
arguments	Record<string, unknown>	apps/web-sdk/src/types.ts:60
callId	string	apps/web-sdk/src/types.ts:61
name	string	apps/web-sdk/src/types.ts:59
toolCallId	string	apps/web-sdk/src/types.ts:58

---

ConversationMessage

Defined in: apps/web-sdk/src/types.ts:24

Properties

Property	Type	Description	Defined in
at	string	-	apps/web-sdk/src/types.ts:28
content	string	-	apps/web-sdk/src/types.ts:27
id?	string	-	apps/web-sdk/src/types.ts:25
interrupted?	boolean	True when barge-in cut the assistant off mid-sentence (§21).	apps/web-sdk/src/types.ts:30
role	"system" | "user" | "assistant" | "tool" | "operator"	-	apps/web-sdk/src/types.ts:26
toolCallId?	string	-	apps/web-sdk/src/types.ts:31
toolCalls?	{ arguments: Record<string, unknown>; id: string; name: string; }[]	-	apps/web-sdk/src/types.ts:32

---

ReconnectingEvent

Defined in: apps/web-sdk/src/types.ts:53

Properties

Property	Type	Defined in
attempt	number	apps/web-sdk/src/types.ts:54

---

ServerError

Defined in: apps/web-sdk/src/protocol.ts:206

Properties

Property	Type	Defined in
code	string	apps/web-sdk/src/protocol.ts:207
documentationUrl?	string	apps/web-sdk/src/protocol.ts:210
message	string	apps/web-sdk/src/protocol.ts:208
retryable?	boolean	apps/web-sdk/src/protocol.ts:209

---

ServerMessage

Defined in: apps/web-sdk/src/protocol.ts:196

Properties

Property	Type	Defined in
at	string	apps/web-sdk/src/protocol.ts:200
content	string	apps/web-sdk/src/protocol.ts:199
id?	string	apps/web-sdk/src/protocol.ts:197
interrupted?	boolean	apps/web-sdk/src/protocol.ts:201
role	"system" | "user" | "assistant" | "tool" | "operator"	apps/web-sdk/src/protocol.ts:198
toolCallId?	string	apps/web-sdk/src/protocol.ts:202
toolCalls?	{ arguments: Record<string, unknown>; id: string; name: string; }[]	apps/web-sdk/src/protocol.ts:203

---

ServerTranscript

Defined in: apps/web-sdk/src/protocol.ts:187

Properties

Property	Type	Defined in
at	string	apps/web-sdk/src/protocol.ts:191
confidence?	number	apps/web-sdk/src/protocol.ts:192
final	boolean	apps/web-sdk/src/protocol.ts:190
language?	string	apps/web-sdk/src/protocol.ts:193
role	Speaker	apps/web-sdk/src/protocol.ts:188
text	string	apps/web-sdk/src/protocol.ts:189

---

SpeechEvent

Defined in: apps/web-sdk/src/types.ts:35

Properties

Property	Type	Defined in
at	string	apps/web-sdk/src/types.ts:37
speaker	Speaker	apps/web-sdk/src/types.ts:36

---

StartCallOptions

Defined in: apps/web-sdk/src/types.ts:119

Properties

Property	Type	Description	Defined in
assistantId?	string	-	apps/web-sdk/src/types.ts:120
metadata?	Record<string, unknown>	-	apps/web-sdk/src/types.ts:125
microphone?	{ autoGainControl?: boolean; deviceId?: string; echoCancellation?: boolean; noiseSuppression?: boolean; }	-	apps/web-sdk/src/types.ts:128
microphone.autoGainControl?	boolean	-	apps/web-sdk/src/types.ts:132
microphone.deviceId?	string	-	apps/web-sdk/src/types.ts:129
microphone.echoCancellation?	boolean	-	apps/web-sdk/src/types.ts:130
microphone.noiseSuppression?	boolean	-	apps/web-sdk/src/types.ts:131
mode?	SessionMode	chat runs the same session without a microphone or speaker.	apps/web-sdk/src/types.ts:123
squadId?	string	-	apps/web-sdk/src/types.ts:121
transports?	TransportKind[]	Overrides the client-level transport preference for this call only.	apps/web-sdk/src/types.ts:127
variables?	Record<string, unknown>	-	apps/web-sdk/src/types.ts:124

---

StateEvent

Defined in: apps/web-sdk/src/types.ts:40

Properties

Property	Type	Defined in
at	string	apps/web-sdk/src/types.ts:43
previous	| "created" | "queued" | "ringing" | "connecting" | "connected" | "listening" | "user_speaking" | "thinking" | "tool_executing" | "assistant_speaking" | "on_hold" | "transferring" | "human_queue" | "human_connected" | "ending" | "ended" | "failed"	apps/web-sdk/src/types.ts:42
reason?	string	apps/web-sdk/src/types.ts:44
state	| "created" | "queued" | "ringing" | "connecting" | "connected" | "listening" | "user_speaking" | "thinking" | "tool_executing" | "assistant_speaking" | "on_hold" | "transferring" | "human_queue" | "human_connected" | "ending" | "ended" | "failed"	apps/web-sdk/src/types.ts:41

---

TokenManagerOptions

Defined in: apps/web-sdk/src/auth.ts:139

Properties

Property	Type	Description	Defined in
apiUrl	string	-	apps/web-sdk/src/auth.ts:140
assistantId?	string	-	apps/web-sdk/src/auth.ts:144
clearTimeoutImpl?	(handle) => void	-	apps/web-sdk/src/auth.ts:149
fetchImpl?	{ (input, init?): Promise<Response>; (input, init?): Promise<Response>; }	-	apps/web-sdk/src/auth.ts:146
now?	() => number	-	apps/web-sdk/src/auth.ts:147
onError?	(error) => void	-	apps/web-sdk/src/auth.ts:153
onToken?	(token) => void	-	apps/web-sdk/src/auth.ts:152
publicKey?	string	-	apps/web-sdk/src/auth.ts:141
refreshSkewMs?	number	Refresh this far ahead of exp.	apps/web-sdk/src/auth.ts:151
setTimeoutImpl?	(handler, ms) => unknown	-	apps/web-sdk/src/auth.ts:148
token?	string	A token the host page minted itself; the SDK then never calls the exchange.	apps/web-sdk/src/auth.ts:143
userId?	string	-	apps/web-sdk/src/auth.ts:145

---

TranscriptEvent

Defined in: apps/web-sdk/src/types.ts:13

Properties

Property	Type	Description	Defined in
at	string	-	apps/web-sdk/src/types.ts:19
confidence?	number	-	apps/web-sdk/src/types.ts:20
final	boolean	false while the transcriber is still revising the utterance.	apps/web-sdk/src/types.ts:18
language?	string	-	apps/web-sdk/src/types.ts:21
speaker	Speaker	Who spoke. Partial results are emitted for both sides as they arrive.	apps/web-sdk/src/types.ts:15
text	string	-	apps/web-sdk/src/types.ts:16

---

WebSocketLike

Defined in: apps/web-sdk/src/transport/socket.ts:16

Properties

Property	Modifier	Type	Defined in
binaryType	public	string	apps/web-sdk/src/transport/socket.ts:18
onclose	public	((event) => void) | null	apps/web-sdk/src/transport/socket.ts:22
onerror	public	((event) => void) | null	apps/web-sdk/src/transport/socket.ts:23
onmessage	public	((event) => void) | null	apps/web-sdk/src/transport/socket.ts:24
onopen	public	((event) => void) | null	apps/web-sdk/src/transport/socket.ts:21
readyState	readonly	number	apps/web-sdk/src/transport/socket.ts:17

Methods

close()

close(code?, reason?): void;

Defined in: apps/web-sdk/src/transport/socket.ts:20

Parameters

Parameter	Type
code?	number
reason?	string

Returns

void

send()

send(data): void;

Defined in: apps/web-sdk/src/transport/socket.ts:19

Parameters

Parameter	Type
data	string | ArrayBufferLike | Blob | ArrayBufferView<ArrayBufferLike>

Returns

void

Type Aliases

CallAgentErrorCode

type CallAgentErrorCode = 
  | "invalid_public_key"
  | "private_key_rejected"
  | "auth_failed"
  | "token_expired"
  | "microphone_denied"
  | "microphone_unavailable"
  | "audio_unsupported"
  | "transport_failed"
  | "transport_closed"
  | "protocol_mismatch"
  | "call_start_failed"
  | "call_ended"
  | "client_tool_failed"
  | "not_connected"
  | "aborted"
  | "server_error";

Defined in: apps/web-sdk/src/errors.ts:9

Error codes the SDK raises. Kept as a closed union so host pages can branch on error.code instead of matching on message text (CONVENTIONS.md §4).

The server's own codes come from CallAgentErrorCode in @callagent/contracts and arrive verbatim on server.error frames; they are surfaced as code without being remapped, so a support ticket quotes the same string both planes log.

---

CallState

type CallState = typeof CALL_STATES[number];

Defined in: apps/web-sdk/src/protocol.ts:60

---

ClientFrame

type ClientFrame = 
  | {
  assistantId?: string;
  callId: string;
  clientTools?: string[];
  event: "start";
  mediaToken?: string;
  metadata?: Record<string, unknown>;
  mode: SessionMode;
  organizationId?: string;
  protocolVersion: number;
  sampleRate: number;
  sdkVersion: string;
  variables?: Record<string, string>;
}
  | {
  event: "auth";
  token: string;
}
  | {
  event: "offer";
  sdp: string;
}
  | {
  candidate: RTCIceCandidateInit | null;
  event: "ice";
}
  | {
  event: "mute";
  muted: boolean;
}
  | {
  content: string;
  event: "text";
}
  | {
  digit: string;
  event: "dtmf";
}
  | {
  event: "mark";
  name: string;
}
  | {
  error?: string;
  event: "tool_result";
  result?: unknown;
  toolCallId: string;
}
  | {
  event: "stop";
  reason?: string;
};

Defined in: apps/web-sdk/src/protocol.ts:156

The gateway dispatches on event, ignores unknown ones, and reads only the keys it knows — so extra fields on start are forward-compatible, not a protocol break.

Union Members

Type Literal

{
  assistantId?: string;
  callId: string;
  clientTools?: string[];
  event: "start";
  mediaToken?: string;
  metadata?: Record<string, unknown>;
  mode: SessionMode;
  organizationId?: string;
  protocolVersion: number;
  sampleRate: number;
  sdkVersion: string;
  variables?: Record<string, string>;
}

Name	Type	Description	Defined in
assistantId?	string	-	apps/web-sdk/src/protocol.ts:160
callId	string	-	apps/web-sdk/src/protocol.ts:159
clientTools?	string[]	-	apps/web-sdk/src/protocol.ts:170
event	"start"	-	apps/web-sdk/src/protocol.ts:158
mediaToken?	string	-	apps/web-sdk/src/protocol.ts:169
metadata?	Record<string, unknown>	-	apps/web-sdk/src/protocol.ts:171
mode	SessionMode	-	apps/web-sdk/src/protocol.ts:168
organizationId?	string	-	apps/web-sdk/src/protocol.ts:161
protocolVersion	number	Fields below are SDK additions; the current gateway ignores them.	apps/web-sdk/src/protocol.ts:166
sampleRate	number	Rate of the PCM we will send. The gateway echoes a format frame back.	apps/web-sdk/src/protocol.ts:163
sdkVersion	string	-	apps/web-sdk/src/protocol.ts:167
variables?	Record<string, string>	-	apps/web-sdk/src/protocol.ts:164

---

Type Literal

{
  event: "auth";
  token: string;
}

---

Type Literal

{
  event: "offer";
  sdp: string;
}

---

Type Literal

{
  candidate: RTCIceCandidateInit | null;
  event: "ice";
}

---

Type Literal

{
  event: "mute";
  muted: boolean;
}

---

Type Literal

{
  content: string;
  event: "text";
}

---

Type Literal

{
  digit: string;
  event: "dtmf";
}

---

Type Literal

{
  event: "mark";
  name: string;
}

---

Type Literal

{
  error?: string;
  event: "tool_result";
  result?: unknown;
  toolCallId: string;
}

---

Type Literal

{
  event: "stop";
  reason?: string;
}

---

ClientToolHandler

type ClientToolHandler = (invocation) => unknown | Promise<unknown>;

Defined in: apps/web-sdk/src/types.ts:64

Parameters

Parameter	Type
invocation	ClientToolInvocation

Returns

unknown | Promise<unknown>

---

MessageRole

type MessageRole = typeof MESSAGE_ROLES[number];

Defined in: apps/web-sdk/src/protocol.ts:72

---

ServerEventName

type ServerEventName = ServerFrame["event"];

Defined in: apps/web-sdk/src/protocol.ts:251

---

ServerFrame

type ServerFrame = 
  | {
  channels: number;
  encoding: "pcm_s16le";
  event: "format";
  sampleRate: number;
}
  | {
  event: "clear";
}
  | {
  event: "mark";
  name: string;
}
  | {
  event: "stop";
  reason?: string;
}
  | {
  event: "answer";
  sdp: string;
}
  | {
  candidate: RTCIceCandidateInit | null;
  event: "ice";
}
  | {
  callId: string;
  event: "ready";
  protocolVersion?: number;
  sampleRate?: number;
  sessionId?: string;
  state?: CallState;
  transport?: TransportKind;
}
  | {
  at?: string;
  event: "state";
  reason?: string;
  state: CallState;
}
  | {
  event: "transcript";
  transcript: ServerTranscript;
}
  | {
  event: "message";
  message: ServerMessage;
}
  | {
  at?: string;
  event: "speech";
  phase: "start" | "end";
  speaker: Speaker;
}
  | {
  arguments: Record<string, unknown>;
  event: "tool_call";
  name: string;
  timeoutMs?: number;
  toolCallId: string;
}
  | {
  error: ServerError;
  event: "error";
}
  | {
  event: "ended";
  reason: string;
  state?: CallState;
};

Defined in: apps/web-sdk/src/protocol.ts:213

Union Members

Type Literal

{
  channels: number;
  encoding: "pcm_s16le";
  event: "format";
  sampleRate: number;
}

Implemented by the gateway today: the negotiated PCM format.

---

Type Literal

{
  event: "clear";
}

Barge-in (§21). Drop everything queued and stop the speaker now. Playing to the end of the buffer here is the single most noticeable voice-UX bug there is. The socket is ordered, so any audio frame after this one is the next utterance.

---

Type Literal

{
  event: "mark";
  name: string;
}

---

Type Literal

{
  event: "stop";
  reason?: string;
}

---

Type Literal

{
  event: "answer";
  sdp: string;
}

Signalling, forwarded verbatim by the gateway; no ICE agent runs there yet.

---

Type Literal

{
  candidate: RTCIceCandidateInit | null;
  event: "ice";
}

---

Type Literal

{
  callId: string;
  event: "ready";
  protocolVersion?: number;
  sampleRate?: number;
  sessionId?: string;
  state?: CallState;
  transport?: TransportKind;
}

Session events the gateway still has to emit — see the file header.

---

Type Literal

{
  at?: string;
  event: "state";
  reason?: string;
  state: CallState;
}

---

Type Literal

{
  event: "transcript";
  transcript: ServerTranscript;
}

---

Type Literal

{
  event: "message";
  message: ServerMessage;
}

---

Type Literal

{
  at?: string;
  event: "speech";
  phase: "start" | "end";
  speaker: Speaker;
}

---

Type Literal

{
  arguments: Record<string, unknown>;
  event: "tool_call";
  name: string;
  timeoutMs?: number;
  toolCallId: string;
}

---

Type Literal

{
  error: ServerError;
  event: "error";
}

---

Type Literal

{
  event: "ended";
  reason: string;
  state?: CallState;
}

---

SessionMode

type SessionMode = "voice" | "chat";

Defined in: apps/web-sdk/src/protocol.ts:76

---

SocketState

type SocketState = "idle" | "connecting" | "open" | "reconnecting" | "closed";

Defined in: apps/web-sdk/src/transport/socket.ts:14

The session control channel.

One WebSocket carries JSON control frames in both directions and, when WebRTC is unavailable, binary PCM as well. It owns reconnection: the call object above it sees open / close / frame and does not care how many sockets it took.

---

Speaker

type Speaker = "user" | "assistant";

Defined in: apps/web-sdk/src/protocol.ts:74

---

TransportKind

type TransportKind = "webrtc" | "websocket" | "chat";

Defined in: apps/web-sdk/src/protocol.ts:79

How the client is carrying media. chat means there is no media at all.

Variables

CALL_STATES

const CALL_STATES: readonly ["created", "queued", "ringing", "connecting", "connected", "listening", "user_speaking", "thinking", "tool_executing", "assistant_speaking", "on_hold", "transferring", "human_queue", "human_connected", "ending", "ended", "failed"];

Defined in: apps/web-sdk/src/protocol.ts:40

Mirrors CallState in @callagent/contracts / App\Enums\CallState. protocol.contract.test.ts proves the two lists are identical.

---

CLIENT_ROUTES

const CLIENT_ROUTES: Readonly<{
  token: "/api/v1/client-tokens";
  webCall: "/api/v1/client/calls";
}>;

Defined in: apps/web-sdk/src/protocol.ts:85

---

MESSAGE_ROLES

const MESSAGE_ROLES: readonly ["system", "user", "assistant", "tool", "operator"];

Defined in: apps/web-sdk/src/protocol.ts:71

Mirrors CallMessageSchema.role in @callagent/contracts.

---

PROTOCOL_VERSION

const PROTOCOL_VERSION: 1 = 1;

Defined in: apps/web-sdk/src/protocol.ts:34

The browser <-> Voice Gateway session protocol.

ALIGNED WITH THE GATEWAY'S WebRtcTransport

apps/voice-gateway/src/transport/webrtc.ts (A2) already implements the media half of this: a WebSocket carrying raw PCM16 frames as binary messages and a small { "event": "..." } JSON control channel. This file speaks exactly that wire format rather than inventing a second one, and adds the conversation events the SDK needs (transcripts, messages, state, client tools) as further event values.

What the gateway implements today: start, dtmf, mark, stop, offer/answer/ ice inbound; format, clear, mark, stop outbound; binary PCM both ways.

What the gateway still has to add for a complete session (raised as decision D-A14-001 and BLOCKERS #16): ready, state, transcript, message, speech, tool_call, error, ended outbound; mute, text, tool_result, auth inbound. Unknown inbound events are ignored on both sides, so the SDK works against the current gateway for audio and barge-in and lights up the rest as it lands.

TODO(A1): these shapes belong in packages/contracts/src/web-session.ts as zod schemas, re-exported from here.

WHY THE SDK DOES NOT IMPORT ZOD AT RUNTIME

The widget is a <script src=...> drop-in on other people's marketing pages; a validation library is a large fraction of the byte budget. So the SDK ships zero runtime dependencies and validates inbound frames with the narrow guards below. The enums it does share with the control plane (CallState, message roles) are asserted against @callagent/contracts in protocol.contract.test.ts, so a divergence fails the build rather than silently accepting an unknown state.

---

VERSION

const VERSION: "0.1.0" = '0.1.0';

Defined in: apps/web-sdk/src/index.ts:76

Functions

assertPublicKey()

function assertPublicKey(key): string;

Defined in: apps/web-sdk/src/auth.ts:79

Parameters

Parameter	Type
key	string

Returns

string

---

decodeAudioFrame()

function decodeAudioFrame(buffer): Int16Array<ArrayBufferLike> | null;

Defined in: apps/web-sdk/src/protocol.ts:267

Parameters

Parameter	Type
buffer	ArrayBuffer

Returns

Int16Array<ArrayBufferLike> | null

---

decodeJwt()

function decodeJwt(token): DecodedJwt;

Defined in: apps/web-sdk/src/auth.ts:110

Reads exp out of a JWT without verifying it. Verification is the server's job — the client only needs to know when to ask for a new one, and a forged exp can at worst make the SDK refresh too eagerly.

Parameters

Parameter	Type
token	string

Returns

DecodedJwt

---

describeMediaError()

function describeMediaError(error): {
  code: MicrophoneErrorCode;
  message: string;
};

Defined in: apps/web-sdk/src/audio/microphone.ts:31

Parameters

Parameter	Type
error	unknown

Returns

{
  code: MicrophoneErrorCode;
  message: string;
}

Name	Type	Defined in
code	MicrophoneErrorCode	apps/web-sdk/src/audio/microphone.ts:32
message	string	apps/web-sdk/src/audio/microphone.ts:33

---

encodeAudioFrame()

function encodeAudioFrame(pcm): ArrayBuffer;

Defined in: apps/web-sdk/src/protocol.ts:263

Binary messages are raw little-endian PCM16 mono in both directions, matching WebRtcTransport. There is no frame header: the gateway stops writing the moment it sends clear, and the socket is ordered, so the client can safely treat every frame that arrives after a clear as belonging to the next utterance.

Parameters

Parameter	Type
pcm	Int16Array

Returns

ArrayBuffer

---

floatToPcm16()

function floatToPcm16(input): Int16Array;

Defined in: apps/web-sdk/src/audio/pcm.ts:10

PCM helpers.

Everything on the socket is signed 16-bit little-endian mono, because that is what every STT vendor and every telephony codec path in this platform already speaks (packages/audio). The browser gives us float32 at the device rate, so the two conversions below are the only audio maths the SDK does.

Parameters

Parameter	Type
input	Float32Array

Returns

Int16Array

---

inspectPublicKey()

function inspectPublicKey(key): PublicKeyCheck;

Defined in: apps/web-sdk/src/auth.ts:41

Parameters

Parameter	Type
key	string

Returns

PublicKeyCheck

---

isCallState()

function isCallState(value): value is "created" | "queued" | "ringing" | "connecting" | "connected" | "listening" | "user_speaking" | "thinking" | "tool_executing" | "assistant_speaking" | "on_hold" | "transferring" | "human_queue" | "human_connected" | "ending" | "ended" | "failed";

Defined in: apps/web-sdk/src/protocol.ts:64

Parameters

Parameter	Type
value	unknown

Returns

value is "created" | "queued" | "ringing" | "connecting" | "connected" | "listening" | "user_speaking" | "thinking" | "tool_executing" | "assistant_speaking" | "on_hold" | "transferring" | "human_queue" | "human_connected" | "ending" | "ended" | "failed"

---

isSecureContextForMedia()

function isSecureContextForMedia(): boolean;

Defined in: apps/web-sdk/src/audio/microphone.ts:90

Returns

boolean

---

looksLikePublicKey()

function looksLikePublicKey(key): boolean;

Defined in: apps/web-sdk/src/auth.ts:91

Parameters

Parameter	Type
key	string

Returns

boolean

---

parseServerFrame()

function parseServerFrame(raw): ServerFrame | null;

Defined in: apps/web-sdk/src/protocol.ts:305

Structural validation of one inbound control frame.

Deliberately permissive about extra fields (the gateway may add some without a client release) and strict about the fields we branch on. An unknown event is not an error — it is a newer gateway — so it returns null and the caller ignores it.

Parameters

Parameter	Type
raw	unknown

Returns

ServerFrame | null

---

pcm16ToFloat()

function pcm16ToFloat(input): Float32Array<ArrayBuffer>;

Defined in: apps/web-sdk/src/audio/pcm.ts:21

Parameters

Parameter	Type
input	Int16Array

Returns

Float32Array<ArrayBuffer>

---

queryMicrophonePermission()

function queryMicrophonePermission(): Promise<PermissionState | "unsupported">;

Defined in: apps/web-sdk/src/audio/microphone.ts:77

navigator.permissions is not implemented for microphone everywhere, so this is best-effort: it lets the widget show "allow the microphone" before the browser prompt where it can, and stays quiet where it cannot.

Returns

Promise<PermissionState | "unsupported">

---

resampleLinear()

function resampleLinear(
   input, 
   fromRate, 
   toRate
): Float32Array;

Defined in: apps/web-sdk/src/audio/pcm.ts:37

Linear resampling.

Not as good as a windowed-sinc filter, but it runs on the audio thread budget and the far end is a speech model, not a mastering engineer. packages/audio owns the high-quality path for server-side media; this is the browser's cheap equivalent.

Parameters

Parameter	Type
input	Float32Array
fromRate	number
toRate	number

Returns

Float32Array

---

supportsWebAudio()

function supportsWebAudio(scope?): boolean;

Defined in: apps/web-sdk/src/transport/support.ts:28

Parameters

Parameter	Type	Default value
scope	typeof globalThis	globalThis

Returns

boolean

---

supportsWebRtc()

function supportsWebRtc(scope?): boolean;

Defined in: apps/web-sdk/src/transport/support.ts:11

Transport selection (§60: "use WebRTC where possible").

WebRTC is preferred because the browser then owns jitter buffering, packet loss concealment and Opus encoding — all things a WebSocket PCM stream has to do badly in JavaScript. The WebSocket path exists because corporate networks block UDP and some embedded webviews ship without RTCPeerConnection at all.

Parameters

Parameter	Type	Default value
scope	typeof globalThis	globalThis

Returns

boolean

---

supportsWebSocket()

function supportsWebSocket(scope?): boolean;

Defined in: apps/web-sdk/src/transport/support.ts:24

Parameters

Parameter	Type	Default value
scope	typeof globalThis	globalThis

Returns

boolean

---

transportPreference()

function transportPreference(options): TransportKind[];

Defined in: apps/web-sdk/src/transport/support.ts:41

Ordered list offered to the gateway; it picks the first it also supports.

Parameters

Parameter	Type
options	TransportPreferenceOptions

Returns

TransportKind[]