HumanFirst.chat JS SDK

JavaScript SDK for embedding the HumanFirst.chat widget and controlling it from your app.

Install

pnpm add @humanfirst-chat/js

Quick start (React / Next.js)

"use client";

import { useEffect } from "react";
import HFChat from "@humanfirst-chat/js";

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

  return null;
}

Identify a user

HFChat.identify({
  email: "[email protected]",
  name: "Jane Doe",
  userId: "user_123",
  plan: "pro",
});

When to call identify():

• Can be called at any time — before or after the widget loads
• Call it when the user logs in, or whenever user data becomes available
• Can be called multiple times; new data is merged with existing metadata
• The visitor is immediately updated in the agent dashboard

// Example: Identify after login
import { useEffect } from "react";
import { useUser } from "./auth"; // your auth hook
import HFChat from "@humanfirst-chat/js";

export function ChatIdentifier() {
  const user = useUser();

  useEffect(() => {
    if (!user?.email) return;

    HFChat.identify({
      email: user.email,
      name: user.name,
      plan: user.plan,
    });
  }, [user]);

  return null;
}

Control visibility

HFChat.show();
HFChat.hide();
HFChat.open();
HFChat.close();
HFChat.toggle();

Open with focus

HFChat.open({ focus: true });

Custom CTA on a specific page (example: /premium)

Use a page-level CTA that opens the chat with focus, and hide the default launcher on that route.

"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation";
import HFChat from "@humanfirst-chat/js";

export function PremiumChatCTA() {
  const pathname = usePathname();

  useEffect(() => {
    if (pathname !== "/premium") return;
    HFChat.hide();
    return () => HFChat.show();
  }, [pathname]);

  return (
    <button type="button" onClick={() => HFChat.open({ focus: true })}>
      Any question? Chat with me
    </button>
  );
}

Configuration

HFChat.init({
  siteId: "YOUR_SITE_ID",
  hidden: false,
  logs: "minimal",
});

Advanced (self-hosted / custom CDN)

void HFChat.init({
  siteId: "YOUR_SITE_ID",
  scriptSrc: "https://cdn.example.com/widget.js",
  baseURL: "https://your-hfchat.example.com",
});

Notes

• Client-side only: call HFChat.init() in the browser (e.g. useEffect).
• On localhost, siteId is required.
• Methods are queued until the widget finishes loading.