Heyo JS  

HEYO JS is the official JavaScript SDK that loads the HEYO live-chat widget and exposes a tiny, typed API.

One line to install, one line to open a chat.

npm i @heyo.so/js

---

Features

• ⚡ Zero-config – drop‐in, no manual <script> tags required
• 🪶 Tiny – <1 kB gzipped, defers the heavy widget to the CDN
• 🧩 Framework-agnostic – works in React, Vue, Svelte, vanilla HTML…
• 🕰 Race-condition-proof – call HEYO.open() before or after the widget loads; the SDK queues and replays for you
• 📜 First-class TypeScript – autocompletion for every method

---

Quick Start

1 · Import once on the client

import { HEYO } from "@heyo.so/js";

// Use HEYO.init() to load the widget. You can optionally pass options (see below)
HEYO.init({
	projectId: "YOUR_PROJECT_ID", // optional in production, required on localhost
});

2 · Use the API anywhere

HEYO.open(); // open the chat drawer
HEYO.identify({
	userId: "42",
	email: "jane@example.com",
	name: "Jane Doe",
});

HEYO is a global singleton: import it once, use it everywhere, even in the browser console.

---

Configuration (HeyoConfig)

Option	Type	Default	Description
projectId	string?	–	Your HEYO project ID. Required for localhost development
hidden	boolean?	false	Start with the widget fully hidden

Example:

HEYO.init({
	projectId: "abc123",
	hidden: true,
});

---

API (HeyoAPI)

Method	Description
show()	Reveal the floating button / agent card
hide()	Completely hide the widget
open()	Open the chat panel
close()	Close the chat panel
identify(meta)	Pass user metadata (ID, email, name…)
ready (property)	true when the widget is fully loaded

All methods are no-ops until the widget is ready, but thanks to the internal queue you can call them at any time.

---

Framework Recipes

React / Next.js (Client Component)

"use client";
import { useEffect } from "react";
import { HEYO } from "@heyo.so/js";

export default function Page() {
	useEffect(() => {
		HEYO.init({ projectId: "YOUR_PROJECT_ID" });
	}, []);

	return <button onClick={() => HEYO.open()}>Chat with us</button>;
}

Nuxt 3 (plugin)

// plugins/heyo.client.ts
import { defineNuxtPlugin } from "#app";
import { HEYO } from "@heyo.so/js";

export default defineNuxtPlugin(() => {
	HEYO.init({ projectId: "YOUR_PROJECT_ID" });
	return {
		provide: { heyo: HEYO },
	};
});

In components you can now use const { $heyo } = useNuxtApp().

---

Type Definitions

The SDK is written in TypeScript and ships its .d.ts files. Quick peek:

export interface HeyoAPI {
	show(): void;
	hide(): void;
	open(): void;
	close(): void;
	identify(meta: HeyoIdentifyMeta): void;
	readonly ready: boolean;
}

export interface HeyoGlobal extends HeyoAPI {
	init(opts?: HeyoConfig): Promise<HeyoAPI>;
}

License

MIT