Mobile Voice and Chat Widget

An agent

A Webcall or voice agent; the app’s calls and chats go to it.

Its webcall key

The agentId and the Bearer key from the agent’s embed snippet.

Your app allowed

Each bundle or application ID, per platform and build flavor.

@ringg/react-native runs the widget in a React Native or Expo app with native views. You also need React 18+ and React Native 0.73+, in a development build or a bare app. Expo Go can’t load the native LiveKit modules, so use an Expo development build.Files you touch, depending on your setup:

app.json

App.tsx

ios

YourApp

Info.plist

android

app

src

main

AndroidManifest.xml

Install

npm install @ringg/react-native

Then install the three native modules. Autolinking only links native code in your app’s own node_modules, so the package can’t bundle them:

npx expo install @livekit/react-native @livekit/react-native-webrtc react-native-svg

npm install @livekit/react-native @livekit/react-native-webrtc react-native-svg

The config prop used below needs 0.4.0 or newer; on 0.3.0 you build the controller yourself.

Platform setup

Voice calls need a microphone, background audio and the native transport’s own manifest entries. Text chat needs none of it.

Expo

Add the plugin to app.json and rebuild the development build. It applies everything the widget needs, on both platforms.

app.json

{
  "expo": {
    "plugins": ["@ringg/react-native"]
  }
}

To change the microphone prompt your users see:

app.json

{
  "expo": {
    "plugins": [["@ringg/react-native", { "microphonePermissionText": "Talk to support." }]]
  }
}

Bare React Native

Bare apps have no config plugins, so add the same values by hand.

ios/YourApp/Info.plist

<key>NSMicrophoneUsageDescription</key>
<string>Voice calls use the microphone.</string>
<key>UIBackgroundModes</key>
<array><string>audio</string></array>

android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Pass a config and make the widget the last child of your root view, so its floating trigger and panel draw over the rest of the app. It opens its own connection and handles the microphone, and releases both when it unmounts.

App.tsx

import { Platform, View } from "react-native";
import { RinggWidget, appOrigin } from "@ringg/react-native";

const BUNDLE_ID = Platform.OS === "android" ? "com.acme.app" : "com.acme.App";

export const App = () => (
  <View style={{ flex: 1 }}>
    <YourApp />
    <RinggWidget
      config={{
        agentId: "your-agent-id",
        authorization: "Bearer your-webcall-public-key",
        clientOrigin: appOrigin(BUNDLE_ID),
        title: "Support",
        description: "How can we help?",
        defaultTab: "text", // or "audio"
      }}
    />
  </View>
);

Tapping the trigger opens the panel, and a chat or call connects to your agent.

Hand the install to Claude or Cursor. Fill in the agent ID, key and bundle IDs first.

Open in Cursor

Caller identity

The backend allow-lists an agent’s callers by the Origin header. Browsers attach one automatically, which is how domain whitelisting works for the web widget. Native HTTP sends nothing, so a webcall request without a caller identity is refused before authentication is even considered.

Response	Meaning
`400 Origin header is required`	No caller identity was sent.
`403 Client '…' is not allowed to initiate webcall`	One was sent, but it is not on the agent’s allowed clients list.
`401 Invalid credentials`	The identity was accepted, but the token is wrong for that environment.

Add the value to the agent’s allowed clients: open the agent, then Embed & Widgets → Install & domains → Allowed clients. Application ids differ per platform and per build flavor (.debug, .staging, .dev), so every build you ship needs its own entry. The value that was sent appears in the refused-call response, ready to paste.

Hybrid WebView runtimes report a shared identity (capacitor://localhost, ionic://localhost, file://) that is the same for every app built on that runtime. Allowing one admits all of them.

On React Native you pass the identity explicitly: appOrigin(BUNDLE_ID) in App.tsx above builds the <platform>://<bundleId> string, android://com.acme.app for that example. React Native can’t read the bundle ID without a native module, so pass it in: a constant, or a value from your app config, is enough. expo-application can read it from the OS, but it is native code, so adding it means rebuilding the app.

Notification sound

React Native has no built-in audio playback, so the widget plays no reply sound unless you pass a player through ports:

import { createAudioPlayer } from "expo-audio";
import { createNotificationPlayer, DEFAULT_CONFIG, RinggWidget } from "@ringg/react-native";

const notification = createNotificationPlayer(DEFAULT_CONFIG.notificationTuneUrl, (url) => createAudioPlayer(url).play());

<RinggWidget config={config} ports={{ notification }} />;

ports overrides anything the widget wires by default, and leaves the rest alone.

Testing hooks

Nodes carry a testID named after the web widget’s data-ringg attribute with a ringg- prefix: ringg-trigger-button, ringg-widget-root, ringg-header-title, ringg-message-input, ringg-end-call-confirm. header-status has no counterpart; its text is the surrounding node’s accessibilityLabel.

Verify the integration

The app is a development build, not Expo Go.
The trigger appears above your app content on both platforms.
Voice mode prompts for microphone permission and can start and end a call on a real device.
Every shipped flavor’s bundle ID is under Allowed clients.
Unmount the screen during a call and confirm the microphone indicator clears.

Known issues

No frosted-glass blur behind the header and composer; those surfaces are near-opaque.
The typing indicator has no gradient shimmer on the text; the ellipsis animates instead.
Agent replies render bold, italic, inline code, links, lists, headings, code blocks, blockquotes and rules. Markdown tables show as plain text.
Voice is unreliable on emulators: Android emulator networking often can’t set up the media connection, and iOS simulators have no microphone. Test voice on a real device.

Next steps

Configure the widget

Every option, its type and its default.

Handle events and actions

Lifecycle events, controller methods, agent actions.

Build agents

Inventory

Deploy

Monitor

Manage account

Ringg Labs

Mobile app install

Before you start

An agent

Its webcall key

Your app allowed

Install

Platform setup

Expo

Bare React Native

Mount the widget

Caller identity

Notification sound

Testing hooks

Verify the integration

Known issues

Next steps

Configure the widget

Handle events and actions

​Before you start

An agent

Its webcall key

Your app allowed

​Install

​Platform setup

​Expo

​Bare React Native

​Mount the widget

​Caller identity

​Notification sound

​Testing hooks

​Verify the integration

​Known issues

​Next steps

Configure the widget

Handle events and actions

Before you start

Install

Platform setup

Expo

Bare React Native

Mount the widget

Caller identity

Notification sound

Testing hooks

Verify the integration

Known issues

Next steps