@opencx/widget-react-headless
v5.14.1
Published
Headless React helpers and hooks.
Keywords
Readme
OpenCX Widget - React Headless
Headless React helpers and hooks.
For more information, check the documentation
Selectable questions
A custom client must render question choices, collect selections or free text, and submit the answer before declaring support:
<WidgetProvider
components={yourComponents}
options={{
token: 'YOUR_WIDGET_TOKEN',
capabilities: { structuredQuestions: true },
}}
>
<YourChat />
</WidgetProvider>Omitting this capability leaves the structured question tool unavailable. Ordinary text questions remain available. The organization must also enable Selectable questions. The built-in Widget declares support automatically for its default question component. If you replace agent_chat_questions, explicitly declare support after implementing the replacement.
Delivery, activity and renderer support
These options are included in the next beta after 5.0.0-beta.1:
<WidgetProvider
components={yourComponents}
options={{
token: '<WIDGET_TOKEN>',
streaming: false,
presentation: { toolActivity: 'hidden', reasoning: false },
}}
>
<YourChat />
</WidgetProvider>streaming defaults to false, preserving v4 polling without changing the server's agent version. Set streaming: true to opt into streaming when the backend supports it. Personal service connections also require capabilities.connections: true.
The organization controls maximum activity visibility. An embed may narrow
toolActivity to status (name and status without inputs/results) or hidden,
and disable reasoning. It cannot override an organization restriction.
Tools still execute when their activity is hidden. The backend applies the same
limits to live replies, reconnects and history; the default is status-only
activity and hidden reasoning.
A headless client does not declare renderer support automatically. Set
capabilities.structuredQuestions, capabilities.richReplies, or
capabilities.pageEffects to true only after implementing that interaction.
These capabilities also require the organization's feature and streaming;
polling receives completed replies without structured interactions. Ordinary
clarifying questions in text do not require a selectable-question renderer.
Interactive question and highlight payloads remain available when activity is
hidden because they drive the customer-facing UI.
Changing options on an existing provider updates subsequent requests without
resetting its session. A delivery change waits for accepted messages, queued
messages and reply reconciliation to finish on their current transport.
Streaming reconnects and history fetches include the current presentation
opt-outs. Changing visibility refreshes existing history; useAgentChatUi()
immediately hides opted-out activity in both live and cached turns, including
while that refresh is pending or fails. Integrations keeping a separate cache
can use applyPresentation(items, presentation) to apply the same display rules.
React Native
Streaming in React Native needs Expo SDK 52 or later and three things from the app:
import { fetch as expoFetch } from 'expo/fetch';
<WidgetProvider
components={yourComponents}
options={{
token: '<WIDGET_TOKEN>',
streaming: true,
streamingFetch: expoFetch as typeof fetch,
}}
>
<YourChat />
</WidgetProvider>;streamingFetch: React Native's built-in fetch cannot read a response while it arrives. Expo SDK 57 installsexpo/fetchas the global fetch (unlessEXPO_PUBLIC_USE_RN_FETCHis set), so therestreamingFetchcan be left out. Every other request keeps using the global fetch. If you wrapexpoFetch(to add headers or logging), return its response unchanged. React Native's globalResponsehas no readable body, so the widget cannot read a response rebuilt withnew Response(...). It then reads the reply again through the global fetch and logs a warning once; where the global fetch cannot stream either, the reply appears once it is saved.- Globals: the widget needs
crypto.getRandomValues, which React Native does not provide. Installreact-native-get-random-valuesand import it first in your entry file. The stream reader also usesstructuredCloneandTextDecoderStream; Expo SDK 57 has both, and older runtimes need polyfills installed at startup, before the widget is imported. - Resuming a dropped reply: browsers resume when the tab is visible again or
the network returns. React Native has neither event, so call
useAgentChatUi().resumeInterruptedTurn()whenAppStatebecomesactiveand when connectivity returns. It does nothing unless the last reply was cut off.
