> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md
# Mobile widget configuration
> Reference for every RinggWidgetConfig option in the Ringg AI React Native and Flutter widgets: identity, panel content, variables, theme, buttons and defaults.
export const RelatedTopics = ({items}) =>
;
`RinggWidgetConfig` controls how the widget looks and starts in your app; the agent's prompt, voice and tools stay in the dashboard. Only `agentId` is required. Every other field falls back to a default generated from one source for all platforms, so the web, React Native and Flutter widgets behave identically when a field is left unset; theme values with no default listed fall back to the packaged Ringg palette. Pick your framework with the switcher next to the table of contents, and [install the package](/documentation/deploy/web-and-apps/mobile-apps/install) first.
`RinggWidgetConfig` is the object you pass to `` from `@ringg/react-native`.
```tsx theme={null}
```
## Identity and auth
`authorization` and `clientOrigin` ship inside your app and can be extracted from it. Use the agent's webcall public key. The config type also accepts `xApiKey`; never put your workspace [API key](/documentation/manage-account/api-key) there, because it isn't limited to one agent or to your **Allowed clients**.
The agent to load.
`Bearer `, from the agent's embed snippet.
Caller identity sent as `Origin`, built with `appOrigin(BUNDLE_ID)`. Required for real calls; see [Caller identity](/documentation/deploy/web-and-apps/mobile-apps/install#caller-identity).
Leave it unset.
## Panel content and mode
Heading on the start screen and header.
Supporting copy on the start screen.
Which mode the panel opens in.
Hides the audio/text switch, pinning the widget to `defaultTab`.
Mounts the panel already open, with no trigger.
A trigger tap starts the conversation in `defaultTab` immediately.
Skips the post-call rating screen.
Logo shown in the header.
Sizing and background for the logo.
Words cycled in the pending-reply indicator.
Replaces the default legal text shown before a conversation. Words in `text` that match a key in `links` link to that URL.
## Variables
`variables` fill the agent's [variables](/documentation/build-agents/customize-agent-behaviour/custom-variables). Values are sent as given, so strings, numbers, booleans, objects and arrays all work. Set them at controller creation; to change them for a new conversation, create a new controller.
```tsx theme={null}
variables: {
callee_name: "John",
account_id: "ACC-42",
is_premium: true,
cart: { items: 3, total: 149.5 },
}
```
## Theme
Colors take any CSS color string; `primaryColor` and `agentBubbleColor` also accept CSS gradients.
Accent for buttons, selected states and the trigger.
Text on primary-colored surfaces.
Panel background.
Cards, inputs and the user message bubble.
Agent bubble background. An empty string renders agent replies without a bubble.
Body text.
Secondary text.
Borders and dividers.
Validation and danger states.
Success states.
Button corner style.
Global corner radius, for example `"12px"`.
Font family, 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
`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.
The floating trigger.
Custom trigger icon.
Icon size in points.
The in-call mute button.
Label on the start-call button.
Call button styling.
Label on the start-chat button.
Chat button styling.
## Voice call view
Shows the audio visualizer during a call. If you pass your own `controller`, pass `room` too.
Shows the live transcript during a call.
## Feedback screen
Heading on the rating screen.
Supporting copy.
Number of stars offered.
Selected and unselected star colors.
Comment field placeholder.
Submit button label.
Submit button styling.
## Chat extras
Commands offered in the composer, merged with any the agent returns at call start. Each is `{ tool_type, command, display_name, description }`.
Shows inline pills in the thread when the agent fires a host action.
Appends the action id to each pill. Useful while debugging.
Sound played on an incoming reply. On React Native it plays only with a player wired through `ports`; see [notification sound](/documentation/deploy/web-and-apps/mobile-apps/install#notification-sound).
## Web-only options
`widgetPosition` and `innerWindowProps` exist on the type because the config is shared with the web widget. They are ignored on React Native: the native layout places the trigger and panel, and there is no resizable window to size.
`RinggWidgetConfig` is the first argument to `RinggWidgetController` in `ringg_flutter`; every field except `agentId` is nullable.
```dart theme={null}
final controller = RinggWidgetController(
const RinggWidgetConfig(
agentId: 'your-agent-id',
authorization: 'Bearer your-webcall-public-key',
title: 'Support',
defaultTab: MediaType.text,
),
ControllerPorts(transport: transport.transport),
);
```
## Identity and auth
`authorization` ships inside your app and can be extracted from it. Use the agent's webcall public key. The config also accepts `xApiKey`; never put your workspace [API key](/documentation/manage-account/api-key) there, because it isn't limited to one agent or to your **Allowed clients**.
The agent to load.
`Bearer `, from the agent's embed snippet.
Pins the caller identity sent as `Origin`. Derived from the running app when null; see [Caller identity](#caller-identity).
Leave it null.
## Panel content and mode
Heading on the start screen and header.
Supporting copy on the start screen.
`MediaType.audio` or `MediaType.text`. Which mode the panel opens in.
Hides the audio/text switch, pinning the widget to `defaultTab`.
Mounts the panel already open, with no trigger.
A trigger tap starts the conversation in `defaultTab` immediately.
Skips the post-call rating screen.
Logo shown in the header.
Sizing and background for the logo.
Words cycled in the pending-reply indicator.
Replaces the default legal text shown before a conversation. Words in `text` that match a key in `links` link to that URL.
## Variables
`variables` fill the agent's [variables](/documentation/build-agents/customize-agent-behaviour/custom-variables). `WidgetVariables` is `Map`, and values are sent as given, so any JSON value works. Set them when you build the controller; to change them for a new conversation, build a new controller.
```dart theme={null}
RinggWidgetConfig(
agentId: 'your-agent-id',
variables: {
'callee_name': 'John',
'account_id': 'ACC-42',
'is_premium': true,
'cart': {'items': 3, 'total': 149.5},
},
)
```
## Theme
`theme` takes a `WidgetTheme`. Colors are CSS color strings, not Dart `Color` objects, so the same values work on web, React Native and Flutter. `primaryColor` and `agentBubbleColor` also accept CSS gradients.
```dart theme={null}
theme: const WidgetTheme(
primaryColor: '#9AADEC',
backgroundColor: '#FFFFFF',
buttonStyle: ButtonStyle.pill,
borderRadius: '12px',
),
```
Accent for buttons, selected states and the trigger.
Text on primary-colored surfaces.
Panel background.
Cards, inputs and the user message bubble.
Agent bubble background. An empty string renders agent replies without a bubble.
Body text.
Secondary text.
Borders and dividers.
Validation and danger states.
Success states.
`rounded`, `pill` or `square`.
Global corner radius, for example `'12px'`.
Font family. Must be a family declared in your `pubspec.yaml`.
## Buttons
`PortableStyles` is the cross-platform style subset: `height`, `width`, `backgroundColor`, `padding`, `borderRadius`. Sizes accept a number or a CSS string, so `'48px'` and `48` both work.
The floating trigger.
Custom trigger icon.
Icon size, as a number or a CSS size string.
The in-call mute button.
Label on the start-call button.
Call button styling.
Label on the start-chat button.
Chat button styling.
## Voice call view
Shows the audio visualizer during a call. Needs `transport` passed to `RinggWidget`.
Shows the live transcript during a call.
## Feedback screen
Heading on the rating screen.
Supporting copy.
Number of stars offered.
Selected and unselected star colors.
Comment field placeholder.
Submit button label.
Submit button styling.
## Chat extras
Commands offered in the composer, merged with any the agent returns at call start.
Shows inline pills in the thread when the agent fires a host action.
Appends the action id to each pill. Useful while debugging.
Sound played on an incoming reply. Needs a `notification` port with a player; see the [ports reference](/documentation/deploy/web-and-apps/mobile-apps/events#ports-reference).
## Web-only options
`widgetPosition` and `innerWindowProps` exist on the type because the config is shared with the web widget. They are ignored on Flutter: the Flutter layout places the trigger and panel, and there is no resizable window to size.
## 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 Flutter this is handled for you. The package reads the running app's id through `package_info_plus` and sends `://`:
| Platform | `Origin` sent |
| - | - |
| Android | `android://` |
| iOS | `ios://` |
| macOS, Windows, Linux | `macos://…`, `windows://…`, `linux://…` |
Set `clientOrigin` only when you want to pin one value, for example a single canonical string across build flavors. It wins over the derived one.
```dart theme={null}
RinggWidgetConfig(
agentId: 'your-agent-id',
clientOrigin: 'android://com.yourcompany.yourapp',
)
```
Supplying your own `ControllerPorts(httpClient: …)` opts out of the default header. Wrap your client to keep it:
```dart theme={null}
ControllerPorts(
transport: transport.transport,
httpClient: appOriginHttpClient(inner: yourClient),
)
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.