Tchao

JavaScript SDK for integrating the Tchao chat widget into your application.

Installation

npm install tchao
# or
pnpm add tchao
# or
yarn add tchao

Quick Start

React (Recommended)

import { useTchao } from "tchao/react";

function App() {
  const { isReady, open, identify } = useTchao({
    websiteId: "your-website-id",
  });

  // Identify user when ready
  useEffect(() => {
    if (isReady && user) {
      identify({ email: user.email, name: user.name });
    }
  }, [isReady, user, identify]);

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

React Provider (Simpler)

import { TchaoProvider } from "tchao/react";

function Layout({ children }) {
  return (
    <>
      <TchaoProvider
        websiteId="your-website-id"
        visitor={{ email: user?.email, name: user?.name }}
      />
      {children}
    </>
  );
}

Vanilla JavaScript

import { tchao } from "tchao";

// Initialize (call once)
await tchao.init({ websiteId: "your-website-id" });

// All methods are safe - no try/catch needed
tchao.identify({ email: "[email protected]" });
tchao.open();

Script Tag

<script
  src="https://tchao.app/widget.js"
  data-website-id="your-website-id"
></script>
<script>
  // Widget auto-initializes
  window.Tchao.identify({ email: "[email protected]" });
</script>

API Reference

React Hook: useTchao(config)

import { useTchao } from "tchao/react";

const {
  isReady, // boolean - widget is initialized
  isLoading, // boolean - widget is loading
  error, // Error | null - initialization error
  show, // () => void
  hide, // () => void
  toggle, // () => void
  open, // (message?: string) => void
  identify, // (info: VisitorInfo) => void
  config, // () => Partial<WidgetConfig>
  on, // (event, callback) => void
  off, // (event, callback) => void
} = useTchao({ websiteId: "..." });

Safe API: tchao

All methods are safe to call at any time - they will queue and execute when ready.

import { tchao } from "tchao";

// Initialize
await tchao.init({ websiteId: "your-website-id" });

// Control methods (safe before/after init)
tchao.show();
tchao.hide();
tchao.toggle();
tchao.open();
tchao.open("I need help with...");

// Identify visitor
tchao.identify({
  email: "[email protected]",
  name: "John Doe",
  avatar: "https://example.com/avatar.jpg",
  metadata: { plan: "pro", userId: "123" },
});

// Events
tchao.on("message", (msg) => console.log(msg));
tchao.on("open", () => console.log("Opened"));
tchao.on("close", () => console.log("Closed"));
tchao.on("ready", () => console.log("Ready"));

// Cleanup
tchao.destroy();

// Status
tchao.isReady(); // boolean

Init Config

tchao.init({
  websiteId: "required",
  host: "https://tchao.app", // optional, for self-hosted
  position: "bottom-right", // "bottom-right" | "bottom-left"
  primaryColor: "#6366f1",
  themeMode: "system", // "light" | "dark" | "system"
  widgetStyle: "bubble", // "bubble" | "name_line" | "question_cta"
  agentName: "Support",
  agentRole: "Customer Support",
  agentImage: "https://...",
  agentWelcomeMessage: "Hi! How can I help?",
  hidePoweredBy: false,
  container: "#chat-container", // CSS selector or DOM element for inline rendering
  demo: true, // Preview mode without backend connection
});

Events

| Event | Callback | Description | | --------- | ---------------------------- | -------------------- | | message | (message: Message) => void | New message received | | open | () => void | Chat window opened | | close | () => void | Chat window closed | | ready | () => void | Widget initialized |

TypeScript

import type {
  TchaoConfig,
  TchaoInstance,
  VisitorInfo,
  Message,
  WidgetConfig,
  TchaoEvent,
  TchaoEventMap,
} from "tchao";

// React types
import type { UseTchaoOptions, UseTchaoReturn } from "tchao/react";

Migration from v0.1.3

The API is backward compatible. New additions:

// New: Safe API (no try/catch needed)
import { tchao } from "tchao";
tchao.identify({ email: "..." }); // Works before init!

// New: React hook
import { useTchao } from "tchao/react";

// New: React provider
import { TchaoProvider } from "tchao/react";

License

MIT