Docs API reference

API reference

The public controller, options, methods, callbacks, types, and audio helpers, with the defaults that matter.

Entry points

Public exports
Export	Kind	Purpose
`useConversation(options?)`	Controller	Creates a controller and registers an `$effect` teardown.
`createConversation(options?)`	Function	Creates a controller without a lifecycle effect. Call `destroy()` yourself.
`ConversationController`	Class	The reactive controller. Accepts the same options as the factory functions.
`ConversationProvider`	Component	Shares a controller through Svelte context.
`getConversationContext()`	Function	Reads the controller from the nearest provider.
`setConversationContext(controller)`	Function	Supplies a controller to a component subtree.
`useConversationClientTool(name, handler)`	Controller	Registers a component scoped tool on the provider controller.
`AudioManager`	Class	Framework-agnostic capture, playback, and device engine.
`AudioVisualizer`	Component	Canvas view of the live spectra.
`ConversationWidget`	Component	Complete conversation surface.

Controller state

These fields are Svelte state or derived values. isTextOnly is a getter. Treat them as read-only from your component and change state through the methods below. The full behavior for each group is covered in Sessions and Audio.

Fields
Field	Type
`status`	`ConversationStatus`
`mode`	`ConversationMode`
`canStart`	`boolean`
`isSpeaking`	`boolean`
`isListening`	`boolean`
`isUserSpeaking`	`boolean`
`isMuted`	`boolean`
`isTextOnly`	`boolean` (getter)
`volume`	`number`
`inputVolume`	`number`
`outputVolume`	`number`
`transcripts`	`TranscriptMessage[]`
`messageCount`	`number`
`message`	`TranscriptMessage \| null`
`error`	`string \| null`
`errorCode`	`ConversationErrorCode \| null`
`latency`	`number \| null`
`latencyHistory`	`number[]`
`conversationId`	`string \| null`
`inputAudioFormat`	`AudioFormatId \| null`
`outputAudioFormat`	`AudioFormatId \| null`
`queueStatus`	`QueueStatus \| null`
`interruptions`	`number`
`canSendFeedback`	`boolean`
`vadScore`	`number`
`contextUsage`	`ContextUsageServerEvent['context_usage_event'] \| null`
`outputGain`	`number`
`inputDeviceId`	`string \| null`
`outputDeviceId`	`string \| null`

Methods

Controller methods
Method	Returns	Notes
`startConversation(target?, options?)`	`Promise<void>`	Opens the session. Connection and audio failures populate `error`. Target can be an agent id, a `ws://` or `wss://` URL (http and https are normalized), or omitted.
`stopConversation()`	`void`	Ends the session and preserves the transcript.
`endSession()`	`void`	Alias for `stopConversation()`.
`toggleMute()`	`void`	Flips the outgoing mute state.
`setMuted(muted)`	`void`	Sets the outgoing mute state explicitly.
`setVolume(volume)`	`void`	Accepts a number or `{ volume: number }`. Clamps to 0 through 1.
`getInputVolume()`	`number`	Latest normalized microphone level.
`getOutputVolume()`	`number`	Latest normalized playback level.
`getInputFrequencyData(target?)`	`Uint8Array`	512 bins. Reuse a buffer for animation frames.
`getOutputFrequencyData(target?)`	`Uint8Array`	512 bins from agent playback.
`getInputByteFrequencyData(target?)`	`Uint8Array`	Alias for `getInputFrequencyData`.
`getOutputByteFrequencyData(target?)`	`Uint8Array`	Alias for `getOutputFrequencyData`.
`getId()`	`string \| null`	Current conversation id.
`sendFeedback(like, eventId?)`	`boolean`	Defaults to the latest agent response. Requires `canSendFeedback`.
`sendUserActivity()`	`boolean`	Throttled to one frame per second.
`sendMCPToolApprovalResult(toolCallId, approved)`	`boolean`	Manual approval path. Sends at most one result per call.
`registerClientTool(name, handler)`	`() => void`	Returns an unregister function.
`changeInputDevice(deviceId?)`	`Promise<boolean>`	Requires an active voice session.
`changeOutputDevice(deviceId?)`	`Promise<boolean>`	Requires an active voice session and browser output routing.
`listAudioDevices()`	`Promise<AudioDeviceInfo[]>`	Wraps `enumerateDevices`.
`sendContextualUpdate(text, contextId?)`	`boolean`	Non-interrupting context for the next turn.
`sendUserMessage(text)`	`boolean`	Typed user turn over the same socket.
`clearTranscripts()`	`void`	Local only. Does not affect the server conversation.
`clearError()`	`void`	Clears `error` and `errorCode`.
`destroy()`	`void`	Releases its resources. Idempotent.

Options

Every field is optional. The same object is accepted by useConversation, createConversation, the ConversationController constructor, and ConversationProvider.

ConversationOptions
Option	Type	Default
`agentId`	`string`	None
`signedUrl`	`string`	None
`signedUrlEndpoint`	`string`	`'/api/signed-url'`
`origin`	`string`	Origin for `serverLocation`
`serverLocation`	`'us' \| 'eu-residency' \| 'in-residency' \| 'global'`	`'us'`
`connectionType`	`'websocket' \| 'webrtc'`	`'websocket'`
`textOnly`	`boolean`	`false`
`dynamicVariables`	`Record<string, string \| number \| boolean>`	None
`userId`	`string`	None
`overrides`	`ConversationConfigOverride`	None
`clientTools`	`Record<string, ClientToolHandler>`	None
`onClientToolCall`	`(call) => string \| object \| array \| Promise`	None
`inputDeviceId`	`string`	System default
`outputDeviceId`	`string`	System default
`micMuted`	`boolean`	`false`
`outputVolume`	`number`	`1`
`inputChunkDurationMs`	`number`	`100`, clamped to 50 through 250
`interruptOnUserSpeech`	`boolean`	`true`
`vadThreshold`	`number`	`0.075`
`maxTranscripts`	`number`	`250`, minimum 20
`resetTranscriptsOnStart`	`boolean`	`true`
`autoCleanup`	`boolean`	`true` for `useConversation`
`debug`	`boolean`	`false`

Callbacks

Session and media callbacks
Option	Payload	When
`onStatusChange`	`ConversationStatus`	Connection state changes.
`onConnect`	`{ conversationId: string }`	Metadata negotiation completes.
`onDisconnect`	`DisconnectDetails`	The socket closes, including a client stop.
`onModeChange`	`ConversationMode`	The derived mode label changes.
`onTranscript`	`TranscriptMessage`	An entry is created or updated.
`onMessage`	`TranscriptMessage`	Alias for `onTranscript`.
`onError`	`ConversationError`	A failure is published.
`onLatency`	`number`	A time-to-first-audio measurement lands.
`onInterruption`	None	Local or server barge-in is counted.
`onCanSendFeedbackChange`	`boolean`	Feedback availability changes.
`onVadScore`	`number`	The server reports a voice activity score.
`onAudio`	`string`	An agent audio chunk arrives before playback.
`onAudioAlignment`	`AudioAlignment`	A chunk includes character timing.
`onPing`	`{ event_id, ping_ms? }`	A keep-alive arrives. The reply is automatic.
`onConversationMetadata`	`ConversationInitiationMetadata`	The initiation metadata arrives.
`onConversationId`	`string`	The conversation id becomes available.

Protocol and tool callbacks
Option	Payload	When
`onAgentChatResponsePart`	Streaming part	A start, delta, or stop part arrives.
`onAgentResponseCorrection`	Correction payload	The server corrects a response.
`onAgentResponseComplete`	`number`	An agent response finishes.
`onAgentResponseMetadata`	Metadata payload	Per-response metadata arrives.
`onContextUsage`	Context usage	The LLM context window is reported.
`onMCPToolCall`	MCP call	An MCP call changes state.
`onMCPConnectionStatus`	Integration status	MCP connection state changes.
`onMCPToolApprovalRequest`	`(call, { signal }) => boolean`	A call needs approval.
`onAgentToolRequest`	Agent tool request	The agent starts a server side tool.
`onAgentToolResponse`	Tool response	An agent tool finishes.
`onGuardrailTriggered`	Guardrail event	A guardrail fires.
`onUnhandledClientToolCall`	Client call	No named or fallback handler exists.
`onIncomingEvent`	`ServerEvent`	Every parsed server event.
`onOutgoingEvent`	`ClientEvent`	Every sent client frame.
`onDebug`	`DebugEvent`	Structured diagnostics when `debug` is on.

Types

Public types
Type	Shape
`AudioFormat`	`{ encoding: 'pcm' \| 'ulaw'; sampleRate: number; channels: 1 }`
`ConversationStatus`	`'disconnected' \| 'connecting' \| 'connected'`
`ConversationMode`	`'disconnected' \| 'connecting' \| 'ready' \| 'listening' \| 'speaking'`
`TranscriptMessage`	Stable id, role, text, `isFinal`, timestamp, optional event and response ids, attachments.
`StartConversationOptions`	`{ signed?: boolean; textOnly?: boolean }`
`DisconnectDetails`	`{ code: number; reason: string; expected: boolean }`
`ConversationError`	`Error` with `code` and optional `cause`.
`ConversationErrorCode`	Union of the 14 stable failure categories.
`ClientToolHandler`	`(parameters, call) => unknown \| Promise<unknown>`
`MCPToolApprovalHandler`	`(call, context) => boolean \| Promise<boolean>`
`AudioDeviceInfo`	`{ deviceId, kind, label, groupId }`
`DebugEvent`	`{ kind, message, data? }`

The complete protocol unions, including every server and client event, are exported from svelte-elevenlabs/types. They mirror the ConvAI WebSocket protocol and are safe to import from Node code.

Audio helpers

Exports from svelte-elevenlabs/audio
Export	Signature	Purpose
`parseAudioFormat`	`(format: string) => AudioFormat`	Validate and parse a format id.
`resampleLinear`	`(samples, sourceRate, targetRate) => Float32Array`	Linear sample rate conversion.
`encodePcm16Base64`	`(samples: Float32Array) => string`	Encode mono float samples for `user_audio_chunk`.
`decodePcm16`	`(base64: string) => Float32Array`	Decode base64 PCM16 little-endian.
`decodeUlaw`	`(bytes: Uint8Array) => Float32Array`	Decode 8-bit G.711 µ-law.
`decodeAudioChunk`	`(base64, format) => Float32Array`	Decode with the negotiated format.
`listAudioDevices`	`() => Promise<AudioDeviceInfo[]>`	Enumerate browser devices.
`AudioManager`	Class	Capture, playback, devices, analysers, and cleanup. Use `AudioManager.isSupported()` for a capability check.
`AudioManagerError`	Class	Error with a stable audio error code and optional cause.

The full list of failure categories, with causes and fixes, lives in Troubleshooting.

Edit this page on GitHub