Function Signature function registerNavaiExpressRoutes ( app : Express , options ?: RegisterNavaiExpressRoutesOptions ) : void
Source: packages/voice-backend/src/index.ts:253Description Registers all Navai backend routes with your Express application. This includes:
Client secret endpoint for OpenAI Realtime authentication
Function listing endpoint for tool discovery
Function execution endpoint for running backend tools
Parameters Your Express application instance
options
RegisterNavaiExpressRoutesOptions
Configuration options for route registration env
Record<string, string | undefined>
Environment variables object. Defaults to process.env
Backend configuration options. If not provided, defaults are loaded from environment variables via getNavaiVoiceBackendOptionsFromEnv(env)
Whether to register function listing and execution routes (/navai/functions*)
clientSecretPath
string
default: "/navai/realtime/client-secret"
Custom path for the client secret endpoint
functionsListPath
string
default: "/navai/functions"
Custom path for the functions list endpoint
functionsExecutePath
string
default: "/navai/functions/execute"
Custom path for the function execution endpoint
Base directory for function scanning. If not specified, uses NAVAI_FUNCTIONS_BASE_DIR env var or process.cwd()
File extensions to include when scanning for functions
Glob patterns to exclude from function scanning
Return Value This function does not return a value. It registers routes directly on the Express app.
Registered Routes POST /navai/realtime/client-secret Creates an ephemeral client secret for OpenAI Realtime API.
Request Body: { "model" : "gpt-realtime" , "voice" : "marin" , "instructions" : "You are a helpful assistant." , "language" : "Spanish" , "voiceAccent" : "neutral Latin American Spanish" , "voiceTone" : "friendly and professional" , "apiKey" : "sk-..." }
Response: { "value" : "ek_..." , "expires_at" : 1730000000 }
GET /navai/functions Lists all available backend functions.
Response: { "items" : [ { "name" : "secret_password" , "description" : "Call exported function default." , "source" : "src/ai/functions-modules/security.ts#default" } ], "warnings" : [] }
POST /navai/functions/execute Executes a backend function by name.
Request Body: { "function_name" : "secret_password" , "payload" : { "args" : [ "abc" ] } }
Success Response: { "ok" : true , "function_name" : "secret_password" , "source" : "src/ai/functions-modules/security.ts#default" , "result" : "..." }
Error Response (Unknown Function): { "error" : "Unknown or disallowed function." , "available_functions" : [ "secret_password" , "other_function" ] }
Function Discovery Patterns The functionsFolders option accepts several pattern formats:
Pattern Description Example Folder Match all files in folder src/ai/functions-modulesRecursive Match all files recursively src/ai/functions-modules/...Wildcard Match using glob patterns src/features/*/voice-functionsExplicit File Match specific file src/ai/functions-modules/secret.tsCSV List Match multiple patterns src/ai/functions-modules,...
Runtime Behavior Important: The function runtime is lazy-loaded once and cached in-memory.
First call to list/execute functions builds the registry
After initial load, file changes are NOT auto-reloaded
Restart the process to reload function definitions
Usage Examples Basic Setup import express from "express" ; import { registerNavaiExpressRoutes } from "@navai/voice-backend" ; const app = express (); app . use ( express . json ()); registerNavaiExpressRoutes ( app ); app . listen ( 3000 );
Custom Configuration import express from "express" ; import { registerNavaiExpressRoutes } from "@navai/voice-backend" ; const app = express (); app . use ( express . json ()); registerNavaiExpressRoutes ( app , { backendOptions: { openaiApiKey: process . env . OPENAI_API_KEY , defaultModel: "gpt-realtime" , defaultVoice: "marin" , defaultInstructions: "You are a helpful assistant." , clientSecretTtlSeconds: 600 , allowApiKeyFromRequest: false }, functionsBaseDir: process . cwd (), functionsFolders: "src/ai/functions-modules" }); app . listen ( 3000 );
Custom Route Paths import express from "express" ; import { registerNavaiExpressRoutes } from "@navai/voice-backend" ; const app = express (); app . use ( express . json ()); registerNavaiExpressRoutes ( app , { clientSecretPath: "/api/auth/realtime-token" , functionsListPath: "/api/tools" , functionsExecutePath: "/api/tools/run" }); app . listen ( 3000 );
Disable Function Routes import express from "express" ; import { registerNavaiExpressRoutes } from "@navai/voice-backend" ; const app = express (); app . use ( express . json ()); // Only register client secret route registerNavaiExpressRoutes ( app , { includeFunctionsRoutes: false }); app . listen ( 3000 );
Multiple Function Folders import express from "express" ; import { registerNavaiExpressRoutes } from "@navai/voice-backend" ; const app = express (); app . use ( express . json ()); registerNavaiExpressRoutes ( app , { functionsFolders: "src/ai/functions-modules,...,src/features/*/tools" , includeExtensions: [ "ts" , "js" ], exclude: [ "**/node_modules/**" , "**/dist/**" , "**/*.test.ts" ] }); app . listen ( 3000 );