OpenGeniChat shows the user’s chats and the open conversation. The chat list is a sidebar when there is room and a drawer when there is not, so it fits a side panel or a full page. Users can start, rename, and archive chats.


Example: OpenGeniChat embedded in a support app. Acme Support is a demo host app, not part of Opengeni.
baseUrl is your proxy’s mount. The component creates the browser client and uses the workspace your proxy resolved for the signed-in user.
The new-chat composer is the same as the follow-up one: attachments, your conversationProps.composerProps, and the model picker when offered. Files attached to the first message are added to the new chat.
Live voice is off unless you turn it on, because each call is paid from your Opengeni credits per minute and asks the browser for the microphone. Pass conversationProps={{ realtimeVoice: true }}. The composer then shows a voice button when your workspace has a voice model available (for example hosted GPT Live). Starting voice in a new chat creates an empty conversation and starts the call there; typed text and attachments remain an unsent draft, not an invented first message. The user talks, the voice model answers, hands work to the agent in the same chat, and the transcript appears in the timeline.
The indicator shown while the agent starts says “Thinking…”. Use conversationProps={{ genieLoading: { phrases: ["One moment…"] } }} for your own copy, or genieLoading.render for your own visual.
While a new chat’s first turn starts, the conversation shows a startup row with the current step (queued, preparing the sandbox, contacting the model), the same row the Opengeni web app shows.
If your server creates the session itself, render the conversation as soon as the person sends, before that call returns: pass sessionId={null} and pendingPrompt={{ text, sentAt }}, then pass the session ID once you have it. It is the same conversation throughout, so their message and the startup row stay put and nothing flashes while history loads. The composer is disabled until the session exists. Pass pendingPrompt only for the prompt that creates the session; the conversation drops it once that session’s history loads or it opens a different session.
visitor: true from the proxy’s resolve. Visitors get no attach button (the proxy also refuses their uploads) unless you set visitorUploads: true.
If your app authenticates with a bearer token instead of cookies, pass it on every request and read it in the proxy’s resolve:
fetch instead when the token must be awaited. A client you pass with baseUrl is used instead of the one the component would create.
The list shows every chat the user can read; pass listProps={{ mineOnly: true }} for only their own, listProps={{ archive: false }} to hide “Archive” (it archives the chat for everyone after a short Undo window and needs control of the chat), and newChat={false} to hide “New chat”. Control the selection with sessionId and onSessionChange (for example from the URL).
For a single conversation, use SessionConversation. It includes streaming replies, tool activity, approvals, questions, attachments, the message queue, Steer, and Pause/Resume.
@opengeni/react/session-ui for the smallest bundle; it has no optional peer dependencies. To share one client across several components or use the headless hooks, wrap them in <OpenGeniProvider client={client} workspaceId={workspaceId}> instead of passing baseUrl.
Props
Remount the component when the signed-in user or tenant changes.
Hide agent signals from end users
Above the composer, the conversation shows how the agent works: the goal pill (for example “Goal · Paused · agent”) and, when you pass them inchromeProps,
counts of helper agents and running commands. People who just want an answer
often don’t need these. Turn them off with agentSignals={false}:
turnSummary facets. An automation run shows as its
one line and its answer, with no work row; a run that is still working, or
ends with a failure only an operator can fix, shows nothing. React Native’s
NativeSessionScreen takes the same agentSignals={false} for all of this,
and to hide its goal, agents and commands chips.
To hide only some of it, pass an object instead. Each switch defaults to
true, so name only what you hide:
For example, an assistant whose users should see queued messages and helper
agents, but not a “Goal · Paused” chip:
turnDetail stays on.
true and false keep their meaning: everything shown, or everything hidden.
NativeSessionScreen takes the same object for its chips and turn rows.
The row above the composer (queue, wait, goal and agents) sits in the same
readable column as the composer, so it lines up with the composer in a wide
panel. A className in chromeProps is added to that row; you no longer need
one to center it.
Automation runs in the chat
When an automation (a schedule or an event trigger) acts in a chat, the chat shows one centered line saying what happened, then the agent’s answer. The line is the automation’s name and what the event that started it says, for example “Ticket assigned to you: T-4907 Refund request from Contoso”, or just the name for a scheduled run. Name automations for the person reading the chat. The automation’s instructions are never shown; runs recorded before Opengeni kept the name read “Automation run”. A run with nothing for the person stays out of the chat. The agent is told to answer exactlyNO_REPLY when a run leaves nothing to see or do, and the chat
then draws neither the run’s line, its work nor its answer. A run that asks the
person something or needs them to connect an account always shows.
Such a run leaves no other trace for the person either: it does not mark the
chat unread, open an inbox reply item or send a phone notification. It stays
in the session’s history. When a run (or any turn) does answer, its phone
notification carries that answer, the same text the chat shows; events that
arrive close together start one run, so they give one answer and one
notification.
Lead the live turn row with your mark
While the agent works, the turn shows one live row, such as “Working · 8s”.turnSummary.renderLiveMark puts your own small mark, for example an animated
mascot, at the start of that row. It is called with the row’s state:
{ kind: "working" }, { kind: "waiting", waitingOn: "you" } when the wait
needs the reader (an approval or a question), { kind: "waiting" } for other
waits, or { kind: "paused" }. The mark goes away when the turn settles. Draw
it about 20 px tall so it fits the row; it is hidden from screen readers
because the row’s words already say what is happening. By default there is no
mark.
rolling: true when you pass turnSummary: it selects the per-turn
presentation that has the live row. On React Native, pass
renderLiveMark={(state) => <Mascot state={state.kind} />} to
NativeSessionScreen or MessageTimeline.
Keep a conversation across layouts
The default component needs no controller setup. If a conversation moves between a side panel and a full-page view, mountuseSessionConversation in a stable
parent and pass it to SessionConversationView. These are the same state and
view used by SessionConversation, not a second chat implementation.
composerOptions.sendExtras for application context and onSent for
post-acceptance notifications, not a custom send wrapper. The stock composer
continues to validate annotation-only messages, upload readiness, queueing and
retry identity. The same modelContext is captured for durable voice messages.
Notification exceptions are reported as browser errors; they cannot make an
accepted send appear failed. Context is ordinary model-visible content, not an
authorization mechanism or a place for secrets.
chromeProps, humanInputProps and approvalProps customize stock status
panels and decision presentation without replacing their action handlers.
timelineProps accepts domain-aware turnSummary, a renderAuthNeeded
connection action, and an emptyState; history, navigation and annotations
stay stock.
realtimeVoiceProps provides optional connected-account state and voice
autostart handoff; live voice remains opt-in as before.
A new conversation in your own layout
OpenGeniChat still needs no creation controller setup. Its new-chat state and
view are also available separately:
useNewConversation and render
NewConversationView with its creation result. An optional createSession
adapter receives the first message, an idempotency key, and browser choices
(files, model policy, or startMode: "realtime"). It returns the session ID;
the server still owns agent configuration, access, and application records.
For voice-first calls the first-message argument is empty. Do not manufacture
a prompt in the adapter.
The stock controller retains the exact in-flight request and adapter when an
outcome is unknown. Retry checks that request instead of creating another chat
from newer edits. A typed OpenGeniApiError with outcomeUnknown: false
releases a definitively rejected attempt. onCreated receives newer unsent
content in draft: pass it as composerOptions.initialDraft to the selected
conversation. The real server draft supplies its persistence revision. It also
receives realtimeModel for the optional voice-autostart handoff. OpenGeniChat
already handles both. New uploads added during creation must finish, be retried,
or be removed before the stock view switches to the created chat.
scopeKey resets a controller’s new draft when your host record changes. Changing
scope or unmounting never cancels a server-side creation or navigates another
scope to its late result. The controller holds active attempts in memory, not
in browser storage; a custom server with durable creation recovery should keep
its ordinary session discovery/reconciliation on the server. Browser markers
are not authorization. Keep the controller mounted for layout changes, and
remount on a signed-in user or tenant change.
NewConversation and NewConversationView accept labels for pending/retry
and upload-handoff copy. In OpenGeniChat, use newChatPending, newChatRetry,
and newChatFinishingUploads in labels.
Brand it
compiled.css is scoped to the components and needs no Tailwind. Out of the box it needs no extra cosmetic host CSS. To match your product, override the --og-* CSS variables on any ancestor:
--og-color-link colors text links in chat replies and across the components; they are always underlined too.
Dark is the default. Add data-og-theme="light" for the light theme and data-og-density="compact" for narrow panels:
tokens.css for every token.
Error copy
Error notices use neutral, brand-free text. To prefix or rewrite them, passformatError to the provider:
ErrorMessageFormatter has the signature (error: unknown, defaultMessage: string) => string | undefined. Returning undefined or an empty string, or a throwing callback, keeps the default. It receives the original error, so don’t log it in the browser.
Outside React, formatErrorMessage(error, fallback?) from @opengeni/sdk returns the same display text. Show that, not error.message.
Render your tools
Calls to your own MCP server can render as product UI. Tool names are<server id>__<tool name>:
Start sessions from the browser
Without a hook, the browser starts chats with Opengeni’s own create request, limited by the user’s permissions. To own chat setup on your server, add the proxy’screateSession hook. The browser then sends the first message and permitted choices; your hook returns the full request, so tools, skills, and authority stay on your server, and the proxy refuses the routes that would change that setup later:
startMode: "realtime", with no initial
message or first-message files. The same value reaches beforeForwardMessage
so an admission hook can distinguish empty creation from a text turn. Model
choices still require the proxy’s modelSelection option.
Links, artifacts, and Sites
File links download by file ID, andsandbox: links download files from the session’s sandbox for users with files:read.
To open artifacts and Sites, either route them to your own pages with resolveLink, or render SessionArtifactViewer from @opengeni/react/artifacts in onOpenArtifact (members need artifacts:read).
Other UI shapes
- Headless hooks from
@opengeni/react/sessionfor a different interaction model with the same behavior. - The SDK alone for a non-React frontend, a CLI, or automation. See the Vue recipe.
- The chat facade when you already have a chat UI. See Keep your existing chat UI.