@flexaura/react

A React chat widget for Flexaura AI agents: a floating button that opens a chat panel, with streamed replies and handoff to your support team.

npm install @flexaura/react

import { FlexauraWidget } from "@flexaura/react";

export function App() {
  return (
    <FlexauraWidget
      agentId="YOUR_AGENT_ID"
      agentToken="fa_live_..."
      memoryMode="ephemeral"
      personaName="Aria"
    />
  );
}

Copy the exact snippet for your agent from the Flexaura dashboard (Agent → Publish → Embed → React). It fills in your agent's id, token, colors and avatar.

The widget ships with its own styles. You don't need Tailwind or a CSS import. Supports React 18 and 19. In the Next.js App Router you can render it from a Server Component; the package is already marked "use client".

Props

| Prop | Type | Default | | | ---------------- | ----------------------------------- | --------------------- | --------------------------------------------------------------- | | agentId | string | required | Your agent's id. | | agentToken | string | required | The agent's public embed token (fa_live_...). | | memoryMode | "ephemeral" \| "persistent" | required | persistent keeps the conversation across page reloads. | | personaName | string | "Chat" | Name in the panel header. | | position | "bottom-right" \| "bottom-left" | "bottom-right" | Corner for the button and panel. | | primaryColor | string | "#FA5714" | Any CSS color. | | welcomeMessage | string | "Hi! How can I help?" | First message when the panel opens. | | placeholder | string | "Type a message..." | Input placeholder. | | avatarGradient | string | Flexaura orange | CSS gradient behind the header avatar. | | avatarUrl | string \| null | null | Avatar image; falls back to the gradient and initial. | | stylePreset | "classic" \| "modern" \| "slick" | "classic" | Compact window, larger window, or full-height side panel. | | greetingBubble | boolean | false | Welcome message in a bubble beside the button, once per visit. | | apiBase | string | Flexaura's API | Only needed for a self-hosted or staging API. |

The embed token is public by design: it only lets visitors chat with this one agent.

Build your own UI

useEmbedChat is the chat state behind the widget: send messages, stream replies, and receive staff replies during a handoff.

import { useEmbedChat } from "@flexaura/react";

const { messages, isSending, error, onFirstOpen, sendMessage, resetConversation } = useEmbedChat({
  agentId: "YOUR_AGENT_ID",
  agentToken: "fa_live_...",
  memoryMode: "ephemeral",
});

Call onFirstOpen() when your chat first becomes visible (it adds the welcome message). Each message has a role: "user", "assistant", "human" (a reply from your team) or "system" (a status note). An assistant message has isStreaming: true while it's still arriving.

License

MIT

Maintainers

This section is for the Flexaura team; it's in the published README only because npm shows one file.

Source. frontend/packages/react/ in the Flexaura repo. The dashboard's own marketing widget, /chat/[token] page and /dev-widget-test import this source through the @flexaura/react alias in frontend/tsconfig.json, so they always run what customers install. Keep the widget in sync with public/widget/embed.js (same look, same behavior).

No node_modules here. The package is built with the frontend's tools (npm run build:react from frontend/); never run npm install in this directory. A second copy of React here would break the app's hooks. Keep dependencies in step with frontend/package.json.

Try the built package in another app. cd frontend && npm run build:react && cd packages/react && npm pack, then npm install /path/to/flexaura-react-<version>.tgz in a test app.

Releasing.

1. Bump version in package.json (semver: renaming or removing an export or prop is a major bump).
2. Merge to main and let Frontend CI pass.
3. Run the Publish @flexaura/react workflow (Actions → workflow_dispatch). It builds, checks the tarball, and publishes with the NPM_TOKEN secret. It refuses a version that's already on npm.