Class: Vowel

Defined in: lib/vowel/core/VowelClient.ts:80

Main Vowel client class

Example

// vowel.client.ts
import { Vowel } from '@/lib/vowel';
import { tanstackRouterAdapter } from '@/lib/vowel/adapters';
import { router } from './router';

export const vowel = new Vowel({
  apiKey: 'vkey_public_xxx',
  router: tanstackRouterAdapter(router),
  routes: [
    { path: '/products', description: 'Browse products' },
    { path: '/cart', description: 'View cart' }
  ]
});

// Register custom actions
vowel.registerAction('searchProducts', {
  description: 'Search for products',
  parameters: {
    query: { type: 'string', description: 'Search query' }
  }
}, async (params) => {
  await searchProducts(params.query);
});

Constructors

Constructor

new Vowel(config): Vowel;

Defined in: lib/vowel/core/VowelClient.ts:105

Parameters

Parameter	Type
`config`	`VowelClientConfig`

Returns

Vowel

Accessors

appId

Get Signature

get appId(): string | undefined;

Defined in: lib/vowel/core/VowelClient.ts:867

Get app ID

Returns

string | undefined

apiKey

Get Signature

get apiKey(): string | undefined;

Defined in: lib/vowel/core/VowelClient.ts:874

Get token issuer identifier alias

Returns

string | undefined

router

Get Signature

get router(): RouterAdapter | undefined;

Defined in: lib/vowel/core/VowelClient.ts:882

Get router adapter (legacy)

Deprecated

Use navigationAdapter property instead

Returns

RouterAdapter | undefined

routes

Get Signature

get routes(): VowelRoute[];

Defined in: lib/vowel/core/VowelClient.ts:889

Get configured routes

Returns

VowelRoute[]

session

Get Signature

get session(): SessionManager;

Defined in: lib/vowel/core/VowelClient.ts:896

Get session manager (for internal use by action handlers)

Returns

SessionManager

voiceConfig

Get Signature

get voiceConfig(): VowelVoiceConfig | undefined;

Defined in: lib/vowel/core/VowelClient.ts:903

Get voice configuration

Returns

VowelVoiceConfig | undefined

systemInstructionOverride

Get Signature

get systemInstructionOverride(): string | undefined;

Defined in: lib/vowel/core/VowelClient.ts:910

Get system instruction override

Returns

string | undefined

state

Get Signature

get state(): VoiceSessionState;

Defined in: lib/vowel/core/VowelClient.ts:917

Get current session state

Returns

VoiceSessionState

floatingCursor

Get Signature

get floatingCursor(): FloatingCursorManager | undefined;

Defined in: lib/vowel/core/VowelClient.ts:945

Get floating cursor manager (if enabled)

Returns

FloatingCursorManager | undefined

Methods

isUserSpeaking()

isUserSpeaking(): boolean;

Defined in: lib/vowel/core/VowelClient.ts:924

Check if user is currently speaking (client-side VAD)

Returns

boolean

isAIThinking()

isAIThinking(): boolean;

Defined in: lib/vowel/core/VowelClient.ts:931

Check if AI is currently thinking/processing

Returns

boolean

isAISpeaking()

isAISpeaking(): boolean;

Defined in: lib/vowel/core/VowelClient.ts:938

Check if AI is currently speaking

Returns

boolean

registerAction()

registerAction<T>(
   name, 
   definition, 
   handler): void;

Defined in: lib/vowel/core/VowelClient.ts:992

⚠️ CRITICAL: Actions MUST be registered BEFORE calling startSession()! Actions registered after the session starts will have NO EFFECT. Tool definitions are sent to the server during session initialization.

Type Parameters

Type Parameter	Default type
`T`	`any`

Parameters

Parameter	Type	Description
`name`	`string`	Action name (will be used as tool name)
`definition`	`VowelAction`	Action definition with parameters
`handler`	`ActionHandler`<`T`>	Function to execute when action is called

Returns

void

Example

// ✅ CORRECT - Register before starting session
vowel.registerAction('addToCart', {
  description: 'Add product to shopping cart',
  parameters: {
    productId: {
      type: 'string',
      description: 'Product ID'
    },
    quantity: {
      type: 'number',
      description: 'Quantity',
      optional: true
    }
  }
}, async ({ productId, quantity = 1 }) => {
  await addToCart(productId, quantity);
});

// Then start the session
await vowel.startSession();

// ❌ WRONG - Too late!
await vowel.startSession();
vowel.registerAction('addToCart', ...);  // Won't work!

registerActions()

registerActions(actions): void;

Defined in: lib/vowel/core/VowelClient.ts:1020

Parameters

Parameter	Type
`actions`	`Record`<`string`, { `definition`: `VowelAction`; `handler`: `ActionHandler`; }>

Returns

void

Example

vowel.registerActions({
  searchProducts: {
    definition: { ... },
    handler: async (params) => { ... }
  },
  addToCart: {
    definition: { ... },
    handler: async (params) => { ... }
  }
});

unregisterAction()

unregisterAction(name): void;

Defined in: lib/vowel/core/VowelClient.ts:1031

Unregister an action

Parameters

Parameter	Type
`name`	`string`

Returns

void

getActionsConfig()

getActionsConfig(): Record<string, VowelAction>;

Defined in: lib/vowel/core/VowelClient.ts:1038

Get all registered actions as a record (for configuration)

Returns

Record<string, VowelAction>

onActionNotification()

onActionNotification(listener): () => void;

Defined in: lib/vowel/core/VowelClient.ts:1042

Parameters

Parameter	Type
`listener`	(`notification`) => `void`

Returns

(): void;

Returns

void

executeAction()

executeAction(name, params): Promise<ToolResult>;

Defined in: lib/vowel/core/VowelClient.ts:1049

Execute a registered action

Parameters

Parameter	Type
`name`	`string`
`params`	`any`

Returns

Promise<ToolResult>

hasAction()

hasAction(name): boolean;

Defined in: lib/vowel/core/VowelClient.ts:1064

Check if an action is registered

Parameters

Parameter	Type
`name`	`string`

Returns

boolean

addRoutes()

addRoutes(routes): void;

Defined in: lib/vowel/core/VowelClient.ts:1075

Add routes (useful for dynamic route registration)

Parameters

Parameter	Type
`routes`	`VowelRoute`[]

Returns

void

setRoutes()

setRoutes(routes): void;

Defined in: lib/vowel/core/VowelClient.ts:1082

Set routes (replaces existing)

Parameters

Parameter	Type
`routes`	`VowelRoute`[]

Returns

void

getCurrentPath()

getCurrentPath(): string;

Defined in: lib/vowel/core/VowelClient.ts:1089

Get current path

Returns

string

navigate()

navigate(path): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1102

Navigate to a path

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

onStateChange()

onStateChange(listener): () => void;

Defined in: lib/vowel/core/VowelClient.ts:1119

Subscribe to state changes

Parameters

Parameter	Type
`listener`	(`state`) => `void`

Returns

(): void;

Returns

void

clearTranscripts()

clearTranscripts(): void;

Defined in: lib/vowel/core/VowelClient.ts:1154

Clear transcript history

Returns

void

clearError()

clearError(): void;

Defined in: lib/vowel/core/VowelClient.ts:1161

Clear the current error state

Returns

void

getDarkMode()

getDarkMode(): boolean;

Defined in: lib/vowel/core/VowelClient.ts:1168

Get current dark mode state

Returns

boolean

setDarkMode()

setDarkMode(isDark): void;

Defined in: lib/vowel/core/VowelClient.ts:1175

Set dark mode state

Parameters

Parameter	Type
`isDark`	`boolean`

Returns

void

toggleDarkMode()

toggleDarkMode(): void;

Defined in: lib/vowel/core/VowelClient.ts:1182

Toggle dark mode

Returns

void

exportState()

exportState(options?): VoiceSessionState;

Defined in: lib/vowel/core/VowelClient.ts:1200

Export conversation state for later restoration

Parameters

Parameter	Type	Description
`options?`	{ `maxTurns?`: `number`; }	Export options
`options.maxTurns?`	`number`	Maximum conversation turns to include (default: all)

Returns

VoiceSessionState

Serializable state object

Example

// Save state to localStorage
const state = vowel.exportState({ maxTurns: 20 });
localStorage.setItem('vowel-conversation', JSON.stringify(state));

importState()

importState(savedState): void;

Defined in: lib/vowel/core/VowelClient.ts:1218

Import conversation state from a previous session

Parameters

Parameter	Type	Description
`savedState`	`Partial`<`VoiceSessionState`>	Previously exported state

Returns

void

Example

// Restore state from localStorage
const saved = localStorage.getItem('vowel-conversation');
if (saved) {
  vowel.importState(JSON.parse(saved));
}

startSession()

startSession(options?): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1266

Start a voice session Content window should be opened before calling this (in click handler for Shopify) Navigation is handled via BroadcastChannel, not WindowProxy

⚠️ CRITICAL for iOS Safari: This method MUST be called directly from a user gesture handler (click, touchstart, touchend). iOS Safari requires AudioContext creation and getUserMedia() calls to happen within the same user gesture event handler.

✅ Correct usage:

button.addEventListener('click', async () => {
  await vowel.startSession(); // Called directly from click handler
});

❌ Incorrect usage (will fail on iOS):

button.addEventListener('click', () => {
  setTimeout(() => {
    vowel.startSession(); // Too late - outside gesture handler
  }, 100);
});

Parameters

Parameter	Type	Description
`options?`	{ `restoreState?`: `Partial`<`VoiceSessionState`>; }	Session start options
`options.restoreState?`	`Partial`<`VoiceSessionState`>	Previously exported state to restore conversation context

Returns

Promise<void>

Example

// Start fresh session
await vowel.startSession();

// Start with restored context
const saved = localStorage.getItem('vowel-conversation');
if (saved) {
  await vowel.startSession({ restoreState: JSON.parse(saved) });
}

notify()

notify(
   eventType, 
   message, 
data?): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1334

Send a notification to the AI about an app event This allows programmatic triggering of AI responses

Parameters

Parameter	Type	Description
`eventType`	`string`	Type of event (e.g., 'notification', 'resource_issue', 'session_start')
`message`	`string`	Human-readable message describing the event
`data?`	`Record`<`string`, `any`>	Optional additional data/context

Returns

Promise<void>

Example

// Notify AI about a game event
vowel.notify('resource_issue', 'Low on wood', { wood: 5, required: 20 });

// Notify about session start
vowel.notify('session_start', 'Voice control is now active');

stopSession()

stopSession(): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1393

Stop the current session

Returns

Promise<void>

pauseSession()

pauseSession(): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1437

Pause the current session (mute microphone, keep connection alive) This is useful for temporarily stopping audio input without disconnecting

Returns

Promise<void>

Example

// Pause during a phone call
await vowel.pauseSession();

// Resume after the call
await vowel.resumeSession();

resumeSession()

resumeSession(): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1471

Resume a paused session (unmute microphone)

Returns

Promise<void>

Example

await vowel.resumeSession();

toggleSession()

toggleSession(): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1500

Toggle session on/off

Returns

Promise<void>

getAvailableMicrophones()

getAvailableMicrophones(requirePermission): Promise<MediaDeviceInfo[]>;

Defined in: lib/vowel/core/VowelClient.ts:1526

Get available microphone devices

Parameters

Parameter	Type	Default value	Description
`requirePermission`	`boolean`	`false`	If true, request getUserMedia first to get device labels. On iOS Safari, this MUST be called from a user gesture handler.

Returns

Promise<MediaDeviceInfo[]>

Promise resolving to array of MediaDeviceInfo for available audio input devices

Example

const devices = await vowel.getAvailableMicrophones();
console.log('Available microphones:', devices.map(d => d.label));

hasMicrophonePermission()

hasMicrophonePermission(): Promise<boolean>;

Defined in: lib/vowel/core/VowelClient.ts:1534

Check if microphone permission has been granted

Returns

Promise<boolean>

Promise resolving to true if permission granted, false otherwise

requestMicrophonePermission()

requestMicrophonePermission(): Promise<boolean>;

Defined in: lib/vowel/core/VowelClient.ts:1543

Request microphone permission MUST be called from a user gesture handler on iOS Safari

Returns

Promise<boolean>

Promise resolving to true if permission granted, false otherwise

getCurrentMicrophone()

getCurrentMicrophone(): MediaDeviceInfo | null;

Defined in: lib/vowel/core/VowelClient.ts:1560

Get the currently active microphone device

Returns

MediaDeviceInfo | null

MediaDeviceInfo for current device, or null if not available

Example

const currentMic = vowel.getCurrentMicrophone();
if (currentMic) {
  console.log('Current microphone:', currentMic.label);
}

setMicrophoneDevice()

setMicrophoneDevice(deviceId): void;

Defined in: lib/vowel/core/VowelClient.ts:1579

Set microphone device preference This will apply the device on the next microphone setup (next connection)

Parameters

Parameter	Type	Description
`deviceId`	`string`	The device ID to use

Returns

void

Example

const devices = await vowel.getAvailableMicrophones();
const usbMic = devices.find(d => d.label.includes('USB'));
if (usbMic) {
  vowel.setMicrophoneDevice(usbMic.deviceId);
}

switchMicrophoneDevice()

switchMicrophoneDevice(deviceId): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1598

Switch microphone device during an active session This will reinitialize the microphone stream with the new device

Parameters

Parameter	Type	Description
`deviceId`	`string`	The device ID to switch to

Returns

Promise<void>

Example

const devices = await vowel.getAvailableMicrophones();
const newMic = devices[1];
await vowel.switchMicrophoneDevice(newMic.deviceId);

notifyEvent()

notifyEvent(eventDetails, context?): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1655

Notify the AI about an app event This allows programmatic triggering of AI voice responses without user speech input

Parameters

Parameter	Type	Description
`eventDetails`	`string`	Description of the event that occurred
`context?`	`Record`<`string`, `any`>	Optional context object to provide additional information

Returns

Promise<void>

Example

// Simple notification
await vowel.notifyEvent('Order placed successfully!');

// Notification with context
await vowel.notifyEvent('New message received', {
  from: 'John Doe',
  preview: 'Hey, are you available?',
  timestamp: new Date().toISOString()
});

// Timer expiry notification
await vowel.notifyEvent('Your 5-minute timer has expired');

// Shopping cart update
await vowel.notifyEvent('Item added to cart', {
  productName: 'Wireless Headphones',
  price: 79.99,
  cartTotal: 3
});

sendText()

sendText(text): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1679

Send text to the AI for processing Lower-level method for custom text-based interactions

Parameters

Parameter	Type	Description
`text`	`string`	Text to send to the AI

Returns

Promise<void>

Example

// Ask a question programmatically
await vowel.sendText('What are the current promotions?');

// Provide context to the AI
await vowel.sendText('The user is looking at product ID 12345');

sendImage()

sendImage(imageUrl): Promise<void>;

Defined in: lib/vowel/core/VowelClient.ts:1707

Send an image to the AI for processing Enables multimodal interactions where the AI can see and respond to images

Parameters

Parameter	Type	Description
`imageUrl`	`string`	URL or data URI of the image to send

Returns

Promise<void>

Example

// Send an image URL
await vowel.sendImage('https://example.com/product.jpg');

// Send a data URI (e.g., from canvas or file upload)
await vowel.sendImage('data:image/png;base64,iVBORw0KGgoAAAANS...');

// Combined with text context
await vowel.sendText('What do you see in this image?');
await vowel.sendImage(imageUrl);

updateContext()

updateContext(context): void;

Defined in: lib/vowel/core/VowelClient.ts:1745

Update the dynamic context that gets appended to system prompt. Context is stringified, wrapped in <context> tags and sent via session.update.

When context changes, a session.update event is automatically sent to update the system prompt so the AI knows about the current context.

Parameters

Parameter	Type	Description
`context`	`Record`<`string`, `unknown`> \| `null`	Context object to append to system prompt. Use null to clear.

Returns

void

Example

// Update context with current page info
vowel.updateContext({ page: 'product', productId: 'iphone-15-pro' });

// Update with multiple details
vowel.updateContext({ 
  page: 'checkout', 
  cartTotal: 199.99, 
  itemCount: 2 
});

// Clear context
vowel.updateContext(null);

getContext()

getContext(): Record<string, unknown> | null;

Defined in: lib/vowel/core/VowelClient.ts:1774

Get current context value

Returns

Record<string, unknown> | null

Current context object (null if no context set)

Example

const currentContext = vowel.getContext();
console.log('Current context:', currentContext);

Class: Vowel ​

Example ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Accessors ​

appId ​

Get Signature ​

Returns ​

apiKey ​

Get Signature ​

Returns ​

router ​

Get Signature ​

Deprecated ​

Returns ​

routes ​

Get Signature ​

Returns ​

session ​

Get Signature ​

Returns ​

voiceConfig ​

Get Signature ​

Returns ​

systemInstructionOverride ​

Get Signature ​

Returns ​

state ​

Get Signature ​

Returns ​

floatingCursor ​

Get Signature ​

Returns ​

Methods ​

isUserSpeaking() ​

Returns ​

isAIThinking() ​

Returns ​

isAISpeaking() ​

Returns ​

registerAction() ​

Type Parameters ​

Parameters ​

Returns ​

Example ​

registerActions() ​

Parameters ​

Returns ​

Example ​

unregisterAction() ​

Parameters ​

Returns ​

getActionsConfig() ​

Returns ​

onActionNotification() ​

Parameters ​

Returns ​

Returns ​

executeAction() ​

Parameters ​

Returns ​

hasAction() ​

Parameters ​

Returns ​

addRoutes() ​

Parameters ​

Returns ​

setRoutes() ​

Parameters ​

Returns ​

getCurrentPath() ​

Returns ​

navigate() ​

Parameters ​

Returns ​

onStateChange() ​

Parameters ​

Returns ​

Class: Vowel

Example

Constructors

Constructor

Parameters

Returns

Accessors

appId

Get Signature

Returns

apiKey

Get Signature

Returns

router

Get Signature

Deprecated

Returns

routes

Get Signature

Returns

session

Get Signature

Returns

voiceConfig

Get Signature

Returns

systemInstructionOverride

Get Signature

Returns

state

Get Signature

Returns

floatingCursor

Get Signature

Returns

Methods

isUserSpeaking()

Returns

isAIThinking()

Returns

isAISpeaking()

Returns

registerAction()

Type Parameters

Parameters

Returns

Example

registerActions()

Parameters

Returns

Example

unregisterAction()

Parameters

Returns

getActionsConfig()

Returns

onActionNotification()

Parameters

Returns

Returns

executeAction()

Parameters

Returns

hasAction()

Parameters

Returns

addRoutes()

Parameters

Returns

setRoutes()

Parameters

Returns

getCurrentPath()

Returns

navigate()

Parameters

Returns

onStateChange()

Parameters

Returns