@fishaudio/agent-widget-react-native is the React Native counterpart of the web widget. One component renders a floating button that opens a call panel with a live transcript, text input, mute, inline tool activity, an optional consent step, and a minimized in-call pill. It runs on the React Native SDK, so microphone permissions, the audio session, and background calls work the same way. To draw your own UI instead, use the SDK’s useConversation hook.
App.tsx
Prerequisites
- An agent with a published version.
- The React Native SDK set up: its native dependencies, the Expo config plugin or the bare React Native steps, the entry file, and a native build. Expo Go cannot run it.
- Your own backend to create session tokens, or a public agent.
Install
Add the widget andreact-native-svg, which draws its icons:
react-native-svg is a native module, so rebuild the app after installing it.
Connect
Pass exactly one of the two:sessionTokenProvider(recommended): a function that asks your backend for a session token and returns it. The backend holds the API key and callsPOST /v1/agent/sessions. It runs before every call. See Start a session.agentId: a public agent. If the agent has Restrict origins on, also passoriginwith one of its allowed origins, because an app sends noOriginof its own.
How it behaves
- Button and proactive bubble. A round button sits in the corner set by
position. WithproactiveMessageset, a bubble appears next to it afterproactiveDelayseconds. Dismissing the bubble hides it until the app restarts. - Panel. On phones (screens narrower than 600 pt) the panel is a full-screen sheet. On tablets it is a card in the corner. The Android back button minimizes it.
- Starting. “Start a voice chat” starts a voice call: the SDK asks for the microphone permission on Android, sets up the audio session, and runs the Android call service with the
callNotificationnotification. Typing a message instead starts a text chat without the microphone. The mute pill can turn the microphone on later. A text chat has no Android call service, so a microphone turned on there is silenced while the app is in the background. Voice calls started with the button keep it. - Consent. With
consenton, the first call waits for the user to agree. The answer lasts until the app restarts. To remember it across launches, passconsentStorage, for example AsyncStorage. - During a call. The header shows the status and timer, a mute pill, and a hang-up button. Minimizing keeps the call running and shows a pill with the timer and a hang-up button. Background calls work as described in Background calls.
- Dragging. With
draggable, the user can drag the button and the minimized pill. On release it snaps to the nearer side, stays clear of the insets, and keeps its place until the app restarts. Dragging hides the proactive bubble; a tap still opens the panel. On tablets, the card opens on the side the button was dragged to. - After a call. The transcript stays with a “Call ended” divider. The user can start a new call or keep typing.
Tool activity
Each tool call shows as an inline chip with its status. Tapping it reveals the call’s input, output, or error. A client tool that throws or times out marks its chip as failed; the call keeps running, andonError reports it. To keep tool data off the device, create sessions with tool_events: false on your backend, or set options.toolEvents = false in onCall for a public agent. See Tool call lifecycle.
Client tools
PassclientTools to handle the client tools your agent is configured with. Each function’s return value goes back to the agent as the tool result.
onCall runs right before each call starts. Change options to adjust anything, including callbacks.
Props
A ref exposes
expand(), which opens the panel as a tap on the button does:
Theming
theme takes any subset of these keys, applied over the light or dark defaults:
Differences from the web widget
- React Native has no audio levels, so the orb and the bars animate by the agent’s mode (listening, thinking, speaking) instead of following the voice.
- Colors come from
themeinstead of CSS custom properties, and there is a dark scheme. consentStoragereplaceslocalStorage. Without it, consent and the dismissed bubble last until the app restarts.- The error messages speak of the app and Settings, not the site and the browser.
- Public agents that restrict origins need
origin, since apps send noOrigin. draggableis React Native only.
Going further
React Native SDK
Setup, background calls, audio routes, and troubleshooting.
Client tools
Let the agent call functions in your app.
Authenticated sessions
Create session tokens on your backend.
Web widget
The same widget for websites.

