Chat Widgetchat-widget

Chat Widget

Configure the visitor widget, expose a session bootstrap endpoint, and embed it through React or a script tag.

Session bootstrapReact embedScript tag

Create the widget in your dashboard

Create and configure the widget from your Clivly dashboard — no raw SQL. The dashboard applies slug, origin, and uniqueness validation the old manual insert skipped.

Launch “Add chat widget” from the dashboard, the ⌘K command palette, or the Settings → Chat widget page — all open the same dialog.
Set the name, widget ID (a public slug used in the embed), allowed origins, greeting, and brand colour, with a live preview.
After you create it, the install step shows the embed snippet and the widget’s active / blocked status.

Add the session route

Your app keeps the secret key server-side and hands the browser a session bootstrap.

app/api/clivly/widget/session/route.ts

import { createChatSessionHandler } from "clivly/sdk";

export const POST = createChatSessionHandler({
  apiKey: process.env.CLIVLY_SECRET_KEY ?? process.env.CLIVLY_API_KEY ?? "",
  allowedOrigins: [
    "https://app.example.com",
  ],
});

`clivly add widget` scaffolds this exact route for you.
`allowedOrigins` are exact-match origins — the scheme and host of the pages that embed the widget.

Vouch for a logged-in visitor

By default a visitor is self-reported: whatever they typed in the pre-chat form. If they are already logged into your app, your server can vouch for who they are.

app/api/clivly/widget/session/route.ts

import { createChatSessionHandler } from "clivly/sdk";
import { auth } from "@/auth";

export const POST = createChatSessionHandler({
  apiKey: process.env.CLIVLY_SECRET_KEY ?? "",
  allowedOrigins: ["https://app.example.com"],
  // Optional. Runs on the browser request with session cookies intact.
  // Returning a user makes your app vouch for that identity.
  resolveUser: async (request) => {
    const session = await auth.api.getSession({ headers: request.headers });
    return session?.user
      ? {
          id: session.user.id,
          email: session.user.email,
          name: session.user.name ?? undefined,
        }
      : null;
  },
});

Conversations record an `identity_source` of `host_session` or `self_reported`, so operators can see which claims are trustworthy.
A verified visitor with no matching CRM contact is recorded as verified with no contact linked — Clivly never auto-creates a contact from this path.
`resolveUser` returning null, or throwing, leaves the visitor self-reported. It never fails the session.

Embed the widget

The current package supports both React embedding and script-tag delivery.

chat-widget.tsx

import { ChatWidget, createSessionFetcher } from "@clivly/chat-widget";

<ChatWidget
  widgetId="support"
  getSession={createSessionFetcher({
    sessionUrl: "/api/clivly/widget/session",
  })}
/>;

embed.html

<script
  src="https://api.clivly.com/widget.js"
  data-widget-id="support"
  data-session-url="/api/clivly/widget/session"
  data-theme="auto"
  defer
></script>

`@clivly/chat-widget` now exposes React and browser-side entry points.
`createChatSessionHandler()` is the intended host-side SDK bridge.
`resolveUser` is optional on the session handler when you want the host to vouch for a logged-in visitor.
`allowed_origins` should be exact-match origins for the host pages that embed the widget.

Framework Guides

Open Section

Auth

Open Section

Clivly docs that match the product you ship today

Chat Widget