Skip to main content

​
What is @navai/voice-frontend?

@navai/voice-frontend is a React SDK that provides voice-first navigation and function execution for web applications. It integrates with the OpenAI Realtime API to enable natural voice interactions that can navigate your app and execute frontend functions.

​
Key Features

  • Voice Navigation: Navigate between routes using natural language
  • Frontend Functions: Execute JavaScript functions via voice commands
  • Backend Integration: Connect to backend functions through the NAVAI API
  • React Hook: Simple useWebVoiceAgent hook for React apps
  • Type-Safe: Full TypeScript support with type definitions
  • Flexible Configuration: Runtime and build-time configuration options

​
Installation

npm install @navai/voice-frontend
The package requires React 18 or higher as a peer dependency.

​
Core Exports

​
React Hook

import { useWebVoiceAgent } from '@navai/voice-frontend';
The primary hook for integrating voice navigation into React components.

​
Agent Builder

import { buildNavaiAgent } from '@navai/voice-frontend';
Low-level API for building a RealtimeAgent with routes and functions.

​
Backend Client

import { createNavaiBackendClient } from '@navai/voice-frontend';
HTTP client for communicating with the NAVAI backend API.

​
Route Resolution

import { resolveNavaiRoute, getNavaiRoutePromptLines } from '@navai/voice-frontend';
Utilities for defining and resolving voice-navigable routes.

​
Function Loading

import { loadNavaiFunctions } from '@navai/voice-frontend';
Dynamic function loader that discovers and registers frontend functions.

​
Quick Example

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

const ROUTES = [
  { name: 'home', path: '/', description: 'Home page' },
  { name: 'profile', path: '/profile', description: 'User profile' }
];

function VoiceButton() {
  const navigate = useNavigate();
  const { start, stop, isConnected } = useWebVoiceAgent({
    navigate,
    defaultRoutes: ROUTES,
    moduleLoaders: {}
  });

  return (
    <button onClick={isConnected ? stop : start}>
      {isConnected ? 'Stop Voice' : 'Start Voice'}
    </button>
  );
}

​
Architecture

The frontend SDK coordinates several components:
  1. useWebVoiceAgent: React hook that manages the voice session lifecycle
  2. buildNavaiAgent: Creates an OpenAI RealtimeAgent with navigation and function tools
  3. createNavaiBackendClient: Handles API communication for secrets and backend functions
  4. Runtime Config: Resolves routes and functions from environment variables or defaults
  5. Route Resolution: Maps voice inputs to application routes
  6. Function Registry: Loads and executes frontend functions

​
Next Steps

React Web Hook

Learn how to use useWebVoiceAgent in your React app

Configuration

Configure routes, functions, and backend connection

UI Navigation

Define voice-navigable routes for your app

Local Functions

Create frontend functions callable via voice

Build docs developers (and LLMs) love

Get started for freeTalk to us