Skip to main content

​
Mobile SDK Overview

The @navai/voice-mobile package provides voice-first AI navigation capabilities for React Native and Expo applications. It enables seamless integration of OpenAI’s Realtime API with mobile apps through WebRTC-based voice interactions.

​
What @navai/voice-mobile Provides

​
Core Features

  • React Native & Expo Support: Full compatibility with React Native 0.72+ and Expo development builds
  • Voice Agent Hook: Ready-to-use useMobileVoiceAgent React hook for managing voice sessions
  • WebRTC Transport: Mobile-optimized WebRTC transport layer using react-native-webrtc
  • Backend Integration: Built-in client for Navai backend routes and function execution
  • Route Navigation: Voice-controlled navigation to app routes
  • Function Execution: Execute frontend and backend functions through voice commands
  • Permission Handling: Automatic microphone permission requests for Android and iOS

​
Architecture

The mobile SDK consists of several key components: 
import {
  useMobileVoiceAgent,           // React hook for voice sessions
  createReactNativeWebRtcTransport, // WebRTC transport layer
  createNavaiMobileVoiceSession,    // Session management
  createNavaiMobileAgentRuntime,    // Agent runtime with tools
  createNavaiMobileBackendClient,   // Backend API client
} from '@navai/voice-mobile';

​
Installation

1

Install the package

Install @navai/voice-mobile and its peer dependencies:
npm install @navai/voice-mobile react-native-webrtc
The package requires react-native-webrtc version 124 or higher.
2

Link native dependencies

For React Native CLI projects:
npx pod-install
For Expo projects, see the Expo Setup guide.
3

Configure permissions

Add microphone permissions to your platform configuration files.iOS (ios/YourApp/Info.plist):
<key>NSMicrophoneUsageDescription</key>
<string>Navai needs microphone access for voice navigation</string>
Android (android/app/src/main/AndroidManifest.xml):
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

​
Key Differences from Web

The mobile SDK has several important differences from the web version:

​
Transport Layer

  • Mobile: Uses createReactNativeWebRtcTransport with react-native-webrtc
  • Web: Uses browser’s native WebRTC APIs
// Mobile
import { createReactNativeWebRtcTransport } from '@navai/voice-mobile';
const webrtc = require('react-native-webrtc');

const transport = createReactNativeWebRtcTransport({
  globals: {
    mediaDevices: webrtc.mediaDevices,
    RTCPeerConnection: webrtc.RTCPeerConnection,
  },
});

​
Permission Handling

  • Mobile: Explicit permission requests required (handled automatically by the hook)
  • Web: Permissions requested during getUserMedia call
The useMobileVoiceAgent hook automatically handles Android permission requests: 
// Mobile permissions are handled automatically
const { start, isConnected } = useMobileVoiceAgent({
  runtime,
  runtimeLoading,
  runtimeError,
  navigate,
});

// Permissions are checked and requested when calling start()
await start();

​
Session Management

  • Mobile: Uses NavaiMobileVoiceSession with mobile-specific configuration
  • Web: Direct browser API integration

​
Environment Configuration

Mobile apps use runtime configuration instead of environment variables: 
import { resolveNavaiMobileApplicationRuntimeConfig } from '@navai/voice-mobile';

const runtime = await resolveNavaiMobileApplicationRuntimeConfig({
  moduleLoaders: generatedLoaders,
  defaultRoutes: APP_ROUTES,
  env: {
    NAVAI_API_URL: 'https://your-backend.com',
    NAVAI_REALTIME_MODEL: 'gpt-realtime',
  },
});

​
Quick Start Example

Here’s a minimal example to get started: 
import React from 'react';
import { View, Button, Text } from 'react-native';
import { useMobileVoiceAgent } from '@navai/voice-mobile';
import { useNavigation } from '@react-navigation/native';

function VoiceButton() {
  const navigation = useNavigation();

  const { start, stop, isConnected, error } = useMobileVoiceAgent({
    runtime: yourRuntimeConfig,
    runtimeLoading: false,
    runtimeError: null,
    navigate: (path) => navigation.navigate(path),
  });

  return (
    <View>
      <Button
        title={isConnected ? 'Stop Voice' : 'Start Voice'}
        onPress={isConnected ? stop : start}
      />
      {error && <Text>Error: {error}</Text>}
    </View>
  );
}

​
Next Steps

React Native Setup

Complete guide to using the mobile SDK in React Native apps

Expo Setup

Configure Expo projects with development builds

WebRTC Transport

Deep dive into the WebRTC transport layer

Backend Integration

Learn about backend routes and functions

Build docs developers (and LLMs) love

Get started for freeTalk to us