Connect to OpenMax
Point the chat at an OpenMax backend with createChatHost, render it, and handle tokens.
Connect to OpenMax
createChatHost from @openmaxai/chat-openmax/react returns a host (ChatHost) for the OpenMax backend. Install the packages and load the stylesheet (@openmaxai/chat-sdk/styles.css) first.
Create the host
src/chat-host.ts
import { createChatHost } from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "https://openmax.com", // REST base URL, without /api/v1
wsUrl: "wss://openmax.com/ws", // or realtime: "off"
auth: {
mode: "token",
getToken: async () => fetchShortLivedToken(), // your code
},
workspaceId: currentWorkspaceId, // sent as X-Workspace-ID when same-origin with baseUrl
orgId: currentOrgId, // sent as X-Org-ID
locale: "en-US", // bundled strings default to Chinese
});
createChatHostis synchronous: it validates the config, sends no request and does not callgetToken. Create it once, at module scope or in a memo.baseUrlis required; the SDK never reads environment variables.- Pass exactly one of
wsUrlorrealtime: "off"; neither or both throws. With"off", messages from others show up only after a reload.
OpenMax addresses
| Use | Address |
|---|---|
baseUrl (REST) |
https://openmax.com (without /api/v1). The SDK appends /api/v1/… (chat API) and /auth/… (token and realtime ticket exchange) |
wsUrl (realtime) |
wss://openmax.com/ws |
The examples on this page use these two addresses; same-origin proxies and your server-side forwarding forward to them too.
orgId is required with a personal API Key
The Key carries no organization, so the backend picks it from
X-Org-ID; without it/api/v1/conversationsreturns401. A session token that already carries an organization can omit it. The backend does not readworkspaceId(X-Workspace-ID), so it is optional, and the SDK does not send it cross-origin. Both options are experimental and may be renamed.
Server-side rendering and Next.js
Besides absolute URLs, baseUrl and wsUrl can be paths starting with / (such as /openmax-api and /openmax-ws), forwarded to OpenMax by a same-origin reverse proxy. A path is not resolved when the host is created but on first use (the first REST request, the first realtime connection), as new URL(path, location.origin), ignoring <base href>; wsUrl becomes wss: on an https: page and ws: on an http: page. The device id is also read on the first connection. So the host can be created at module scope, and server-side rendering does not touch window.
- Where
location.originitself is unusable (on the server; on a page whoselocation.originis"null"such asabout:blank; or on a page that is not http(s), such asfile:orchrome-extension:), the first request rejects with aChatSdkConfigErrornamingbaseUrl; a pathwsUrlopens no connection and does not reconnect, and the adapter reports once throughsink.erroran error withcodews_url_unresolved(itscauseis theChatSdkConfigErrornamingwsUrl); the chat UI keeps working, only without realtime. In development builds it also logs oneconsole.error(once per host) namingwsUrlwith the reason and the fix; production builds print nothing. In both casesgetTokenis not called. Sandboxed iframes are not in this group: theirlocation.originis the http(s) origin of the address (onlywindow.originis"null"), so paths resolve and requests go out as usual; whether they get through is up to the server's CORS. - A protocol-relative form such as
//host/apiis not special-cased: it follows the URL standard and points at that host with the page scheme (another origin, so the cross-origin requirements apply). Forms that do not start with/(api) throw when the host is created.
The recommended pattern for Next.js: a module marked "use client" also runs on the server during server-side rendering. Create the host at the top level of such a module, give REST a path, and forward it to OpenMax with rewrites:
src/chat-host.ts
"use client";
import { createChatHost } from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "/openmax-api",
wsUrl: "wss://openmax.com/ws", // or a same-origin path, see below
auth: {
mode: "token",
getToken: async () => fetchShortLivedToken(),
},
});
next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
async rewrites() {
return [
{ source: "/openmax-api/:path*", destination: "https://openmax.com/:path*" },
];
},
};
export default nextConfig;
/openmax-api/:path* covers both /openmax-api/api/v1/… and the ticket exchange at /openmax-api/auth/ws-ticket. Keep Authorization and X-Org-ID when forwarding; a path such as /openmax-api is same-origin with the page, so X-Workspace-ID is sent when you pass workspaceId.
The chat components can be rendered on the server too. On the server they send no request and do not call getToken; the server HTML and the first client frame show the same placeholder: the conversation list shows its loading skeleton, the message thread shows nothing (or your emptyState), and the group info panel shows nothing. Requests start once <ChatProvider> has mounted in the browser, and the data replaces the placeholder as it arrives.
Until then host.identity knows nobody: currentUserId() returns "" and listMembers() returns an empty list. Don't rely on it while rendering on the server; if your own components need the current user, read host.identity in useEffect (or after mount). Called directly in the browser, outside any component, host.identity still fetches what it is asked for.
Next.js rewrites do not forward WebSockets
rewritesforwards HTTP requests only, not WebSocket upgrades. Either givewsUrlas an absolute URL (wss://…; the page origin must be registered, see mode 2 in Realtime connection: deployment modes), or make it a path (such as/openmax-ws) and put a reverse proxy that forwards upgrades (Upgrade,Connection) in front of Next.js; the nginx setup is mode 1 in the same section.
Render the chat
src/app.tsx
import { createChatI18n } from "@openmaxai/chat-sdk";
import {
ChatProvider,
ChatRoot,
ChatSplitLayout,
ConversationHeader,
CwsConversationList,
CwsMessageThread,
useChatSdkConversationList,
} from "@openmaxai/chat-sdk/react";
import { useState } from "react";
import { I18nextProvider } from "react-i18next";
import { host } from "./chat-host";
const i18n = createChatI18n({ locale: "en-US" });
export function App() {
return (
<I18nextProvider i18n={i18n}>
<ChatProvider host={host}>
<ChatRoot style={{ display: "flex", height: "100vh" }}>
<Chat />
</ChatRoot>
</ChatProvider>
</I18nextProvider>
);
}
function Chat() {
const { conversations } = useChatSdkConversationList();
const [selectedId, setSelectedId] = useState<string | null>(null);
const selected = conversations.find((c) => c.id === selectedId) ?? null;
return (
<ChatSplitLayout
open={selected !== null}
list={
<CwsConversationList
selectedId={selectedId}
onSelect={(c) => setSelectedId(c.id)}
onDeselect={() => setSelectedId(null)}
/>
}
>
{selected && (
<>
<ConversationHeader
conversation={selected}
onBack={() => setSelectedId(null)}
/>
<CwsMessageThread key={selected.id} conversation={selected} />
</>
)}
</ChatSplitLayout>
);
}
ChatProviderinstalls the host and the composer plugins, and re-renders when your profile and member data arrive.ChatRootis the context root of the chat: it gives the SDK components inside it their color scheme and overlay landing node, and the SDK components go inside it. It is not a style scope itself; the styles apply only inside the component root each SDK component brings. See Installation · Load the styles.CwsConversationListis the conversation list; its data comes from the host'sconversations.listand is fetched again when new messages arrive.ChatSplitLayoutputs the list and the open conversation side by side. On narrow screens (viewport under 768 px) it shows one at a time: the list, or the conversation whileopenis true. It takes its width from its parent, which is whyChatRootgetsdisplay: flex. SeeChatSplitLayout.ConversationHeaderis the conversation header: title, member count and a mute toggle (the OpenMax adapter implementssetMutedwithPOST /api/v1/conversations/{id}/muteor/unmute). On narrow screens it shows a back arrow that callsonBack; clearing the selection there brings the list back. See Header.CwsMessageThreadis the message thread and composer. It already wraps aConversationScopefor its conversation, so uploads are tied to that conversation (OpenMax uploads are per conversation).- Composer plugins: this host has
workItems(GET /api/v1/work-references), soChatProviderinstalls the#plugin: type#or click the#toolbar button to list projects, type to search projects and issues, and expand a project to get its issues; see Capabilities. I18nextProvider(from your ownreact-i18next, with an instance fromcreateChatI18n): a few components read strings from react-i18next. See Internationalization.
This example does not need @tanstack/react-query.
useChatSdkConversationList() also returns isLoading, error, hasNextPage, fetchNextPage and refetch. With wsUrl, the list refreshes within a second of new messages, read updates or a reconnect.
Tokens and expiry
The SDK only consumes tokens; it never issues or refreshes them:
- The first request that needs a token calls
getToken()and caches the result. - On a
401it callsgetToken({ refresh: true })(renew for real at this point) and re-sends the request once with the new token. - If no token comes back, or the re-sent request gets
401again, it rejects withChatSdkRequestError. How to renew is up to you; when the renewal endpoint is offline, throw aChatSdkErrorwithkindnetworkand the request fails withnetwork, not as an expired session. AgetTokencall that has not settled within 30 seconds fails withtimeout, which is not an expired session either, and the next request calls it again.
The WebSocket exchanges the same token for a one-time ticket; a 401 there also renews first and exchanges again. If it is still refused after renewal, or getToken() fails with a credential failure, it stops reconnecting (network backs off and reconnects as usual). A 403 on the ticket request (not allowed to get a ticket) is not renewed; it stops reconnecting and reports once through the error event, and it does not count as an expired session. When the server closes the connection because the credentials are no longer valid, it does not reconnect either and treats it as expired credentials. See Errors and expired sessions.
For short-lived tokens, return the expiry too: getToken may resolve to { token, expiresAt } (OpenMaxToken; expiresAt in epoch milliseconds or an ISO 8601 string). Then:
- Before a request goes out with less than 60 seconds left (half the lifetime for tokens shorter than two minutes), the SDK asks
getToken({ refresh: true })first, so no request fails with401because the token ran out. Requests that notice it at the same time share one call; a page that comes back after a long time in the background renews before its first request. - The realtime connection is handed over before expiry instead of being dropped: a second connection opens with a new ticket and the old one closes once it is up. Messages that arrive during the handover show up once.
- A
401renews only when its code isAUTH_TOKEN_EXPIRED. Any other401(the token or the Key behind it was revoked) fails withunauthorizedstraight away:onUnauthorizedis called and realtime stops reconnecting, without trading for new tokens.
A plain string keeps the behavior above unchanged.
Connect with a personal API Key
Users create personal API Keys themselves in OpenMax under Settings → Developer → Personal API keys; a Key starts with cwpat_. Keep the Key on your server: your server trades the Key for a short-lived token and hands that to the SDK in the browser.
Each user uses their own Key. A Key acts as the one person who created it; one Key shared by many users' browsers is not supported. Users create their own Key in OpenMax and give it to you; your server stores it per signed-in user and trades with that user's Key.
Never put a personal API Key in the browser
A Key acts as the person who created it and is valid for up to a year (90 days by default). Once it is in browser code, anyone who can open the page can read it in the developer tools and, until it expires or is rotated, send and read messages as that person within the permissions it was granted. Revoke it at once if you suspect it leaked. The only exception is an internal page only the Key's owner uses.
Wherever the Key is sent from:
- The Key is sent as
Authorization: Bearer cwpat_…; the backend accepts it only in that header. orgIdis required. The Key only says who you are; the organization comes fromX-Org-ID. The backend checks your membership in that organization on every request, so if you are removed or your role changes, the next request already uses the new state. In any organization a Key never has more rights than you do.- When embedded cross-origin, the SDK does not send
X-Workspace-ID(the backend does not read it, and OpenMax's CORS setup does not allow it). It is sent only when the page andbaseUrlshare an origin andworkspaceIdis given; when there is no page origin (outside a browser) it counts as cross-origin.
Recommended: trade the Key for a short-lived token on your server
The endpoint is POST /auth/pat/exchange (under baseUrl), called with Authorization: Bearer cwpat_… and X-Org-ID. X-Org-ID is required; without it the answer is 403 AUTH_ORG_MEMBERSHIP_REQUIRED. The response is wrapped in the standard data envelope: the token is data.access_token, next to fields such as the expiry and the permissions actually granted (scopes). Pass the token and its expiry to the browser, so the SDK can renew before the token runs out. The request body is optional: without it the token lives 900 seconds and gets the Key's permissions intersected with the "Chat" preset. To change that, send JSON: expires_in (60–900 seconds, never past the Key's own expiry); scopes (the permissions you want, also intersected with the Key's; those the Key lacks are dropped). The "Chat" preset leaves out changing groups and members and switching models (see Which permissions to grant); list those in scopes if you use them.
- When the SDK needs a token it calls your
getToken, which asks your own server. - Your server first works out which signed-in user is asking, then trades that user's own Key with OpenMax, sending the organization (
X-Org-ID), for a short-lived token and returns the token to the browser. The token is bound to that organization, soorgIdin the browser must match it; if it does not, requests are refused with401. The Key never leaves your server. - The SDK uses the token for requests and to open the realtime connection. Shortly before the token expires, the SDK asks again with
getToken({ refresh: true })(see Tokens and expiry), your server trades for a new one, and requests and the realtime connection carry on without the user noticing.
Your server (Node / Express):
server.ts
import express from "express";
const app = express();
// requireLogin is your own sign-in check; after it, req.user is the current user
app.post("/chat-token", requireLogin, async (req, res) => {
// The current user's own Key (cwpat_…), stored only on the server; a Key acts as one person, never use it for another user
const apiKey = await loadUserApiKey(req.user.id);
if (!apiKey) return res.status(401).end(); // this user has not given you a Key yet, or has removed it
const r = await fetch("https://openmax.com/auth/pat/exchange", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"X-Org-ID": req.user.orgId, // required, 403 without it; the token is bound to this organization, and orgId in the browser must match it
},
});
if (r.ok) {
const { data } = await r.json(); // the response is wrapped in the data envelope
// expires_in: seconds the token lives; as epoch milliseconds it becomes the SDK's expiresAt
return res.json({ token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 });
}
// 401 only when the Key itself is unusable (revoked, rotated, expired); the browser treats that as expired credentials
if (r.status === 401) return res.status(401).end();
// 400, 403 and 404 do not go away on retry: the Key lacks org:token:exchange, the user is not in this organization, what was traded is not a Key, the Key holds none of the requested permissions, or the exchange is not open on the server
if ([400, 403, 404].includes(r.status)) return res.status(r.status).end();
if (r.status === 429) {
return res.status(429).set("Retry-After", r.headers.get("Retry-After") ?? "1").end();
}
res.status(503).end(); // upstream error or unreachable: temporarily unavailable, not a Key problem
});
In the browser:
src/chat-host.ts
import { ChatSdkError } from "@openmaxai/chat-sdk";
import { createChatHost } from "@openmaxai/chat-openmax/react";
// The SDK caches the token and asks again shortly before expiresAt, so always trade for a new one
async function getToken() {
// a failing fetch itself (offline, for example) throws a TypeError, which the SDK treats as network; no need to catch it
const r = await fetch("/chat-token", { method: "POST", credentials: "include" });
if (r.status === 401) throw new Error("chat token: 401"); // only this is handled as expired credentials: realtime stops, onUnauthorized is called
// retrying cannot fix these: report them as forbidden, so realtime stops reconnecting and it does not count as an expired session
if ([400, 403, 404].includes(r.status)) throw new ChatSdkError("forbidden", "", { status: r.status });
if (!r.ok) throw new ChatSdkError("network", "", { status: r.status }); // rate limit or upstream error: not an expired session, realtime keeps reconnecting
const { token, expiresAt } = await r.json();
return { token, expiresAt }; // with the expiry the SDK renews before it runs out
}
export const host = createChatHost({
baseUrl: "https://openmax.com",
wsUrl: "wss://openmax.com/ws",
auth: { mode: "token", getToken },
orgId: currentOrgId, // required
});
The SDK caches what
getToken()returns and asks again with{ refresh: true }shortly beforeexpiresAt, and after a401whose code isAUTH_TOKEN_EXPIRED(when the page's clock is off). With{ refresh: true }, always trade for a new token on your server; do not return the old one. Any other401means the Key or the token was revoked: the SDK does not ask again and handles it as expired credentials.When no token can be had, there are three cases:
- Only when your server answers
401(this user's Key is gone, expired, revoked or rotated) throw a plainError, which is handled as expired credentials. - A
400,403or404from the token endpoint does not go away on retry. Your server passes that status on as it is (do not turn it into503), and the browser throws aChatSdkErrorwhosekindisforbidden: realtime stops reconnecting, and it does not count as an expired session. The403codeisAUTH_PAT_INSUFFICIENT_SCOPE(the Key lacksorg:token:exchange, named inmeta.required_scope; trading a short-lived token again gets this too, since a traded token does not carry it),AUTH_ORG_MEMBERSHIP_REQUIRED(the user is not in this organization, or the request has noX-Org-ID) orAUTH_PAT_EXCHANGE_CREDENTIAL_INVALID(what was traded is not a personal API Key, for example a web sign-in session); the400codeisAUTH_PAT_EXCHANGE_SCOPE_INVALID(the Key holds none of the requested permissions, or of the "Chat" preset whenscopesis not sent; the missing ones are inmeta.missing_scopes; it is also returned whenscopesnames a permission that does not exist, listed inmeta.invalid_scopes) orAUTH_PAT_EXCHANGE_EXPIRES_IN_INVALID(the lifetime is outside 60–900 seconds); the404codeisAUTH_PAT_EXCHANGE_DISABLED(the exchange is not open on the server; it answers this until it opens). A400or403needs a change to the Key or to your server: ask the user for a Key with the right permissions, or check the organization. A404waits for OpenMax to open the exchange; once it is open, REST trades again on its next request, but realtime has stopped reconnecting and comes back only with a new host (or a page reload). - For rate limits (
429,codeAUTH_PAT_EXCHANGE_RATE_LIMITED, withRetry-After; at most 30 trades per Key per 60 seconds), upstream errors and an unreachable server throw aChatSdkErrorwhosekindisnetwork, which does not count as an expired session. Otherwise one upstream hiccup shows "session expired" on every open page.
- Only when your server answers
Without short-lived tokens: forward through your server
If you do not trade for short-lived tokens, you can point the SDK's baseUrl at your own server and have it forward requests to OpenMax, adding the current user's own Key (Authorization: Bearer cwpat_…) on the way. The browser never holds the Key.
getTokenreturns your own site's token; your server works out which user it belongs to and swaps in that user's Key before forwarding. Do not forward many users' requests with one Key, and do not forward requests from users who are not signed in.- There is no realtime this way: the realtime connection accepts only a short-lived token and refuses the Key itself. Use
realtime: "off"; messages from others then show up only after a reload. - Forward only the API paths the SDK uses (an allowlist) and reject everything else; strip the
Authorizationthe browser sent and put the Key in its place. - Never write the
Authorizationheader to logs, and never put the Key in client-exposed environment variables such asNEXT_PUBLIC_orVITE_ones. - Attachment upload and download URLs come straight from OpenMax and do not pass through your server; allow them as in Deployment requirements.
An internal page only the Key's owner uses
Only when a page is used solely by the Key's owner (for example your own debugging page) may the Key go into the browser, with getToken returning the Key itself. All three must hold: only you open the page; the Key has only the permissions chat needs (see Which permissions to grant); its expiry is short. The realtime connection refuses the Key itself, so use realtime: "off".
src/chat-host.ts
import { createChatHost } from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "https://openmax.com",
realtime: "off", // the realtime connection refuses the Key itself
auth: { mode: "token", getToken: async () => apiKey }, // cwpat_…, only on a page you alone use
orgId: currentOrgId, // required
});
Which permissions to grant
When creating the Key, pick the "Chat" preset to grant what chat needs from the table below in one click; only changing groups and members (messages:conversation:write, messages:conversation.member:write) and switching models (agents:model:write) are not in it, so grant those separately if you use them.
A Key can only call endpoints whose permission it was granted. The easy way is to grant the two broad items messages:read and messages:write, then add the ones below for the features you use:
| Feature | Permission |
|---|---|
| Conversation list, members, messages, read and unread state, incremental sync | messages:read (includes messages:conversation:read, messages:conversation.member:read, messages:message:read, messages:read_state:read, messages:sync:read) |
| Sending messages and attachments, editing and recalling, reactions, answering cards, marking read, mute and pin, starting DMs and groups, changing groups and members | messages:write (includes messages:message:send, messages:message:write, messages:reaction:write, messages:card:interact, messages:read_state:write, messages:conversation.preference:write, messages:conversation:create, messages:conversation:write, messages:conversation.member:write) |
| The current user | org:me:read |
Names, avatars and @ candidates of organization members |
org:member:read |
# work items |
work:project:read |
| Artifact links in messages | kb:artifact:read |
| The model name in Agent DMs, switching models | agents:model:read, agents:model:write |
Trading for a short-lived token and realtime need the ones below, all in the "Chat" preset:
org:token:exchange: trade the Key for a short-lived token. The traded token does not carry it, so a token cannot be traded again.messages:realtime:connect: open the realtime connection with the traded short-lived token. It is part of the broadmessages:readitem, so granting that item includes it.messages:typing:read,org:presence:read,agents:activity:read: receive typing, presence and Agent activity in realtime. Broad items do not include these three; without the preset, grant them one by one.
401 and 403
401: the token or Key has expired, was revoked or rotated, or is not valid. WhengetTokenreturned{ token, expiresAt }, onlyAUTH_TOKEN_EXPIREDmakes the SDK ask again; any other401fails withunauthorizedstraight away. Otherwise, as in Tokens and expiry, the SDK asks once more withgetToken({ refresh: true }): with short-lived tokens, trade for a new one on your server; when forwarding or using the Key directly, a Key cannot be renewed, so return it unchanged. If the re-sent request gets401again, it fails with aChatSdkRequestErrorwhosekindisunauthorized; if the Key itself is no longer valid, ask its owner for a new one.403: the Key is valid but lacks the permission the operation needs. The error'scodeisAUTH_PAT_INSUFFICIENT_SCOPEand itskindisforbidden; the missing permission is inmeta.required_scopein the response body. A403does not trigger a renewal and does not count as an expired session.
Revoking or rotating a Key takes effect on the next request: the backend checks the Key on every request, and short-lived tokens traded from it stop working from the next request too; open realtime connections are closed within about 1 second; when the user is removed from the organization, their realtime connections in that organization are closed within about 1 second too. The SDK treats such a disconnect as expired credentials: it does not reconnect, reports once with an error whose kind is unauthorized, and the host handles it as expired credentials (calls onUnauthorized, or shows "session expired" once without it; see Errors and expired sessions).
Realtime
- The realtime connection is opened with a short-lived token (the Key it was traded from needs
messages:realtime:connect), so new messages show up live; the Key itself is refused for realtime (403,codeAUTH_REALTIME_REQUIRES_EXCHANGED_TOKEN), so forwarding and the internal page both needrealtime: "off". - When the short-lived token expires, the server closes the realtime connections opened with it and the SDK reconnects as usual: the ticket request gets one
401, and once it has a new token it connects again without the user noticing. - When opening the realtime connection is refused (
403), the SDK stops reconnecting and reports it once through the error event (the adapter'ssink.error) withkindforbidden. It does not count as an expired session: no renewal, noonUnauthorized, no "session expired" notice. Realtime does not recover on its own: after granting the Key the missing permission, create a new host (or reload the page) to reconnect. - The realtime connection filters events by the short-lived token's permissions; events whose permission is missing do not arrive: messages, member changes and read state need the matching items in
messages:read, typing, presence and Agent activity need the three listed separately above, and sending typing yourself needsmessages:message:send. - Where you do not need realtime, use
realtime: "off"; messages from others then show up only after a reload.
Tear down
host.dispose();
Closes the WebSocket and stops reconnecting for good; a disposed host cannot be revived. Call it on sign-out or page exit. Avoid effect cleanups that may run again: StrictMode runs cleanups once on mount in development.
Configuration
| Option | Type | Required | Description |
|---|---|---|---|
baseUrl |
string |
Yes | REST base URL without /api/v1; for OpenMax, https://openmax.com. An absolute http(s) URL, or a path starting with / (see Server-side rendering and Next.js). |
wsUrl |
string |
This or realtime |
Realtime endpoint; for OpenMax, wss://openmax.com/ws. An absolute ws(s) URL, or a path starting with /. Not derived from baseUrl. |
realtime |
"off" |
This or wsUrl |
REST only, no WebSocket. |
auth |
{ mode: "token"; getToken } |
Yes | Only token is supported. logto and cookie throw ChatSdkConfigError. |
agentActivity |
boolean |
No | Agent runs, read-only progress (experimental · transitional); replaced when the planned Agent runs capability lands. Default true (also with realtime: "off"): the realtime channel recognizes agent_activity frames and agent_run on replies is decoded into agent_run_summary; false does neither, so nothing is drawn. It lives only on the adapter side; the SDK has no such switch. |
workspaceId / orgId |
string |
No (orgId is required with a personal API Key; the backend does not read workspaceId, so it is optional) |
Sent as X-Workspace-ID / X-Org-ID; X-Workspace-ID only when the page and baseUrl share an origin. |
locale |
string |
No | BCP-47. Primary tag en picks English strings, anything else Chinese. Default "zh-CN". Ignored when ports.i18n is given. |
storage |
"memory" | "localStorage" |
No | Where drafts and the device id live. Default "memory": nothing written to page storage; every load counts as a new device. |
instanceKey |
string |
No | Keeps stored drafts of two chats on one page apart; persists across loads only with storage: "localStorage". Default "default". |
ports |
ChatSdkPortOverrides |
No | Replace whole local capabilities: render, attention, i18n, navigation, mediaViewer, composerPreferences, localRecords, drafts, attachments, instanceScope. |
Invalid config throws ChatSdkConfigError synchronously (exported from @openmaxai/chat-sdk/react); failed requests reject with ChatSdkRequestError (exported from @openmaxai/chat-openmax).
Reactions, recall, editing and edit history are wired; reactions, edits and recalls by others appear live, and a message removed by moderation is removed from the thread; changes others made while you were offline or away are caught up from the change log on reconnect or when you switch back to the conversation (see Realtime and sync · Gap-fill).
The "@me" jump is wired too: when someone mentions you, a button with the count appears at the bottom right of the thread; click it to jump to the next one, or long-press it to mark all read.
Read receipts are wired too: your messages show ticks in DMs and "read n/m" in groups; a conversation with read receipts off (the read-cursors endpoint answers 412) shows no receipts at all.
Cards can be answered and answers by others appear live; business-card buttons are drawn only with the { adapter } form and cards.isOperationAllowed.
# work items in the composer are wired too: the chosen project or issue is sent as a [#label](proj://…) / issue://… reference.
The Agent DM header shows the model too: the owner gets a model button (and the "yours" name tag after the name, when the host gives memberMarks.nameTag) to switch the model and whether its name is shown to others; anyone else sees the read-only model name.
Which optional capabilities this host provides (profile cards and group management among them), and which ports can replace: Known limitations · Default host.
Deployment requirements
If the page that hosts the chat has a different origin from baseUrl (it is embedded under another domain), the backend must allow that page's origin for CORS. Same-origin deployments need no CORS, but the realtime connection still checks the page's origin; see Realtime connection: deployment modes.
A direct connection needs your page's origin registered first. When the page calls OpenMax directly from its own origin (browser → OpenMax, mode 2 below), OpenMax allows only registered origins: a page that is not registered can neither call the API nor open the realtime connection. To register, email contact@openmax.com with the origins of your pages (scheme, host and port). Not every origin is allowed by default, and there is no allow-all option. Through a same-origin proxy that rewrites or removes Origin (mode 1), REST and the realtime connection need no registration, only the OpenMax addresses above; for attachments see the two items below.
- REST API (direct connection): every request carries an
Authorizationheader, so the browser sends a preflight (OPTIONS) first. The preflight must allow the origin and listAuthorizationandX-Org-IDinAccess-Control-Allow-Headers(cross-origin, the SDK does not sendX-Workspace-ID). If the preflight is blocked, not even the current user loads. - Attachment upload URLs (both modes): the browser sends the upload
PUTstraight to theupload_urlthe server returns, not through your proxy, so the storage behind it must allowPUTfrom the origin too. - Attachment download URLs (both modes): received attachment URLs (
download_url) are used as is to show images and previews, so the storage behind them must allow the origin too.
A request blocked by CORS fails with a ChatSdkRequestError whose status is 0; see Errors and expired sessions.
Realtime connection: deployment modes
The realtime endpoint checks the Origin of the WebSocket handshake. It accepts the handshake when the Origin host equals the host the request was sent to, when the Origin is registered, or when there is no Origin at all (clients that are not browsers). Anything else gets 403 with the code WS_ORIGIN_NOT_ALLOWED. Pick the mode that matches your deployment:
Same-origin proxy. The page,
baseUrlandwsUrlare all on your origin, and your server forwards them to OpenMax. REST needs no CORS. A proxy normally setsHostto OpenMax's host while the browser'sOriginstays your page's, so the handshake fails the check. RewritingOriginin the proxy to OpenMax's origin, or removing it, is officially supported; registering your page's origin as in mode 2 works too. The proxy must also pass the WebSocket upgrade through (UpgradeandConnection). With nginx:nginx.conflocation /openmax-ws { proxy_pass https://openmax.com/ws; proxy_ssl_server_name on; proxy_http_version 1.1; proxy_set_header Host openmax.com; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Origin ""; }With
Originrewritten or removed, the page origin needs no registration; OpenMax treats the connection like one from a server: which pages may use your proxy is up to you.Direct connection. The page calls OpenMax's
baseUrlandwsUrlitself, from another origin. Register your page's origin (see Deployment requirements); the registration covers CORS and the realtime connection together. A bare*(every origin) is not accepted; subdomain patterns such as*.example.comare. Prefer registering exact origins.
| Symptom | Cause |
|---|---|
The browser shows the WebSocket closing with 1006 |
The handshake's Origin failed the check (the server answers 403 WS_ORIGIN_NOT_ALLOWED, which a browser cannot read, so it only reports 1006): the page's origin is not registered (mode 2), or the proxy passes the browser's Origin through unchanged (mode 1) |
Standalone OpenMax package
The OpenMax code lives in its own package, @openmaxai/chat-openmax, and every example on this page imports createChatHost from @openmaxai/chat-openmax/react. When moving from the old form, the config keeps its shape; the import path and the config type names changed:
| Old form | Now |
|---|---|
createChatHost from @openmaxai/chat-sdk/react taking the OpenMax config directly (it now takes only { adapter } and throws ChatSdkConfigError at once when given the OpenMax config) |
createChatHost from @openmaxai/chat-openmax/react |
ChatSdkConfig, ChatSdkAuth |
OpenMaxChatConfig, OpenMaxAuth |
| — | The one-line config does not take onUnauthorized (known gap); for it, use { adapter: createOpenMaxAdapter(config), onUnauthorized } |
