helia
start free
back

docs

Add Helia to your site or app.

Most sites paste one script tag from the Helia admin. Use the SDK packages only when you need React/Next.js integration or signed user identity.

Quick start

Start from the Helia admin you use. Cloud users open the hosted app. Self-hosted users open their own Helia admin domain.

Helia Cloud: app.gethelia.devSelf-hosted: your Helia admin URL

Website or CMS

No npm package. Copy the script tag from the Widget page.

React or Next.js app

Install @gethelia/react when the widget lives inside your app shell.

Logged-in users

Install @gethelia/server only when your backend signs user identity.

React / Next.js

Only for app shells.

pnpm add @gethelia/react

Signed users

Only for backend identity.

pnpm add @gethelia/server
You only need @gethelia/server when your backend signs logged-in users. Anonymous widgets do not need a backend package.

Script tag

For websites, CMS pages, and most marketing sites, no npm package is needed. Paste the snippet from your Helia admin.

Replace https://your-helia-admin and the workspace id only when writing examples by hand. The admin-generated snippet already fills both values correctly.
  1. 1Open Helia admin -> Widget.
  2. 2Pick floating or embedded mode.
  3. 3Copy the HTML snippet.
  4. 4Paste it before </body> or in your CMS custom HTML area.
HTML snippet
<script
  src="https://your-helia-admin/w.js"
  data-workspace="YOUR_WORKSPACE_ID"
  async
></script>
Optional: embedded widget

Embedded mode mounts the chat inside a container. Give the container a height or the widget will collapse.

Embedded HTML snippet
<div id="helia-chat" style="height: 600px"></div>
<script
  src="https://your-helia-admin/w.js"
  data-workspace="YOUR_WORKSPACE_ID"
  data-mode="embedded"
  data-target="#helia-chat"
  async
></script>

React / Next.js

Use the React SDK in a client component. The widget needs the browser, so do not render it from a server component directly.

  1. 1Install @gethelia/react.
  2. 2Create a small client component for the widget.
  3. 3Render that component from your layout or app shell.
app/helia-widget.tsx
"use client";

import { HeliaWidget } from "@gethelia/react";

export function HeliaSupportWidget() {
  return <HeliaWidget workspace="YOUR_WORKSPACE_ID" />;
}
app/layout.tsx
import { HeliaSupportWidget } from "./helia-widget";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <HeliaSupportWidget />
      </body>
    </html>
  );
}

Signed users

Use signed identity when Helia should know who is chatting. Your backend returns a signed identity for the current user, and the widget sends it with chat requests.

  1. 1Install @gethelia/server in your backend.
  2. 2Generate an identity secret in Helia Settings.
  3. 3Store it as HELIA_IDENTITY_SECRET on the server.
  4. 4Create a token endpoint in whichever backend you already use.
  5. 5Connect that endpoint to the script tag or React widget.
  6. 6Enable Reject anonymous chats only after signed traffic works.
The token endpoint returns { id, name?, signature }. Helia verifies the signature before attaching that user to the conversation.

Backend token endpoint

app/api/helia/token/route.ts

import { signIdentity } from "@gethelia/server";

export async function GET() {
  const user = await currentUser();
  if (!user) return new Response("unauthorized", { status: 401 });

  return Response.json(
    signIdentity(
      { id: user.id, name: user.name },
      process.env.HELIA_IDENTITY_SECRET!,
    ),
  );
}

After the endpoint works, connect it to whichever widget install you use.

React widget with identity
<HeliaWidget
  workspace="YOUR_WORKSPACE_ID"
  tokenEndpoint="/api/helia/token"
/>
HTML widget with identity
<script
  src="https://your-helia-admin/w.js"
  data-workspace="YOUR_WORKSPACE_ID"
  data-token-endpoint="/api/helia/token"
  async
></script>

Self-host

To install Helia itself, use Docker. This is separate from installing the assistant on a customer-facing site.

Run Helia
git clone https://github.com/snowztech/helia
cd helia
cp .env.example .env
# edit .env and set OPENAI_API_KEY and MASTER_KEY
docker compose up -d

After your admin is running, open the Widget page and copy the generated snippet. It will point at your self-hosted w.js.