OpenMax
Free Trial

FAQ

Common integration problems and how to fix them.

FAQ

The chat has no styles

The SDK stylesheet is not loaded, or the components are not inside ChatRoot. The stylesheet applies only inside the .omx-chat component roots that SDK components bring along inside ChatRoot. Check that your global CSS imports @openmaxai/chat-sdk/styles.css, that the CSS file itself is imported, and that the chat is wrapped in <ChatRoot>; see Installation.

Components show translation keys

I18nextProvider is missing. A few components (mention panel, group management, floating and drawer surfaces) read strings through useTranslation, so wrap the tree in <I18nextProvider i18n={createChatI18n({ locale: "en-US" })}> (I18nextProvider from react-i18next, createChatI18n from @openmaxai/chat-sdk). See Internationalization.

Invalid hook call

Two copies of React are loaded. With Vite, set resolve.dedupe: ["react", "react-dom"]; see Installation · Configure your bundler.

Using it without a backend

Build a host from in-memory functions plus createLocalPorts, as in the Quick start. Every demo on this site works this way.

Using your own backend

Implement the required identity, messaging and inboundDelivery capabilities, add conversations if you show the conversation list, and take the other required ones from createLocalPorts. See Connect your own backend. Or write an adapter and pass it to createChatHost({ adapter }), which builds the host from it; the same guide covers both.

Mobile support

Yes, with no device switch to pass. Components switch layout by the width of their own container (the narrow layout below 768 px) and choose touch interactions by input type; see Components · Responsive behavior. @openmaxai/chat/surfaces also provides a bottom drawer, ChatMobileDrawer; whether to use it is up to your app.

Dark mode

Add the dark class to an ancestor, usually <html>. The chat does not follow prefers-color-scheme on its own. See Theming.

A feature is missing

Optional features appear only when the host provides their capability:

Feature Capability
"@me" jump mentions
# work-item references workItems
Agent model selector agentConfig
Create group, group info panel groupManagement
Card buttons and options cards
Profile card on avatars profileCard
Clickable images mediaViewer
Reactions, recall, edit, read receipts The matching optional messaging methods
Attachment button attachments with an attachment limit above 0

Which of these the host from createChatHost provides is on Known limitations · Default host; its uploads need <ConversationScope> around the thread. See Capabilities.

Own messages briefly appear as someone else's

createChatHost fetches the current user after the first render, so the user id is briefly empty; <ChatProvider> re-renders once it arrives.

Can I see what an agent is doing, and stop it?

Yes. Once the host provides the agentRuns capability and the backend pushes agent_event frames, the message thread shows run progress, tool steps, streaming output and a stop button. See Connect your own backend. Planned

Is it on npm?

Yes. The packages are on npm as 3.0.0 prereleases (3.0.0-beta.*). Every export is @experimental and may change between prereleases, so pin an exact version and use the same one for every @openmaxai/chat* package; see Installation. Changes are recorded in the changelog.