React Native Widget Configuration

This page is the complete reference for RinggWidgetConfig, the object you pass to <RinggWidget config />. Configure assistant behavior, tools and prompts in the dashboard; use this object for app-level runtime settings. See React Native for installation and the integration steps.

<RinggWidget
  config={{
    agentId: "your-agent-id",
    authorization: "Bearer your-webcall-public-key",
    clientOrigin: appOrigin(BUNDLE_ID),
    title: "Support",
    defaultTab: "text",
  }}
/>

Identity and auth

Option	Type	Notes
`agentId`	`string`	The assistant to load. Required.
`authorization`	`string`	`Bearer <webcall-public-key>`, generated per assistant in the dashboard and rotatable from there.
`clientOrigin`	`string`	Caller identity sent as `Origin`. Required for real calls, see Caller identity.
`mode`	`"dev" \| "stage" \| "prod"`	Which Ringg environment to call. Defaults to `prod`.

authorization and clientOrigin ship inside your app binary and can be extracted from it. Use only the webcall public key generated for that assistant, never a backend integration key, and keep the assistant’s allowed clients list tight.

Panel content and mode

Option	Type	Notes
`title`	`string`	Heading on the start screen and header.
`description`	`string`	Supporting copy on the start screen.
`defaultTab`	`"audio" \| "text"`	Which mode the panel opens in.
`hideTabSelector`	`boolean`	Hides the audio/text switch, pinning the widget to `defaultTab`.
`defaultExpanded`	`boolean`	Mounts the panel already open, with no trigger.
`bypassStartScreen`	`boolean`	A trigger tap starts the conversation in `defaultTab` immediately.
`bypassFeedbackScreen`	`boolean`	Skips the post-call rating screen.
`logoUrl`	`string`	Logo shown in the header.
`logoStyles`	`PortableStyles`	Sizing and background for the logo.
`typingWords`	`string[]`	Words cycled in the pending-reply indicator.

Variables

variables are forwarded to the assistant as custom_args_values and fill {{placeholders}} in its prompts. Values are sent verbatim, so strings, numbers, booleans, objects and arrays are all accepted.

variables: {
  callee_name: "John",
  account_id: "ACC-42",
  is_premium: true,
  cart: { items: 3, total: 149.5 },
}

Set variables at controller creation. To change them for a new conversation, create a new controller.

Theme

theme accepts thirteen fields. Colors take any CSS color string; primaryColor and agentBubbleColor also accept CSS gradients.

Option	Type	Applies to
`theme.primaryColor`	`string`	Accent for buttons, selected states and the trigger.
`theme.primaryTextColor`	`string`	Text on primary-colored surfaces.
`theme.backgroundColor`	`string`	Panel background.
`theme.surfaceColor`	`string`	Cards, inputs and the user message bubble.
`theme.agentBubbleColor`	`string`	Assistant bubble background. An empty string renders assistant replies bubble-less.
`theme.textColor`	`string`	Body text.
`theme.mutedTextColor`	`string`	Secondary text.
`theme.borderColor`	`string`	Borders and dividers.
`theme.errorColor`	`string`	Validation and danger states.
`theme.successColor`	`string`	Success states.
`theme.buttonStyle`	`"rounded" \| "pill" \| "square"`	Button corner style.
`theme.borderRadius`	`string`	Global corner radius, for example `"12px"`.
`theme.fontFamily`	`string`	Font family. Must be a font your app has already loaded.

fontFamily is resolved against fonts registered in your app. React Native does not fetch web fonts, so load the family through Expo Font or your native font assets first.

Buttons

Option	Type	Notes
`buttons.modalTrigger.styles`	`PortableStyles`	The floating trigger.
`buttons.modalTrigger.icon.url`	`string`	Custom trigger icon.
`buttons.modalTrigger.icon.size`	`number`	Icon size in points.
`buttons.mic.styles`	`PortableStyles`	The in-call mute button.
`buttons.call.textBeforeCall`	`string`	Label on the start-call button.
`buttons.call.textDuringCall`	`string`	Label once the call is live.
`buttons.call.styles`	`PortableStyles`	Call button styling.
`buttons.text.textBeforeCall`	`string`	Label on the start-chat button.
`buttons.text.textDuringCall`	`string`	Label once chat is live.
`buttons.text.styles`	`PortableStyles`	Chat button styling.

PortableStyles is the cross-platform style subset: height, width, backgroundColor, padding, borderRadius. Arbitrary CSS is not accepted, because these values are applied to native views.

Voice call view

Option	Type	Notes
`voiceCall.showAnimation`	`boolean`	Shows the audio visualizer during a call. Needs `room` passed to `<RinggWidget />`.
`voiceCall.showTranscript`	`boolean`	Shows the live transcript during a call.

Feedback screen

Option	Type	Notes
`feedbackScreen.title`	`string`	Heading on the rating screen.
`feedbackScreen.description`	`string`	Supporting copy.
`feedbackScreen.starsCount`	`number`	Number of stars offered.
`feedbackScreen.starsStyles.filledColor`	`string`	Selected star color.
`feedbackScreen.starsStyles.emptyColor`	`string`	Unselected star color.
`feedbackScreen.placeholder`	`string`	Comment field placeholder.
`feedbackScreen.submitBtnCTA`	`string`	Submit button label.
`feedbackScreen.submitBtnStyles`	`PortableStyles`	Submit button styling.

Set bypassFeedbackScreen: true to skip the screen entirely.

Chat extras

Option	Type	Notes
`enabledSlashCommands`	`SlashCommand[]`	Commands offered in the composer, merged with any the assistant returns at call start. Each is `{ tool_type, command, display_name, description }`.
`eventLogs.enabled`	`boolean`	Shows inline pills in the thread when the assistant fires a host action.
`eventLogs.showIds`	`boolean`	Appends the action id to each pill. Useful while debugging.
`notificationTuneUrl`	`string`	Sound played on an incoming reply. See notification sound, which needs a player wired up on React Native.

Web-only options

These exist on the type because the config is shared with the web widget. They are ignored on React Native, where the panel sizes itself to the device.

Option	Why it does not apply
`widgetPosition`	Trigger and panel placement is handled by the native layout.
`innerWindowProps`	There is no resizable window to size.

Defaults

Every optional field falls back to a shared default. These values are generated from one source for all platforms, so the web, React Native and Flutter widgets behave identically when a field is left unset.

Field	Default
`mode`	`prod`
`title`	`Ringg AI Support`
`description`	`Ringg AI offers 24/7 voice support to handle your business calls efficiently and professionally`
`defaultTab`	`audio`
`hideTabSelector`	`false`
`defaultExpanded`	`false`
`bypassStartScreen`	`false`
`bypassFeedbackScreen`	`false`
`voiceCall.showAnimation`	`false`
`voiceCall.showTranscript`	`true`
`notificationTuneUrl`	`https://assets.ringg.ai/audios/misc/widget_notification.mp3`
`typingWords`	`Thinking`, `Reasoning`, `Working on it`, `Almost there`
`eventLogs.enabled`	`false`

Theme values not listed here fall back to the packaged Ringg palette.

Caller identity

The backend allow-lists an assistant’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 assistant’s allowed clients list.
`401 Invalid credentials`	The identity was accepted, but the token is wrong for that environment.

Add the value to the assistant’s allowed clients under Agent → Webcall → Install & domains in the dashboard. 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, pass the identity explicitly. appOrigin builds the <platform>://<bundleId> string for you:

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

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

clientOrigin: appOrigin(BUNDLE_ID); // "android://com.acme.app"

The bundle id is a parameter because React Native cannot read it without a native module, and the package will not add one for a single string. Your app already declares it, so a constant or a read of your own app config is enough. expo-application reports the same value if you would rather ask the OS, but it is native code, so adding it means rebuilding the app.

Get Started

API Reference

Webhooks Setup

Telephony Integration

MCP Server

External Integrations

Privacy and Compliance

React Native Widget Configuration

Identity and auth

Panel content and mode

Variables

Theme

Buttons

Voice call view

Feedback screen

Chat extras

Web-only options

Defaults

Caller identity

​Identity and auth

​Panel content and mode

​Variables

​Theme

​Buttons

​Voice call view

​Feedback screen

​Chat extras

​Web-only options

​Defaults

​Caller identity

Identity and auth

Panel content and mode

Variables

Theme

Buttons

Voice call view

Feedback screen

Chat extras

Web-only options

Defaults

Caller identity