Skip to main content
@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
It works in Expo apps and in bare React Native apps. Expo is not required.

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:android or EAS Build. Expo Go cannot run it (expo-dev-client is 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-native 3.1, @livekit/react-native-webrtc 150.1, and livekit-client 2.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
Then build the native app with 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: call LiveKitReactNative.setup(this, AudioType.CommunicationAudioType()) in onCreate.
  • iOS AppDelegate.swift: import livekit_react_native, then call LivekitReactNative.setup() in didFinishLaunchingWithOptions.
  • iOS Podfile: LiveKit’s WebRTC pod comes from LiveKit’s own spec repo. Add both sources at the top, then run cd 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
With expo-router (the default 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. When the user starts a call, the app asks your backend for a session token. The backend calls POST /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:
  • localhost is the phone, not your computer. During development, use your computer’s LAN address, or on Android forward the port with adb 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:
If the agent has Restrict origins on, the platform checks the request’s 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:
The origin option is experimental and may change in a minor release: a dedicated way for apps to identify themselves may replace it.
Know what a public agent means before shipping one in an app:
  • 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.
The second argument takes mobile options: 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).
  • useAudioLevels and AgentAudioVisualizer.
  • Starting calls with AgentSession directly. It is exported as a type only, for conversation.session. Start calls through useConversation, which also handles the permission, audio session, and call service.

Background calls

  • iOS: with the audio background 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.