Skip to main content

​
Backend Options

Configuration options for backend initialization. Source: packages/voice-backend/src/index.ts:30 
type NavaiVoiceBackendOptions = {
  openaiApiKey?: string;
  defaultModel?: string;
  defaultVoice?: string;
  defaultInstructions?: string;
  defaultLanguage?: string;
  defaultVoiceAccent?: string;
  defaultVoiceTone?: string;
  clientSecretTtlSeconds?: number;
  allowApiKeyFromRequest?: boolean;
}
​
openaiApiKey
string
Your OpenAI API key. If not provided, allowApiKeyFromRequest must be enabled
​
defaultModel
string
default:"gpt-realtime"
Default OpenAI Realtime model
​
defaultVoice
string
default:"marin"
Default voice for audio output
​
defaultInstructions
string
default:"You are a helpful assistant."
Default system instructions
​
defaultLanguage
string
Default response language (e.g., “Spanish”, “French”)
​
defaultVoiceAccent
string
Default voice accent (e.g., “neutral Latin American Spanish”)
​
defaultVoiceTone
string
Default voice tone (e.g., “friendly and professional”)
​
clientSecretTtlSeconds
number
default:"600"
Time-to-live for client secrets in seconds. Must be between 10 and 7200
​
allowApiKeyFromRequest
boolean
Whether to allow API keys from client requests. Auto-enabled if openaiApiKey is not set

​
CreateClientSecretRequest

Request body for creating a client secret. Source: packages/voice-backend/src/index.ts:42 
type CreateClientSecretRequest = {
  model?: string;
  voice?: string;
  instructions?: string;
  language?: string;
  voiceAccent?: string;
  voiceTone?: string;
  apiKey?: string;
}
​
model
string
Override default model for this session
​
voice
string
Override default voice for this session
​
instructions
string
Override default instructions for this session
​
language
string
Override default language for this session
​
voiceAccent
string
Override default voice accent for this session
​
voiceTone
string
Override default voice tone for this session
​
apiKey
string
Client-provided API key (only used if allowed)

​
OpenAIRealtimeClientSecretResponse

Response from OpenAI Realtime client secret endpoint. Source: packages/voice-backend/src/index.ts:52 
type OpenAIRealtimeClientSecretResponse = {
  value: string;
  expires_at: number;
  session?: unknown;
}
​
value
string
required
The ephemeral client secret token (starts with ek_)
​
expires_at
number
required
Unix timestamp when the token expires
​
session
unknown
Optional session metadata from OpenAI

​
RegisterNavaiExpressRoutesOptions

Options for registering Express routes. Source: packages/voice-backend/src/index.ts:58 
type RegisterNavaiExpressRoutesOptions = {
  env?: Record<string, string | undefined>;
  backendOptions?: NavaiVoiceBackendOptions;
  includeFunctionsRoutes?: boolean;
  clientSecretPath?: string;
  functionsListPath?: string;
  functionsExecutePath?: string;
  functionsBaseDir?: string;
  functionsFolders?: string;
  includeExtensions?: string[];
  exclude?: string[];
}
​
env
Record<string, string | undefined>
default:"process.env"
Environment variables object
​
backendOptions
NavaiVoiceBackendOptions
Backend configuration. Defaults to loading from environment
​
includeFunctionsRoutes
boolean
default:"true"
Whether to register function routes
​
clientSecretPath
string
default:"/navai/realtime/client-secret"
Custom path for client secret endpoint
​
functionsListPath
string
default:"/navai/functions"
Custom path for functions list endpoint
​
functionsExecutePath
string
default:"/navai/functions/execute"
Custom path for function execution endpoint
​
functionsBaseDir
string
Base directory for function scanning
​
functionsFolders
string
Comma-separated patterns for function discovery
​
includeExtensions
string[]
File extensions to include
​
exclude
string[]
Glob patterns to exclude

​
Runtime Configuration

​
ResolveNavaiBackendRuntimeConfigOptions

Options for resolving runtime configuration. Source: packages/voice-backend/src/runtime.ts:9 
type ResolveNavaiBackendRuntimeConfigOptions = {
  env?: Record<string, string | undefined>;
  functionsFolders?: string;
  defaultFunctionsFolder?: string;
  baseDir?: string;
  includeExtensions?: string[];
  exclude?: string[];
}
​
env
Record<string, string | undefined>
default:"process.env"
Environment variables object
​
functionsFolders
string
Comma-separated patterns for function discovery
​
defaultFunctionsFolder
string
default:"src/ai/functions-modules"
Fallback folder when no matches found
​
baseDir
string
default:"process.cwd()"
Base directory for scanning
​
includeExtensions
string[]
File extensions to include
​
exclude
string[]
Glob patterns to exclude

​
ResolveNavaiBackendRuntimeConfigResult

Result from runtime configuration resolution. Source: packages/voice-backend/src/runtime.ts:18 
type ResolveNavaiBackendRuntimeConfigResult = {
  functionModuleLoaders: NavaiFunctionModuleLoaders;
  warnings: string[];
}
​
functionModuleLoaders
NavaiFunctionModuleLoaders
required
Record of file paths to module loader functions
​
warnings
string[]
required
Array of warning messages from scanning

​
Function Types

Payload passed to function execution. Source: packages/voice-backend/src/functions.ts:1 
type NavaiFunctionPayload = Record<string, unknown>
Common properties:
  • args or arguments: Array of function arguments
  • value: Single value argument
  • constructorArgs: Constructor arguments for class instantiation
  • methodArgs: Method arguments for class methods
  • Any other properties: Passed as first argument if args not provided
Context passed to function execution. Source: packages/voice-backend/src/functions.ts:3 
type NavaiFunctionContext = Record<string, unknown>
Properties:
  • req: Express Request object when called from /navai/functions/execute
Normalized function definition. Source: packages/voice-backend/src/functions.ts:5 
type NavaiFunctionDefinition = {
  name: string;
  description: string;
  source: string;
  run: (payload: NavaiFunctionPayload, context: NavaiFunctionContext) => Promise<unknown> | unknown;
}
​
name
string
required
Normalized function name (snake_case)
​
description
string
required
Human-readable description of what the function does
​
source
string
required
Source location in format path#exportName or path#exportName.method
​
run
(payload: NavaiFunctionPayload, context: NavaiFunctionContext) => Promise<unknown> | unknown
required
Async function that executes the tool with given payload and context
Registry of loaded functions. Source: packages/voice-backend/src/functions.ts:12 
type NavaiFunctionsRegistry = {
  byName: Map<string, NavaiFunctionDefinition>;
  ordered: NavaiFunctionDefinition[];
  warnings: string[];
}
​
byName
Map<string, NavaiFunctionDefinition>
required
Map of function names to definitions for O(1) lookup
​
ordered
NavaiFunctionDefinition[]
required
Array of all function definitions in discovery order
​
warnings
string[]
required
Array of warning messages from loading process
Record of module loaders. Source: packages/voice-backend/src/functions.ts:18 
type NavaiFunctionModuleLoaders = Record<string, () => Promise<unknown>>
Maps file paths to async functions that import the module. Example: 
const loaders: NavaiFunctionModuleLoaders = {
  "src/ai/functions-modules/weather.ts": () => import("./weather.ts"),
  "src/ai/functions-modules/calendar.ts": () => import("./calendar.ts")
};

​
Usage Examples

​
Type-Safe Backend Configuration

import type { NavaiVoiceBackendOptions } from "@navai/voice-backend";

const options: NavaiVoiceBackendOptions = {
  openaiApiKey: process.env.OPENAI_API_KEY,
  defaultModel: "gpt-realtime",
  defaultVoice: "marin",
  defaultInstructions: "You are a helpful assistant.",
  clientSecretTtlSeconds: 600,
  allowApiKeyFromRequest: false
};

​
Type-Safe Client Secret Request

import type { CreateClientSecretRequest } from "@navai/voice-backend";

const request: CreateClientSecretRequest = {
  model: "gpt-realtime",
  voice: "marin",
  instructions: "You are a travel assistant.",
  language: "Spanish",
  voiceAccent: "neutral Latin American Spanish",
  voiceTone: "warm and enthusiastic"
};

​
Type-Safe Function Definition

import type { 
  NavaiFunctionDefinition,
  NavaiFunctionPayload,
  NavaiFunctionContext 
} from "@navai/voice-backend";

const weatherFunction: NavaiFunctionDefinition = {
  name: "get_weather",
  description: "Get current weather for a location",
  source: "src/ai/functions-modules/weather.ts#default",
  run: async (payload: NavaiFunctionPayload, context: NavaiFunctionContext) => {
    const location = payload.args?.[0] as string;
    return { temp: 72, location };
  }
};

​
Type-Safe Registry Usage

import type { NavaiFunctionsRegistry } from "@navai/voice-backend";
import { loadNavaiFunctions } from "@navai/voice-backend";

const registry: NavaiFunctionsRegistry = await loadNavaiFunctions(loaders);

// Type-safe lookup
const fn = registry.byName.get("get_weather");
if (fn) {
  const result = await fn.run(
    { args: ["San Francisco"] },
    { req: {} as any }
  );
}

// Type-safe iteration
for (const definition of registry.ordered) {
  console.log(`${definition.name}: ${definition.description}`);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us