@fishaudio/agent-react-native adds voice calls with your agent to a React Native app. The call runs on the same code as the Web SDK, so connection handling, transcripts, client tools, and end reasons behave the same. The hooks are the React SDK’s. On top of that, the package handles what phones need:
- The microphone permission on Android
- The platform audio session and routing (loudspeaker, earpiece, headsets)
- Background calls: an Android foreground service and iOS background audio
- An Expo config plugin for the native settings
React SDK
The hook API this package builds on.
Authenticated sessions
Create session tokens on your backend.
Web SDK reference
Events, client tools, and error codes.
Requirements
- A native build. WebRTC is a native module. In Expo, build with
npx expo run:ios/run:androidor EAS Build. Expo Go cannot run it (expo-dev-clientis optional). Bare React Native apps build as usual; see Bare React Native. - A physical device for anything involving the microphone.
- Your own backend to create session tokens, or a public agent. Never ship an API key inside an app.
- Tested with Expo SDK 58 and bare React Native 0.88,
@livekit/react-native3.1,@livekit/react-native-webrtc150.1, andlivekit-client2.20 to 2.23, on iOS 26 and Android 17. Other versions may work but are untested.
Install (Expo)
npx expo install adds the three config plugins to app.json for you. If you installed with npm or yarn instead, add them yourself:
app.json
npx expo run:ios --device or npx expo run:android --device. Rebuild whenever you add a package with native code. After changing a plugin or its options, run npx expo prebuild first: once the ios and android folders exist, run:ios and run:android do not apply plugin changes. A JavaScript reload picks up neither.
Android needs no configuration: the package’s manifest adds the microphone, audio, and foreground-service permissions and the service itself when the app is built.
Bare React Native
Without Expo, install the packages without the config plugins and set the native options yourself:1
Set up LiveKit
Follow the LiveKit React Native installation for its native setup. It replaces the two LiveKit and WebRTC config plugins. In short:
-
Android
MainApplication.kt: callLiveKitReactNative.setup(this, AudioType.CommunicationAudioType())inonCreate. -
iOS
AppDelegate.swift:import livekit_react_native, then callLivekitReactNative.setup()indidFinishLaunchingWithOptions. -
iOS
Podfile: LiveKit’s WebRTC pod comes from LiveKit’s own spec repo. Add both sources at the top, then runcd ios && pod install --repo-update:Podfile
2
Configure iOS
Add the microphone text, and the
audio background mode so calls continue in the background:Info.plist
3
Build
Android needs nothing extra: autolinking registers the package’s module, and its manifest brings the permissions and the foreground service. Build with
npx react-native run-ios or run-android.Set up the entry file
setupFishAgent() installs the WebRTC globals the SDK runs on. Call it before your app’s modules load: put it in a file of its own and import that file first in your entry file. A call in the entry file’s body is not enough, since every import in a file runs before its body. startSession also installs the globals if they are missing, so a forgotten call does not break calls, but code that touches WebRTC earlier would fail.
setupFishAgent.ts
create-expo-app template), also point main in package.json at the new file: "main": "index.ts".
Quick start
SupportCall.tsx
startSession asks for the microphone on Android the first time (iOS asks on its own when capture starts), so call it from a button press.
Start a session
An app starts a call in one of two ways, the same two the browser SDKs offer.From your backend (recommended)
When the user starts a call, the app asks your backend for a session token. The backend callsPOST /v1/agent/sessions with your API key and returns the response unchanged, and the app passes it to startSession({ sessionToken }). The endpoint is the same one web apps use; see Authenticated sessions for backend examples.
Two things differ from the browser:
localhostis the phone, not your computer. During development, use your computer’s LAN address, or on Android forward the port withadb reverse tcp:3001 tcp:3001.- iOS blocks plain
http://outside development builds. Serve the token endpoint over HTTPS.
Public agent
An agent with public access turned on takes sessions with just its id, with no API key and no backend:Origin header against the agent’s allowed origins. Browsers send their page’s origin themselves; an app sends none, so pass one that is on the list:
- Anyone with the agent id can start sessions, billed to you. An app can be unpacked, and any client can send any
Origin, so restricting origins does not make an agent private. Rate limits are the backstop, and public sessions accept only a few overrides. - Prefer your backend for production apps, especially with signed-in users: it decides who gets a token and can attribute sessions to your users.
useConversation(defaults?, options?)
The React SDK hook with the same arguments, return values, and lifecycle, plus:
Audio routes:
auto(default): a connected Bluetooth or wired headset, otherwise the loudspeaker.speaker: always the loudspeaker, even with a headset connected.earpiece: the phone’s receiver, for holding it to the ear.
Everything else (
status, mode, micMuted / setMicMuted, sendUserMessage, interrupt, session, client tools, callbacks, and errors) works as described in the React SDK and Web SDK pages. useAgentMessages and AgentSessionProvider are re-exported from the React SDK and work the same way.
Not available on React Native:
- The browser-only members of the React hook (
startAudio,setOutputVolume,setInputDevice,setOutputDevice). useAudioLevelsandAgentAudioVisualizer.- Starting calls with
AgentSessiondirectly. It is exported as a type only, forconversation.session. Start calls throughuseConversation, which also handles the permission, audio session, and call service.
Background calls
-
iOS: with the
audiobackground mode (on by default in the plugin), a call continues when the app goes to the background or the screen locks. The user can keep talking and hear the agent. - Android: during a call, the SDK runs a microphone foreground service with an ongoing notification. Android 14 and later silence an app’s microphone as soon as it leaves the foreground unless such a service runs.
- Google Play: the package adds a microphone-type foreground service and its permissions to your app. Declare its use in Play Console before publishing, as Google Play requires.
-
Android 13+ notifications: the call notification only shows if the app holds
POST_NOTIFICATIONS, which Android 13 and later grant at runtime. The SDK declares it but does not ask for it, so the prompt stays under your control. Without it, the service still runs and background capture still works; only the notification is hidden. To show it, ask before the first call:
Troubleshooting
Going further
Client tools
Let the agent call functions in your app.
Authenticated sessions
Create session tokens server-side.
Public agents
Public access, origin restriction, and rate limits.
Dynamic variables
Personalize each session at start time.

