useWebVoiceAgent

Overview

The useWebVoiceAgent hook provides a complete React integration for NAVAI voice agents. It manages the entire lifecycle of voice agent connections, including initialization, backend communication, function loading, and session management.

Import

import { useWebVoiceAgent } from '@navai/voice-frontend';

Signature

function useWebVoiceAgent(
  options: UseWebVoiceAgentOptions
): UseWebVoiceAgentResult

Parameters

options

UseWebVoiceAgentOptions

required

Configuration options for the voice agent hook.

Show properties

navigate

(path: string) => void

required

Navigation function to handle route changes. Typically from your router (e.g., React Router’s navigate function).

moduleLoaders

NavaiFunctionModuleLoaders

required

Object mapping function module paths to dynamic import loaders.

{
  './functions/getUserProfile.ts': () => import('./functions/getUserProfile'),
  './functions/sendMessage.ts': () => import('./functions/sendMessage')
}

defaultRoutes

NavaiRoute[]

required

Array of route definitions that the voice agent can navigate to.

[
  {
    name: 'profile',
    path: '/profile',
    description: 'User profile page',
    synonyms: ['perfil', 'my account']
  }
]

env

Record<string, string | undefined>

Environment variables for configuration. Can include NAVAI_API_URL to override the default backend URL.

apiBaseUrl

string

Base URL for the NAVAI backend API. Defaults to http://localhost:3000.

routesFile

string

Path to a custom routes configuration file.

functionsFolders

string

Comma-separated list of folders containing function modules.

modelOverride

string

Override the default OpenAI model for the voice agent (e.g., gpt-4o-realtime-preview).

defaultRoutesFile

string

Path to the default routes configuration file.

defaultFunctionsFolder

string

Path to the default functions folder.

Return Value

result

UseWebVoiceAgentResult

An object containing the voice agent state and control methods.

Show properties

status

'idle' | 'connecting' | 'connected' | 'error'

Current connection status of the voice agent.

idle: Not connected
connecting: Establishing connection
connected: Active voice session
error: Connection or runtime error occurred

error

string | null

Error message if status is error, otherwise null.

isConnecting

boolean

Convenience flag indicating if status is connecting.

isConnected

boolean

Convenience flag indicating if status is connected.

start

() => Promise<void>

Async function to initialize and start the voice agent session.This function:

Resolves runtime configuration
Creates a backend client secret
Loads backend and frontend functions
Builds the agent with tools
Establishes a realtime connection

Throws errors that are caught and stored in the error field.

stop

() => void

Function to disconnect and cleanup the voice agent session.

Example Usage

import { useWebVoiceAgent } from '@navai/voice-frontend';
import { useNavigate } from 'react-router-dom';

function VoiceAssistant() {
  const navigate = useNavigate();
  
  const voiceAgent = useWebVoiceAgent({
    navigate,
    moduleLoaders: {
      './functions/getProfile.ts': () => import('./functions/getProfile'),
      './functions/sendMessage.ts': () => import('./functions/sendMessage')
    },
    defaultRoutes: [
      {
        name: 'home',
        path: '/',
        description: 'Home page'
      },
      {
        name: 'profile',
        path: '/profile',
        description: 'User profile page',
        synonyms: ['perfil', 'account']
      },
      {
        name: 'settings',
        path: '/settings',
        description: 'Application settings',
        synonyms: ['config', 'preferences']
      }
    ],
    apiBaseUrl: 'https://api.myapp.com',
    modelOverride: 'gpt-4o-realtime-preview'
  });

  return (
    <div>
      <h2>Voice Assistant</h2>
      <p>Status: {voiceAgent.status}</p>
      
      {voiceAgent.error && (
        <div className="error">
          Error: {voiceAgent.error}
        </div>
      )}
      
      {voiceAgent.isConnected ? (
        <button onClick={voiceAgent.stop}>
          Stop Voice Agent
        </button>
      ) : (
        <button 
          onClick={voiceAgent.start}
          disabled={voiceAgent.isConnecting}
        >
          {voiceAgent.isConnecting ? 'Connecting...' : 'Start Voice Agent'}
        </button>
      )}
    </div>
  );
}

Lifecycle

Initialization: Hook sets up memoized backend client and runtime config promise
Start: Call start() to begin connection sequence
Connecting: Backend secret created, functions loaded, agent built
Connected: Realtime session established with OpenAI
Stop: Call stop() to gracefully close the session
Cleanup: Hook automatically calls stop() on unmount

Error Handling

const voiceAgent = useWebVoiceAgent(options);

if (voiceAgent.status === 'error') {
  console.error('Voice agent error:', voiceAgent.error);
  // Handle error - show UI message, retry, etc.
}

Source Reference

Defined in: packages/voice-frontend/src/useWebVoiceAgent.ts:52

Backend API

Frontend API

Mobile API

useWebVoiceAgent

Overview

Import

Signature

Parameters

Return Value

Example Usage

Lifecycle

Error Handling

Source Reference

Build docs developers (and LLMs) love

Backend API

Frontend API

Mobile API

​Overview

​Import

​Signature

​Parameters

​Return Value

​Example Usage

​Lifecycle

​Error Handling

​Source Reference

Build docs developers (and LLMs) love

Overview

Import

Signature

Parameters

Return Value

Example Usage

Lifecycle

Error Handling

Source Reference