Class: Vowel

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

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({
  appId: 'your-app-id',
  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:98

Parameters

Parameter	Type
`config`	`VowelClientConfig`

Returns

Vowel

Accessors

appId

Get Signature

get appId(): string | undefined;

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

Get app ID

Returns

string | undefined

router

Get Signature

get router(): RouterAdapter | undefined;

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

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:733

Get configured routes

Returns

VowelRoute[]

session

Get Signature

get session(): SessionManager;

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

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:747

Get voice configuration

Returns

VowelVoiceConfig | undefined

systemInstructionOverride

Get Signature

get systemInstructionOverride(): string | undefined;

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

Get system instruction override

Returns

string | undefined

state

Get Signature

get state(): VoiceSessionState;

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

Get current session state

Returns

VoiceSessionState

floatingCursor

Get Signature

get floatingCursor(): FloatingCursorManager | undefined;

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

Get floating cursor manager (if enabled)

Returns

FloatingCursorManager | undefined

Methods

isUserSpeaking()

isUserSpeaking(): boolean;

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

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

Returns

boolean

isAIThinking()

isAIThinking(): boolean;

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

Check if AI is currently thinking/processing

Returns

boolean

isAISpeaking()

isAISpeaking(): boolean;

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

Check if AI is currently speaking

Returns

boolean

registerAction()

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

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

⚠️ 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:864

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:875

Unregister an action

Parameters

Parameter	Type
`name`	`string`

Returns

void

getActionsConfig()

getActionsConfig(): Record<string, VowelAction>;

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

Get all registered actions as a record (for configuration)

Returns

Record<string, VowelAction>

executeAction()

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

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

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:904

Check if an action is registered

Parameters

Parameter	Type
`name`	`string`

Returns

boolean

addRoutes()

addRoutes(routes): void;

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

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:922

Set routes (replaces existing)

Parameters

Parameter	Type
`routes`	`VowelRoute`[]

Returns

void

getCurrentPath()

getCurrentPath(): string;

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

Get current path

Returns

string

navigate()

navigate(path): Promise<void>;

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

Navigate to a path

Parameters

Parameter	Type
`path`	`string`

Returns

Promise<void>

onStateChange()

onStateChange(listener): () => void;

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

Subscribe to state changes

Parameters

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

Returns

(): void;

Returns

void

clearTranscripts()

clearTranscripts(): void;

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

Clear transcript history

Returns

void

clearError()

clearError(): void;

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

Clear the current error state

Returns

void

getDarkMode()

getDarkMode(): boolean;

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

Get current dark mode state

Returns

boolean

setDarkMode()

setDarkMode(isDark): void;

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

Set dark mode state

Parameters

Parameter	Type
`isDark`	`boolean`

Returns

void

toggleDarkMode()

toggleDarkMode(): void;

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

Toggle dark mode

Returns

void

exportState()

exportState(options?): VoiceSessionState;

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

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:1058

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:1106

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:1167

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:1226

Stop the current session

Returns

Promise<void>

pauseSession()

pauseSession(): Promise<void>;

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

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:1296

Resume a paused session (unmute microphone)

Returns

Promise<void>

Example

await vowel.resumeSession();

toggleSession()

toggleSession(): Promise<void>;

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

Toggle session on/off

Returns

Promise<void>

getAvailableMicrophones()

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

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

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:1359

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:1368

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:1385

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:1404

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:1423

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:1480

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:1504

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:1532

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);

Class: Vowel ​

Example ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Accessors ​

appId ​

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 ​

executeAction() ​

Parameters ​

Returns ​

hasAction() ​

Parameters ​

Returns ​

addRoutes() ​

Parameters ​

Returns ​

setRoutes() ​

Parameters ​

Returns ​

getCurrentPath() ​

Returns ​

navigate() ​

Parameters ​

Returns ​

onStateChange() ​

Parameters ​

Returns ​

Returns ​

clearTranscripts() ​

Returns ​

clearError() ​

Returns ​

getDarkMode() ​

Returns ​

Class: Vowel

Example

Constructors

Constructor

Parameters

Returns

Accessors

appId

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

executeAction()

Parameters

Returns

hasAction()

Parameters

Returns

addRoutes()

Parameters

Returns

setRoutes()

Parameters

Returns

getCurrentPath()

Returns

navigate()

Parameters

Returns

onStateChange()

Parameters

Returns

Returns

clearTranscripts()

Returns

clearError()

Returns

getDarkMode()

Returns