Skip to main content

​
Overview

The createNavaiMobileBackendClient function creates a client for communicating with your NAVAI backend. It handles creating realtime client secrets, listing backend functions, and executing backend function calls.

​
Usage

import { createNavaiMobileBackendClient } from '@navai/voice-mobile';

const backendClient = createNavaiMobileBackendClient({
  apiBaseUrl: 'https://api.myapp.com',
  env: { NAVAI_API_URL: 'https://api.myapp.com' }
});

// Create client secret for WebRTC
const { value: clientSecret } = await backendClient.createClientSecret({
  model: 'gpt-4o-realtime-preview',
  voice: 'alloy',
  instructions: 'You are a helpful assistant.'
});

// List available backend functions
const { functions, warnings } = await backendClient.listFunctions();

// Execute a backend function
const result = await backendClient.executeFunction({
  functionName: 'get_weather',
  payload: { location: 'San Francisco' }
});

​
Options

​
apiBaseUrl
string
Base URL for the NAVAI backend API. Defaults to http://localhost:3000 if not provided.Can also be set via env.NAVAI_API_URL.
apiBaseUrl: 'https://api.myapp.com'
​
env
NavaiMobileEnv
Environment variables object. Used to read NAVAI_API_URL if apiBaseUrl is not provided.
env: { NAVAI_API_URL: 'https://api.myapp.com' }
​
fetchImpl
typeof fetch
Custom fetch implementation. Defaults to global fetch.
fetchImpl: customFetch
​
clientSecretPath
string
API path for creating client secrets. Defaults to /navai/realtime/client-secret.
clientSecretPath: '/api/v1/realtime/secret'
​
functionsListPath
string
API path for listing functions. Defaults to /navai/functions.
functionsListPath: '/api/v1/functions'
​
functionsExecutePath
string
API path for executing functions. Defaults to /navai/functions/execute.
functionsExecutePath: '/api/v1/functions/execute'

​
Return Value

Returns NavaiMobileBackendClient object:
​
createClientSecret
(input?: CreateRealtimeClientSecretInput) => Promise<CreateRealtimeClientSecretResult>
Create a realtime client secret for WebRTC connection.
​
listFunctions
() => Promise<BackendFunctionsResult>
List available backend functions.
​
executeFunction
(input: ExecuteNavaiBackendFunctionInput) => Promise<unknown>
Execute a backend function.Returns the function result. Throws error if execution fails.

​
Examples

​
Basic Setup

import { createNavaiMobileBackendClient } from '@navai/voice-mobile';

const backendClient = createNavaiMobileBackendClient({
  apiBaseUrl: process.env.NAVAI_API_URL || 'http://localhost:3000'
});

​
Create Client Secret

const secretResult = await backendClient.createClientSecret({
  model: 'gpt-4o-realtime-preview',
  voice: 'alloy',
  instructions: 'You are a helpful fitness coach.'
});

console.log('Client Secret:', secretResult.value);
if (secretResult.expires_at) {
  console.log('Expires at:', new Date(secretResult.expires_at * 1000));
}

​
List Backend Functions

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

if (warnings.length > 0) {
  console.warn('Warnings:', warnings);
}

console.log('Available functions:');
for (const fn of functions) {
  console.log(`- ${fn.name}: ${fn.description}`);
}

​
Execute Backend Function

try {
  const result = await backendClient.executeFunction({
    functionName: 'get_weather',
    payload: {
      location: 'San Francisco, CA',
      units: 'fahrenheit'
    }
  });
  
  console.log('Weather result:', result);
} catch (error) {
  console.error('Function execution failed:', error.message);
}

​
Custom API Paths

const backendClient = createNavaiMobileBackendClient({
  apiBaseUrl: 'https://api.myapp.com',
  clientSecretPath: '/api/v1/realtime/secret',
  functionsListPath: '/api/v1/functions/list',
  functionsExecutePath: '/api/v1/functions/exec'
});

​
With Custom Fetch

import { fetch as customFetch } from './custom-fetch';

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

​
Integration with Voice Session

import {
  createNavaiMobileBackendClient,
  createNavaiMobileVoiceSession,
  createReactNativeWebRtcTransport
} from '@navai/voice-mobile';

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

const session = createNavaiMobileVoiceSession({
  transport: createReactNativeWebRtcTransport({ globals: webrtc }),
  backendClient
});

const response = await session.start({
  model: 'gpt-4o-realtime-preview',
  voice: 'alloy'
});

console.log('Backend functions:', response.backendFunctions);

​
Error Handling

​
Create Client Secret Errors

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

​
List Functions Errors

The listFunctions method never throws. Errors are returned as warnings: 
const { functions, warnings } = await backendClient.listFunctions();

if (warnings.length > 0) {
  console.warn('Failed to load some functions:', warnings);
}

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

​
Execute Function Errors

try {
  const result = await backendClient.executeFunction({
    functionName: 'get_weather',
    payload: { location: 'SF' }
  });
} catch (error) {
  // HTTP error, invalid response, or function execution error
  console.error('Function execution failed:', error.message);
}

​
API Endpoints

The backend client expects these endpoints:

​
POST /navai/realtime/client-secret

Create a realtime client secret. Request: 
{
  "model": "gpt-4o-realtime-preview",
  "voice": "alloy",
  "instructions": "You are a helpful assistant."
}
Response: 
{
  "value": "secret_abc123",
  "expires_at": 1234567890
}

​
GET /navai/functions

List available backend functions. Response: 
{
  "items": [
    {
      "name": "get_weather",
      "description": "Get current weather",
      "source": "backend"
    }
  ],
  "warnings": []
}

​
POST /navai/functions/execute

Execute a backend function. Request: 
{
  "function_name": "get_weather",
  "payload": { "location": "San Francisco" }
}
Response: 
{
  "ok": true,
  "result": { "temperature": 68, "condition": "sunny" }
}
Error Response: 
{
  "ok": false,
  "error": "Function not found",
  "details": "No function named 'get_weather'"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us