@actera/sdk-react

React components for embedding the Actera chat widget in a SaaS dashboard.

Actera lets your users ask an AI assistant to inspect data and run approved actions in your product. The React SDK renders the widget, collects missing tool inputs, shows approval prompts, and sends requests to your Actera gateway with a short-lived delegated token from your backend.

Install

npm install @actera/sdk-react

The package expects React and React DOM to be installed by your app:

npm install react react-dom

Basic usage

Wrap the part of your app that should show Actera with ActeraProvider, then render ActeraChat.

import { ActeraChat, ActeraProvider } from "@actera/sdk-react";

async function getAccessToken() {
  const res = await fetch("/api/actera-token", { method: "POST" });
  const data = (await res.json()) as { token: string };
  return data.token;
}

export function App() {
  return (
    <ActeraProvider
      endpoint="https://api.actera.tech"
      getAccessToken={getAccessToken}
    >
      <ActeraChat />
    </ActeraProvider>
  );
}

Your backend should mint the token. Do not expose your Actera API key in browser code.

Provider options

<ActeraProvider
  endpoint="https://api.actera.tech"
  getAccessToken={getAccessToken}
  integrationConfig={integrationConfig}
  resolveResultAction={resolveResultAction}
  resolveResultRowActions={resolveResultRowActions}
>
  <ActeraChat />
</ActeraProvider>

endpoint is the Actera gateway URL.

getAccessToken returns a short-lived delegated token for the signed-in user and workspace.

integrationConfig customizes how tool results map to your product resources, including labels, fields, routes, preview limits, and row actions.

resolveResultAction and resolveResultRowActions let your app attach links to tool results at runtime.

Customize the widget

<ActeraChat
  title="Actera"
  statusLabel="Ready"
  emptyState="Ask Actera to inspect a workspace."
  placeholder="Ask Actera..."
  dialogLabel="Actera chat"
  openLabel="Open Actera"
  closeLabel="Close Actera"
/>

ActeraChat renders as a floating chat button that expands into a panel. Tool selection, permission checks, approvals, and execution happen server-side.

Result links

Use integration config when your app has stable resource routes:

const integrationConfig = {
  sdk: { resultPreviewLimit: 8 },
  resources: {
    projects: {
      label: "projects",
      route: "/projects",
      titleField: "name",
      displayFields: ["name", "status", "createdAt"],
      collectionAction: {
        label: "Open projects",
        href: "/projects",
      },
      rowActions: [
        {
          label: "Open",
          href: "/projects/{id}",
          requiresPermission: "projects:read",
        },
      ],
    },
  },
  tools: {
    list_projects: {
      resultResource: "projects",
    },
  },
};

Or resolve actions dynamically:

<ActeraProvider
  endpoint="https://api.actera.tech"
  getAccessToken={getAccessToken}
  resolveResultRowActions={({ item }) => {
    if (!item || typeof item !== "object" || !("id" in item)) return [];
    return [{ label: "Open", href: `/projects/${String(item.id)}` }];
  }}
>
  <ActeraChat />
</ActeraProvider>

Exports

import {
  ActeraChat,
  ActeraProvider,
  ClarificationForm,
  ConfirmationCard,
  useActeraContext,
} from "@actera/sdk-react";

The package also exports TypeScript types for provider configuration, chat messages, approvals, clarifications, and formatted collection results.