Docs

Install the HumanFirst.chat widget on your website (script tag or npm SDK).

1) Create a site (project)

Go to /projects
Click “Add Project”
Set the domain (e.g. example.com) to enable automatic production installs (no projectId needed on your site)
Open /projects/[id]/settings to copy the installation snippet

2) Choose an installation method

Both options load the same widget. Choose based on your setup:

Option A — Script tag

Best if you want the simplest setup: no bundler, no app code changes, works on plain HTML sites, Webflow, WordPress, etc.

You paste one <script> snippet and you’re done.

Option B — npm SDK

Best for React/Next.js and SPAs when you want to control the widget from code (open it from a button, identify users after login, change settings, etc.).

You install @humanfirst/js and call HFChat.init() in a Client Component.

Tip: on localhost, you must provide a projectId. In production, if your project has a domain set, you can omit it and let HumanFirst.chat resolve the project by website host.

3) Option A — Script tag

Add this right before </body> (works everywhere):

<script src="https://humanfirst.chat/widget.global.js" data-project-id="YOUR_PROJECT_ID"></script>

That’s it — the widget loads and auto-initializes.

Calling commands

The script exposes window.HFChat. Commands are queued until the widget is ready, so you can call them immediately:

<script>
  // After the script tag (or after DOMContentLoaded)
  window.HFChat?.open()
  window.HFChat?.identify({ email: "jane@example.com", plan: "pro" })
</script>

4) Option B — npm SDK

Install the SDK:

pnpm add @humanfirst/js

Next.js (Client Component):

"use client";
import { useEffect } from "react";
import HFChat from "@humanfirst/js";

export function SupportChat() {
  useEffect(() => {
    void HFChat.init({ projectId: "YOUR_PROJECT_ID" });
  }, []);

  return <button onClick={() => HFChat.open()}>Chat</button>;
}

Why use the SDK?

You can call HFChat.open() (and other commands) right away. The SDK loads the widget script in the background and runs your command once the widget is ready.

Production domain install (optional)

If you set a domain for your project in the dashboard, you can omit projectId in production and let HumanFirst.chat resolve the correct project from your website host.

<script src="https://humanfirst.chat/widget.global.js"></script>
<script>
  // Works in production if the domain is configured in the dashboard.
  // On localhost you still must pass projectId.
  HumanFirstChat.init({ logs: "minimal" });
</script>

Widget API (commands)

Control the widget from JavaScript: open/close, hide/show, identify visitors, and update appearance.

Using the npm SDK

Import @humanfirst/js and call methods directly.

import HFChat from "@humanfirst/js";

void HFChat.init({ projectId: "YOUR_PROJECT_ID" });
HFChat.open();

HFChat.identify({ email: "jane@example.com", name: "Jane" });
HFChat.configure({ widgetPosition: "left", widgetColor: "#2563eb" });

HFChat.onReady(() => {
  // Safe place to run commands that depend on the widget being ready
});

Using the script tag

After the script loads, the widget exposes window.HFChat (and HumanFirstChat.init).

<script src="https://humanfirst.chat/widget.global.js" data-project-id="YOUR_PROJECT_ID"></script>
<script>
  // After the script tag (or after DOMContentLoaded)
  window.HFChat?.open();
  window.HFChat?.identify({ email: "jane@example.com", name: "Jane" });
</script>

Command reference

show() / hide() — Show or hide the widget entirely

open() / close() / toggle() — Control the chat panel

isOpen() — Returns whether the panel is open

identify(meta) — Attach visitor metadata (email, name, and any custom fields)

configure(settings) — Change widget UI (color/position/size)

onReady(cb) — Runs when the widget is fully ready (useful for “run after load”)

onOpen(cb) / onClose(cb) — Runs when the panel opens/closes

ready — Boolean flag indicating readiness

Troubleshooting

If the bubble doesn’t appear, check your snippet (script URL + data-project-id) and open the browser console for errors.
If your site has a strict CSP, allow script-src, connect-src, and frame-src for https://humanfirst.chat.
On localhost, always provide a projectId (domain-based resolution only works in production).