@synerise/ai-assistant-react

React wrapper for embedding the Synerise AI Assistant in React 18 applications.

Requirements

This package is designed for the Synerise platform. To use it you need:

• An active Synerise tenant and a tracker key
• Network access to https://api.synerise.com (or your custom Synerise API endpoint)
• React 18 in your application

If you don't have a Synerise account, visit synerise.com.

Which package do I need?

| Your stack | Package | | --- | --- | | Vanilla JS / no bundler / <script> tag | @synerise/ai-assistant-sdk | | React 18 | @synerise/ai-assistant-react (this package) | | Preact | @synerise/ai-assistant-core | | Build a custom chat UI from primitives | @synerise/ai-assistant-ui |

How packages relate

@synerise/ai-assistant-react  ──>  @synerise/ai-assistant-core  ──>  @synerise/ai-assistant-ui

This package is a thin React wrapper around the Preact-based core. The chat UI itself is rendered with Preact under the hood via preact/compat. Most apps don't need to know this, but see the SSR / dual runtime notes below.

Installation

npm install @synerise/ai-assistant-react preact
# or
pnpm add @synerise/ai-assistant-react preact
# or
yarn add @synerise/ai-assistant-react preact

Peer dependencies

• react ^18.3.1
• react-dom ^18.3.1
• preact ^10.26.9 (transitively required by @synerise/ai-assistant-core)

Quick start

import { AIAssistant } from "@synerise/ai-assistant-react";

export function AssistantPanel() {
  return (
    <AIAssistant
      apiUrl="https://api.synerise.com/gen-ai/v3/ai-assistant"
      context={{ profileId: "user-123" }}
      additionalContextValues={{ segment: "premium" }}
      displayMode="bordered"
      onPromptSuccess={(response) => {
        console.log("threadId:", response.meta.threadId);
        console.log("messages:", response.data.messages);
      }}
      onCustomAction={({ actionName, params }) => {
        console.log(actionName, params);
      }}
    />
  );
}

What this package provides

• AIAssistant — full chat component with built-in lifecycle handling
• Icon — icon component (re-exported from core/ui)
• ChatBase — lower-level chat primitive for advanced cases
• All exports from @synerise/ai-assistant-core are re-exported, so you typically need only one import:

import {
  AIAssistant,
  assistantApi,
  AI_ASSISTANT_ERROR_TYPE,
  CHAT_STATE,
  type AIAssistantProps,
  type AIAssistantResponseBody,
} from "@synerise/ai-assistant-react";

Important props

| Prop | Type | Description | | --- | --- | --- | | apiUrl | string | Base assistant API URL | | context | Context | Per-request context object | | additionalContextValues | AdditionalContextValues | Per-request metadata | | displayMode | "drawer" \| "bordered" | UI layout | | onPromptSuccess | (response) => void | Required. Called after a successful init/message response | | onCustomAction | ({ actionName, params }) => void | Called when the assistant emits a custom action | | threadId | string | Loads an existing conversation when provided | | stream | boolean | Use SSE instead of regular POST | | fastMode | boolean | Append fastMode=true query param | | authParams | { code, clientUUID } | Auth payload (alternative to XSRF cookie auth) | | disableXSRFToken | boolean | Skip XSRF token header in fetch calls |

For the full prop surface, see the TypeScript definitions of AIAssistantProps.

Direct API access (without rendering)

You can call the underlying API helpers without mounting any component:

import { assistantApi } from "@synerise/ai-assistant-react";

const initResponse = await assistantApi.initChat({
  apiUrl: "https://api.synerise.com/gen-ai/v3/ai-assistant",
  context: { profileId: "user-123" },
  additionalContextValues: { segment: "premium" },
  message: null,
});

const threadId = initResponse?.meta.threadId;

if (threadId) {
  await assistantApi.sendChatMessage({
    apiUrl: "https://api.synerise.com/gen-ai/v3/ai-assistant",
    threadId,
    message: "Show me products for trail running",
    context: { profileId: "user-123" },
    additionalContextValues: { segment: "premium" },
  });
}

SSR / dual runtime notes

The chat is rendered with Preact via preact/compat while your host app runs React. This means:

• The <AIAssistant> component is a React component on the outside (usable like any other), but the chat tree it renders internally is Preact.
• You can render this safely on the client — no special setup needed for CSR-only apps.
• For SSR frameworks (Next.js, Remix, etc.) render <AIAssistant> only on the client. Either:
  • Wrap it in a dynamic import with { ssr: false }, or
  • Mount it inside useEffect, or
  • Guard with typeof window !== "undefined".
• The chat interacts with the DOM (document.cookie, fetch) so it cannot run during server rendering.

Troubleshooting

• TypeScript errors about ReactNode from preact vs react — both runtimes ship slightly different ReactNode types. The wrapper uses as any internally to bridge them. If you re-type slots or callbacks, narrow types explicitly.
• "Two React instances" warnings — this is expected: React for your app, Preact (via compat) for the chat. They do not share state. If you see hook errors, ensure you are not calling Preact hooks from React components or vice versa.
• document is not defined during SSR — render only on the client (see SSR / dual runtime notes).
• 401 / 403 from API — verify your tracker key, that apiUrl matches your tenant, and that disableXSRFToken matches your tenant's auth flow.

Support

For technical and licensing inquiries: [email protected].

License

Proprietary. See LICENSE.