Chat SDK integration
Put OpenMax conversations in your page: which template to pick, keeping tokens out of the browser, and common pitfalls.
Chat SDK integration
Use this when you need OpenMax conversations (with people or agents) in your page. For installation, components, capabilities, credentials, scopes, i18n, theming, cards, and real-time connections, see the Chat SDK docs (Tutorial for getting started and integration guides, Reference for components and APIs); for availability, see the Calling platform capabilities ("Capability list"). This page only covers which template to pick and how the reference implementation does it.
Choosing a template
- Pin the exact version: install the same version of all four packages (
@openmaxai/chat,@openmaxai/chat-store,@openmaxai/chat-sdk,@openmaxai/chat-openmax), and hard-code the version in your dependencies (no^, no dist-tag). When upgrading, read the CHANGELOG for each version (all exports are experimental). The current version is 3.0.0-beta.5. - Use the
{ adapter }form:createChatHost({ adapter: createOpenMaxAdapter(config), cards, onUnauthorized, onEvent, profileCardActions }). Do not use the one-line form from chat-openmax/react as your template: it does not accept cards, onUnauthorized, onEvent, or profileCardActions, so you cannot build business cards, profile cards, or credential-expiry callbacks. - Set storage to
"localStorage": with the default"memory", every load counts as a new device, and every reconnect re-pushes the oldest 100 inbox items. Do not puthost.dispose()in an effect cleanup that may run more than once. - Follow the host theme and language: map the host language (en / zh) to en-US / zh-CN, and map the theme mode to ChatRoot's colorScheme.
Recommended: keep tokens out of the browser
- Point the SDK's baseUrl / wsUrl at a same-origin gateway on your site, and have getToken return a placeholder string. The OpenMax token stays only on the server, and the refresh token is stored encrypted. The gateway allowlists auth, paths, query parameters, and headers, and applies rate limits (example: 120 REST requests per person per minute).
- The gateway must also allow real-time connections: the ticket endpoint
POST {baseUrl}/auth/ws-ticket(not under/api/v1); the two query parameters ticket and device_id on the WebSocket URL; and the WS proxy must pass through Upgrade and Connection and rewrite or drop Origin. Attachment upload and download URLs do not go through the gateway; allow the attachment domain separately. - In gateway mode, the gateway handles 401 itself: the browser only holds a placeholder and cannot refresh. The gateway must refresh on the server and replay the request. If the 401 is passed through to the browser, it is treated as expired credentials and the real-time connection stops.
- When signing in with OpenMax, request the chat scopes and offline_access at the same time. Feeding the SDK an app OAuth token is the reference implementation's approach; the Chat SDK docs only describe "keep a personal API Key on the server and exchange it for short-lived tokens".
Pitfalls
- Places where you need your own wrapper around chat-openmax (verified against beta.5): on forbidden, the UI does not say "real-time stopped"; identity.me only accepts
/me; the SDK has no sensitive-content blocking; identity.members throws on 403 / 404 instead of degrading. - Old tokens cannot get new scopes: after adding chat scopes, users must sign in again.
