Vowel Client Library

Core reference for @vowel.to/client. Framework-specific skills (vowel-react, vowel-vanilla, vowel-webcomponent) assume you have read this file first.

What is Vowel?

vowel (lowercase) is a SaaS platform that adds AI-powered voice agents to web applications. The @vowel.to/client package provides real-time voice interaction via vowel-prime, Gemini Live API, or OpenAI Realtime API. Key capabilities: smart navigation (voice-controlled routing), custom actions (business logic via voice), and optional page automation (DOM interaction).

Connection Paradigms

The client supports these top-level connection models:

1. Hosted / platform token issuer — pass apiKey (preferred, vkey_* format) or legacy appId. Optionally set convexUrl or tokenEndpoint to override the default hosted URL.
2. Token-based flow — tokenProvider callback or pre-issued voiceConfig.token for server-managed sessions.
3. Direct WebSocket — raw voiceConfig.token pointing to a Vowel Engine WebSocket. See docs/recipes/connection-paradigms.md for advanced patterns (sidecar, trusted server, fixed API keys).

apiKey and appId are aliases for the token issuer identifier. Prefer apiKey in new code.

Installation