React Native Widget Events and Control

Once the widget is mounted, the controller is your handle on it: subscribe to what the conversation is doing, drive the panel from your own UI, and react to actions the assistant fires.

Getting the controller

<RinggWidget config /> builds the controller for you. onReady hands it back:

const [controller, setController] = useState<RinggWidgetController | null>(null);

<RinggWidget config={config} onReady={setController} />;

It fires once, after the widget’s first render, and the widget destroys the controller when it unmounts. Everything on this page works off that value.

If you built the controller yourself and passed it as controller instead of config, you already have it, and its lifecycle is yours: call destroy() when you are done.

Lifecycle events

The widget emits five lifecycle events. The names and payloads are identical on every platform; only the delivery mechanism differs (browser CustomEvent on the web, an in-memory bus on React Native and Flutter).

Event	Fires when	Payload
`ringg:widget_status`	The panel opens or closes.	`status`: `"maximised"` or `"minimised"`. `mode`: `"audio"` or `"text"`.
`ringg:conversation_status`	A voice or chat conversation starts or ends.	`status`: `"started"` or `"ended"`. `mode`: `"audio"` or `"text"`. `callId`: string.
`ringg:feedback_status`	The user submits or skips the post-call feedback screen.	`status`: `"submitted"` or `"skipped"`. `callId`: string. `rating`: number, only when submitted.
`ringg:calendar_booking`	A calendar component is shown, a slot is confirmed, or booking fails.	`status`: `"shown"`, `"confirmed"` or `"failed"`. `componentId`: string. `slotId`: string, optional. `message`: string, optional.
`ringg:component_acknowledgement`	The user responds to an interactive component (form submit, button tap, slot pick).	`componentName`: string. `componentId`: string. `status`: string.

ringg:calendar_booking and ringg:component_acknowledgement only fire when the assistant sends interactive components. An assistant configured for plain voice or text never emits them.

React Native has no DOM, so events arrive on the controller’s in-memory bus. on returns an unsubscribe function.

useEffect(() => {
  const unsubscribe = controller.eventBus.on(
    "ringg:conversation_status",
    ({ status, mode, callId }) => {
      analytics.track(`call_${status}`, { mode, callId });
    },
  );

  return unsubscribe;
}, [controller]);

Subscribe in an effect and return the unsubscribe function. Handlers registered during render accumulate on every re-render and fire multiple times per event.

Controller methods

Call these to drive the widget from your own buttons, deep links or navigation events.

Method	Effect
`openWidget()`	Opens the panel.
`minimizeWidget()`	Closes the panel back to the trigger.
`handleTriggerClick()`	What the built-in trigger does: toggles the panel, or starts the conversation directly when `bypassStartScreen` is set.
`startCall(mediaType)`	Starts a conversation in `"audio"` or `"text"`. Requests microphone permission for audio.
`endCall()`	Ends the conversation and releases the microphone.
`sendMessage(text)`	Sends a chat message as the user.
`sendSlashCommand(command)`	Runs one of the commands from `enabledSlashCommands`.
`submitFeedback(rating, comment)`	Submits the post-call feedback.
`skipFeedback()`	Dismisses the feedback screen.
`destroy()`	Tears the controller down and releases the microphone. Call on unmount.

<Pressable onPress={() => controller.openWidget()}>
  <Text>Talk to support</Text>
</Pressable>

The controller also exposes methods for component responses, Block Kit actions and dynamic-data extensions. The bundled widget calls those on itself while rendering interactive components, so a normal integration does not need them.

Reading state

Each store has a hook that re-renders your component when its snapshot changes. Use these to build your own UI, or to mirror the widget’s state elsewhere in your app.

Hook	Snapshot
`useRinggSession(controller)`	`phase` (`"idle"`, `"starting"`, `"live-optimistic"`, `"connected"`), `isLoading`, `isSessionLive`, `connectionState` (`"disconnected"`, `"connecting"`, `"connected"`, `"reconnecting"`), `error`.
`useRinggShell(controller)`	`viewState` (`"closed"`, `"open"`, `"feedback"`), `currentCallId`, `callMode`.
`useRinggMessages(controller)`	`messages`, the chat thread.
`useRinggTyping(controller)`	`isTyping`, true while a reply is pending.
`useRinggComponents(controller)`	`completedFlowIds`, interactive flows the user has finished.
`useRinggSlashCommands(controller)`	`commands` currently offered in the composer.

const { isSessionLive, connectionState } = useRinggSession(controller);
const { messages } = useRinggMessages(controller);

return <Badge live={isSessionLive} reconnecting={connectionState === "reconnecting"} />;

Each message carries name, message, isSelf, timestamp, an optional sourceUrl for retrieved sources, and componentType with componentData when the message renders a component instead of text.

Interactive components

Assistants can send interactive components into the chat thread instead of plain text. All six types render natively, with no work on your side beyond mounting the widget.

Component	What the user sees
`calendar_booking`	Available slots to pick from, with a confirmation state.
`form`	A field set the user fills in and submits.
`buttons`	Quick-reply choices. The selection echoes back as a chat bubble.
`confirmation`	A yes or no decision with a summary of what is being confirmed.
`interactive_flow`	A multi-step sequence of the above, completed as one flow.
`blocks`	A Block Kit layout, for richer assistant-authored cards.

Configure which components an assistant can send from the dashboard. See Chat Components for authoring them.

Agent-triggered app actions

Assistants can fire host actions during a conversation, for example to open a screen or focus a field. On the web these become browser events. React Native has no ambient event bus, so you supply the handler through ports and receive the same payload.

import { createHostActionDispatcher, RinggWidget } from "@ringg/react-native";

const onDomAction = createHostActionDispatcher(({ name, payload }) => {
  if (name === "open_checkout") navigation.navigate("Checkout", payload);
});

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

Set eventLogs: { enabled: true } in config to also show each fired action as an inline pill in the chat thread, which makes these easy to watch while building.

Ports reference

ports overrides what the widget wires on its own. Every entry is optional: supply one and yours is used, leave it out and the default applies.

Port	Default	Override it to
`transport`	A LiveKit connection the widget owns	Bring your own adapter, or a room shared with the rest of your app.
`urlResolver`	The Ringg endpoints, selected by `config.mode`	Point at a different backend.
`micPermission`	The native permission prompt	Gate access yourself, or show your own explanation first.
`notification`	Silent	Play a reply sound, see notification sound.
`onDomAction`	Unset. Actions are acknowledged and dropped	Handle agent-triggered app actions.
`eventBus`	Created for you	Share one bus with other code.
`clock`	System clock	Inject time, for tests.

ports is read once, when the widget builds the controller. Changing it later has no effect; changing config rebuilds the conversation from scratch.

Owning the lifecycle yourself

When the widget cannot own the transport, build the controller and pass that instead. defaultUrlResolver keeps the Ringg endpoints without you naming them:

import { RinggWidget, createLiveKitTransport, createNativeMicPermission, createRinggWidgetController, defaultUrlResolver } from "@ringg/react-native";

const livekit = createLiveKitTransport();
const controller = createRinggWidgetController(config, {
  transport: livekit.transport,
  urlResolver: defaultUrlResolver,
  micPermission: createNativeMicPermission(),
});

<RinggWidget controller={controller} room={livekit.room} />;
// Yours to build, yours to release: controller.destroy(); livekit.dispose();

QA checklist

Open and close the panel once, then confirm one ringg:widget_status event per action.

Start and end one conversation, then confirm ringg:conversation_status carries a callId.

Navigate away and back, then confirm listeners are not duplicated.

Submit and skip feedback in separate runs if the feedback screen is enabled.

Unmount the screen during a call and confirm the microphone indicator clears.

Get Started

API Reference

Webhooks Setup

Telephony Integration

MCP Server

External Integrations

Privacy and Compliance

React Native Widget Events and Control

Getting the controller

Lifecycle events

Controller methods

Reading state

Interactive components

Agent-triggered app actions

Ports reference

Owning the lifecycle yourself

QA checklist

​Getting the controller

​Lifecycle events

​Controller methods

​Reading state

​Interactive components

​Agent-triggered app actions

​Ports reference

​Owning the lifecycle yourself

​QA checklist

Getting the controller

Lifecycle events

Controller methods

Reading state

Interactive components

Agent-triggered app actions

Ports reference

Owning the lifecycle yourself

QA checklist