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.
