Skip to main content
@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
Render it last in your root view so it floats above the app and stays mounted across screens. It covers the screen with a layer that lets touches through, so only its button and panel catch taps. Unmounting the widget ends its call.

Prerequisites

Install

Add the widget and react-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 calls POST /v1/agent/sessions. It runs before every call. See Start a session.
  • agentId: a public agent. If the agent has Restrict origins on, also pass origin with one of its allowed origins, because an app sends no Origin of its own.
The origin prop is experimental, like the SDK’s origin option, and may change in a minor release.
For a public agent, the widget also loads the agent’s widget settings from the dashboard (name, greeting, proactive message, consent, which features are on, UI strings). Props win over those settings.

How it behaves

  • Button and proactive bubble. A round button sits in the corner set by position. With proactiveMessage set, a bubble appears next to it after proactiveDelay seconds. 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 callNotification notification. 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 consent on, the first call waits for the user to agree. The answer lasts until the app restarts. To remember it across launches, pass consentStorage, 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, and onError 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

Pass clientTools 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 theme instead of CSS custom properties, and there is a dark scheme.
  • consentStorage replaces localStorage. 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 no Origin.
  • draggable is 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.