Skip to main content

​
Overview

The createNavaiBackendClient function creates a client instance for communicating with the NAVAI backend API. The client handles three main operations: creating ephemeral client secrets, listing available backend functions, and executing backend functions.

​
Import

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

​
Signature

function createNavaiBackendClient(
  options?: CreateNavaiBackendClientOptions
): NavaiBackendClient

​
Parameters

​
options
CreateNavaiBackendClientOptions
Optional configuration for the backend client.

​
Return Value

​
client
NavaiBackendClient
Backend client instance with three methods.

​
Example Usage

​
Basic Setup

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

// Create client with default settings (localhost:3000)
const client = createNavaiBackendClient();

// Create client with custom URL
const client = createNavaiBackendClient({
  apiBaseUrl: 'https://api.myapp.com'
});

// Create client with environment variables
const client = createNavaiBackendClient({
  env: {
    NAVAI_API_URL: 'https://api.myapp.com'
  }
});

​
Creating Client Secret

const client = createNavaiBackendClient({
  apiBaseUrl: 'https://api.myapp.com'
});

try {
  const secret = await client.createClientSecret({
    model: 'gpt-4o-realtime-preview',
    voice: 'alloy',
    language: 'en'
  });
  
  console.log('Ephemeral key:', secret.value);
  if (secret.expires_at) {
    console.log('Expires at:', new Date(secret.expires_at * 1000));
  }
  
  // Use secret.value to connect RealtimeSession
  await session.connect({ apiKey: secret.value });
} catch (error) {
  console.error('Failed to create client secret:', error);
}

​
Listing Backend Functions

const client = createNavaiBackendClient();

const result = await client.listFunctions();

// Handle warnings (non-fatal errors)
if (result.warnings.length > 0) {
  console.warn('Warnings:', result.warnings);
}

// Use functions
console.log('Available backend functions:');
for (const fn of result.functions) {
  console.log(`- ${fn.name}: ${fn.description || 'No description'}`);
}

​
Executing Backend Function

const client = createNavaiBackendClient({
  apiBaseUrl: 'https://api.myapp.com'
});

try {
  // Execute function with payload
  const result = await client.executeFunction({
    functionName: 'search_documents',
    payload: {
      query: 'invoice',
      limit: 10
    }
  });
  
  console.log('Search results:', result);
} catch (error) {
  console.error('Function execution failed:', error);
}

// Execute function without payload
try {
  const result = await client.executeFunction({
    functionName: 'get_current_user',
    payload: null
  });
  
  console.log('Current user:', result);
} catch (error) {
  console.error('Failed to get user:', error);
}

​
Full Integration Example

import { createNavaiBackendClient, buildNavaiAgent } from '@navai/voice-frontend';
import { RealtimeSession } from '@openai/agents/realtime';

async function initializeVoiceAgent(navigate: (path: string) => void) {
  // Create backend client
  const backendClient = createNavaiBackendClient({
    apiBaseUrl: 'https://api.myapp.com'
  });
  
  // Get client secret
  const secret = await backendClient.createClientSecret({
    model: 'gpt-4o-realtime-preview'
  });
  
  // List backend functions
  const { functions, warnings } = await backendClient.listFunctions();
  if (warnings.length > 0) {
    console.warn('Backend function warnings:', warnings);
  }
  
  // Build agent
  const { agent } = await buildNavaiAgent({
    navigate,
    routes: [
      { name: 'home', path: '/', description: 'Home page' },
      { name: 'profile', path: '/profile', description: 'User profile' }
    ],
    backendFunctions: functions,
    executeBackendFunction: backendClient.executeFunction,
    functionModuleLoaders: {
      './functions/getUser.ts': () => import('./functions/getUser')
    }
  });
  
  // Create and connect session
  const session = new RealtimeSession(agent);
  await session.connect({ apiKey: secret.value });
  
  return session;
}

​
Error Handling

​
createClientSecret

Throws errors that should be caught: 
try {
  const secret = await client.createClientSecret();
} catch (error) {
  // Handle HTTP errors or invalid responses
  console.error('Failed to create secret:', error.message);
}

​
listFunctions

Never throws; returns warnings instead: 
const { functions, warnings } = await client.listFunctions();

// Always succeeds, check warnings for issues
if (warnings.length > 0) {
  console.warn('Issues loading backend functions:', warnings);
}

// functions will be empty array if loading failed
if (functions.length === 0) {
  console.log('No backend functions available');
}

​
executeFunction

Throws errors for execution failures: 
try {
  const result = await client.executeFunction({
    functionName: 'process_data',
    payload: { data: [1, 2, 3] }
  });
} catch (error) {
  // Handle execution errors or HTTP errors
  console.error('Function execution failed:', error.message);
}

​
Custom Fetch Implementation

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

// Example: Add authentication headers
const customFetch: typeof fetch = async (url, options) => {
  const token = await getAuthToken();
  
  return fetch(url, {
    ...options,
    headers: {
      ...options?.headers,
      'Authorization': `Bearer ${token}`
    }
  });
};

const client = createNavaiBackendClient({
  apiBaseUrl: 'https://api.myapp.com',
  fetchImpl: customFetch
});

​
Source Reference

Defined in: packages/voice-frontend/src/backend.ts:80

Build docs developers (and LLMs) love

Get started for freeTalk to us