Skip to main content

​
Overview

The createNavaiBackendClient function creates an HTTP client for communicating with the Navai backend API. It handles authentication, function listing, and function execution.

​
Import

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

​
Type Signature

function createNavaiBackendClient(
  options?: CreateNavaiBackendClientOptions
): NavaiBackendClient

​
Parameters

​
options
CreateNavaiBackendClientOptions
Optional client configuration
​
apiBaseUrl
string
Backend API base URLDefault: http://localhost:3000Can also be set via env.NAVAI_API_URL
​
env
Record<string, string | undefined>
Environment variables
env: {
  NAVAI_API_URL: 'https://api.example.com'
}
​
fetchImpl
typeof fetch
Custom fetch implementation (defaults to global fetch)
​
clientSecretPath
string
Path for client secret endpointDefault: /navai/realtime/client-secret
​
functionsListPath
string
Path for functions list endpointDefault: /navai/functions
​
functionsExecutePath
string
Path for function execution endpointDefault: /navai/functions/execute

​
Return Value

​
NavaiBackendClient
object
required
Backend client instance with three methods
​
createClientSecret
(input?: CreateClientSecretInput) => Promise<CreateClientSecretOutput>
required
Create ephemeral client secret for OpenAI Realtime APIInput:
{
  model?: string;          // e.g., 'gpt-4o-realtime-preview-2024-12-17'
  voice?: string;          // e.g., 'alloy'
  instructions?: string;   // System instructions
  language?: string;       // e.g., 'en'
  voiceAccent?: string;
  voiceTone?: string;
  apiKey?: string;         // Optional override
}
Output:
{
  value: string;           // Ephemeral API key
  expires_at?: number;     // Unix timestamp
}
​
listFunctions
() => Promise<BackendFunctionsResult>
required
List available backend functionsOutput:
{
  functions: [
    {
      name: string;
      description?: string;
      source?: string;
    }
  ],
  warnings: string[];      // Non-fatal errors
}
​
executeFunction
ExecuteNavaiBackendFunction
required
Execute a backend functionInput:
{
  functionName: string;
  payload: Record<string, unknown> | null;
}
Output:
unknown  // Function result
Throws: Error if function fails or returns ok: false

​
Examples

​
Basic Usage

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

const client = createNavaiBackendClient();

// Create client secret
const secret = await client.createClientSecret();
console.log(secret.value); // "sk-..."

// List functions
const { functions } = await client.listFunctions();
console.log(functions); // [{ name: 'send_email', description: '...' }]

// Execute function
const result = await client.executeFunction({
  functionName: 'send_email',
  payload: {
    to: '[email protected]',
    subject: 'Hello',
    body: 'World'
  }
});

​
With Custom Base URL

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

// All requests go to https://api.example.com
const secret = await client.createClientSecret();

​
With Environment Variables

const client = createNavaiBackendClient({
  env: {
    NAVAI_API_URL: 'https://api.example.com'
  }
});

// Uses env.NAVAI_API_URL as base URL

​
With Custom Fetch

import fetch from 'node-fetch';

const client = createNavaiBackendClient({
  fetchImpl: fetch as any
});

// Uses node-fetch instead of global fetch

​
With Custom Paths

const client = createNavaiBackendClient({
  apiBaseUrl: 'https://api.example.com',
  clientSecretPath: '/api/v1/realtime/secret',
  functionsListPath: '/api/v1/functions',
  functionsExecutePath: '/api/v1/functions/run'
});

​
With Model Override

const secret = await client.createClientSecret({
  model: 'gpt-4o-realtime-preview-2024-12-17',
  voice: 'alloy',
  instructions: 'You are a helpful assistant.'
});

console.log(secret);
// { value: 'sk-...', expires_at: 1234567890 }

​
Handling Function List Errors

const { functions, warnings } = await client.listFunctions();

if (warnings.length > 0) {
  console.warn('Function loading warnings:', warnings);
  // [navai] Failed to load backend functions (404).
}

console.log(`Loaded ${functions.length} backend functions`);

​
Executing Backend Functions

try {
  const result = await client.executeFunction({
    functionName: 'create_order',
    payload: {
      items: [{ id: 1, quantity: 2 }],
      userId: '123'
    }
  });
  
  console.log('Order created:', result);
} catch (error) {
  console.error('Function execution failed:', error.message);
}

​
Complete Integration Example

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

// Create client
const client = createNavaiBackendClient({
  apiBaseUrl: process.env.NEXT_PUBLIC_API_URL
});

// Get ephemeral key and functions
const secret = await client.createClientSecret({
  model: 'gpt-4o-realtime-preview-2024-12-17'
});
const { functions: backendFunctions } = await client.listFunctions();

// Build agent
const { agent } = await buildNavaiAgent({
  navigate: (path) => router.push(path),
  routes: myRoutes,
  backendFunctions,
  executeBackendFunction: client.executeFunction
});

// Start session
const session = new RealtimeSession(agent);
await session.connect({
  apiKey: secret.value,
  model: 'gpt-4o-realtime-preview-2024-12-17'
});

​
API Endpoints

​
POST /navai/realtime/client-secret

Create ephemeral client secret. Request: 
{
  "model": "gpt-4o-realtime-preview-2024-12-17",
  "voice": "alloy",
  "instructions": "You are helpful."
}
Response: 
{
  "value": "sk-...",
  "expires_at": 1234567890
}

​
GET /navai/functions

List available backend functions. Response: 
{
  "items": [
    {
      "name": "send_email",
      "description": "Send an email",
      "source": "backend"
    }
  ],
  "warnings": []
}

​
POST /navai/functions/execute

Execute a backend function. Request: 
{
  "function_name": "send_email",
  "payload": {
    "to": "[email protected]",
    "subject": "Hello"
  }
}
Response (Success): 
{
  "ok": true,
  "result": { "messageId": "abc123" }
}
Response (Error): 
{
  "ok": false,
  "error": "Invalid email address",
  "details": "user@example is not a valid email"
}

​
Error Handling

​
Client Secret Errors

try {
  const secret = await client.createClientSecret();
} catch (error) {
  // HTTP error or invalid response
  console.error('Failed to create secret:', error.message);
}

​
Function List Errors

const { functions, warnings } = await client.listFunctions();

// Always succeeds, but may return warnings
if (warnings.length > 0) {
  warnings.forEach(w => console.warn(w));
}

if (functions.length === 0) {
  console.log('No backend functions available');
}

​
Function Execution Errors

try {
  const result = await client.executeFunction({
    functionName: 'send_email',
    payload: { to: 'invalid' }
  });
} catch (error) {
  // Either HTTP error or function returned ok: false
  console.error('Function failed:', error.message);
}

​
Types

// packages/voice-frontend/src/backend.ts:29-42

export type CreateNavaiBackendClientOptions = {
  apiBaseUrl?: string;
  env?: Record<string, string | undefined>;
  fetchImpl?: typeof fetch;
  clientSecretPath?: string;
  functionsListPath?: string;
  functionsExecutePath?: string;
};

export type NavaiBackendClient = {
  createClientSecret: (input?: CreateClientSecretInput) => Promise<CreateClientSecretOutput>;
  listFunctions: () => Promise<BackendFunctionsResult>;
  executeFunction: ExecuteNavaiBackendFunction;
};

Build docs developers (and LLMs) love

Get started for freeTalk to us