OpenMax
Free Trial

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
});
  • createChatHost is synchronous: it validates the config, sends no request and does not call getToken. Create it once, at module scope or in a memo.
  • baseUrl is required; the SDK never reads environment variables.
  • Pass exactly one of wsUrl or realtime: "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/conversations returns 401. A session token that already carries an organization can omit it. The backend does not read workspaceId (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.origin itself is unusable (on the server; on a page whose location.origin is "null" such as about:blank; or on a page that is not http(s), such as file: or chrome-extension:), the first request rejects with a ChatSdkConfigError naming baseUrl; a path wsUrl opens no connection and does not reconnect, and the adapter reports once through sink.error an error with code ws_url_unresolved (its cause is the ChatSdkConfigError naming wsUrl); the chat UI keeps working, only without realtime. In development builds it also logs one console.error (once per host) naming wsUrl with the reason and the fix; production builds print nothing. In both cases getToken is not called. Sandboxed iframes are not in this group: their location.origin is the http(s) origin of the address (only window.origin is "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/api is 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

rewrites forwards HTTP requests only, not WebSocket upgrades. Either give wsUrl as 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>
  );
}
  • ChatProvider installs the host and the composer plugins, and re-renders when your profile and member data arrive.
  • ChatRoot is 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.
  • CwsConversationList is the conversation list; its data comes from the host's conversations.list and is fetched again when new messages arrive.
  • ChatSplitLayout puts 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 while open is true. It takes its width from its parent, which is why ChatRoot gets display: flex. See ChatSplitLayout.
  • ConversationHeader is the conversation header: title, member count and a mute toggle (the OpenMax adapter implements setMuted with POST /api/v1/conversations/{id}/mute or /unmute). On narrow screens it shows a back arrow that calls onBack; clearing the selection there brings the list back. See Header.
  • CwsMessageThread is the message thread and composer. It already wraps a ConversationScope for 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), so ChatProvider installs 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 own react-i18next, with an instance from createChatI18n): 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:

  1. The first request that needs a token calls getToken() and caches the result.
  2. On a 401 it calls getToken({ refresh: true }) (renew for real at this point) and re-sends the request once with the new token.
  3. If no token comes back, or the re-sent request gets 401 again, it rejects with ChatSdkRequestError. How to renew is up to you; when the renewal endpoint is offline, throw a ChatSdkError with kind network and the request fails with network, not as an expired session. A getToken call that has not settled within 30 seconds fails with timeout, 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 with 401 because 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 401 renews only when its code is AUTH_TOKEN_EXPIRED. Any other 401 (the token or the Key behind it was revoked) fails with unauthorized straight away: onUnauthorized is 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.
  • orgId is required. The Key only says who you are; the organization comes from X-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 and baseUrl share an origin and workspaceId is given; when there is no page origin (outside a browser) it counts as cross-origin.

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.

  1. When the SDK needs a token it calls your getToken, which asks your own server.
  2. 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, so orgId in the browser must match it; if it does not, requests are refused with 401. The Key never leaves your server.
  3. 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 before expiresAt, and after a 401 whose code is AUTH_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 other 401 means 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 plain Error, which is handled as expired credentials.
    • A 400, 403 or 404 from the token endpoint does not go away on retry. Your server passes that status on as it is (do not turn it into 503), and the browser throws a ChatSdkError whose kind is forbidden: realtime stops reconnecting, and it does not count as an expired session. The 403 code is AUTH_PAT_INSUFFICIENT_SCOPE (the Key lacks org:token:exchange, named in meta.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 no X-Org-ID) or AUTH_PAT_EXCHANGE_CREDENTIAL_INVALID (what was traded is not a personal API Key, for example a web sign-in session); the 400 code is AUTH_PAT_EXCHANGE_SCOPE_INVALID (the Key holds none of the requested permissions, or of the "Chat" preset when scopes is not sent; the missing ones are in meta.missing_scopes; it is also returned when scopes names a permission that does not exist, listed in meta.invalid_scopes) or AUTH_PAT_EXCHANGE_EXPIRES_IN_INVALID (the lifetime is outside 60–900 seconds); the 404 code is AUTH_PAT_EXCHANGE_DISABLED (the exchange is not open on the server; it answers this until it opens). A 400 or 403 needs a change to the Key or to your server: ask the user for a Key with the right permissions, or check the organization. A 404 waits 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, code AUTH_PAT_EXCHANGE_RATE_LIMITED, with Retry-After; at most 30 trades per Key per 60 seconds), upstream errors and an unreachable server throw a ChatSdkError whose kind is network, which does not count as an expired session. Otherwise one upstream hiccup shows "session expired" on every open page.

    See Errors and expired sessions.

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.

  • getToken returns 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 Authorization the browser sent and put the Key in its place.
  • Never write the Authorization header to logs, and never put the Key in client-exposed environment variables such as NEXT_PUBLIC_ or VITE_ 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 broad messages:read item, 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. When getToken returned { token, expiresAt }, only AUTH_TOKEN_EXPIRED makes the SDK ask again; any other 401 fails with unauthorized straight away. Otherwise, as in Tokens and expiry, the SDK asks once more with getToken({ 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 gets 401 again, it fails with a ChatSdkRequestError whose kind is unauthorized; 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's code is AUTH_PAT_INSUFFICIENT_SCOPE and its kind is forbidden; the missing permission is in meta.required_scope in the response body. A 403 does 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, code AUTH_REALTIME_REQUIRES_EXCHANGED_TOKEN), so forwarding and the internal page both need realtime: "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's sink.error) with kind forbidden. It does not count as an expired session: no renewal, no onUnauthorized, 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 needs messages: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 Authorization header, so the browser sends a preflight (OPTIONS) first. The preflight must allow the origin and list Authorization and X-Org-ID in Access-Control-Allow-Headers (cross-origin, the SDK does not send X-Workspace-ID). If the preflight is blocked, not even the current user loads.
  • Attachment upload URLs (both modes): the browser sends the upload PUT straight to the upload_url the server returns, not through your proxy, so the storage behind it must allow PUT from 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:

  1. Same-origin proxy. The page, baseUrl and wsUrl are all on your origin, and your server forwards them to OpenMax. REST needs no CORS. A proxy normally sets Host to OpenMax's host while the browser's Origin stays your page's, so the handshake fails the check. Rewriting Origin in 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 (Upgrade and Connection). With nginx:

    nginx.conf

    location /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 Origin rewritten 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.

  2. Direct connection. The page calls OpenMax's baseUrl and wsUrl itself, 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.com are. 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 }

See @openmaxai/chat-openmax.