SDK reference

Drop us in. Ship in an afternoon.

One package per platform, one env var, zero backend. Pick your stack — every snippet below is copy-paste ready.

Next.js / WebReact NativeiOS SwiftAndroidVanilla JS

Next.js / Web

Package @tinychat/react.

Install

Add the React package and your publishable key. The widget renders once at the root and follows the user across routes.

bash

npm i @tinychat/react

.env.local

NEXT_PUBLIC_TINYCHAT_KEY=pk_live_xxxxxxxxxxxx

Initialize

Mount <TinyChat> once in your root layout. The provider hydrates client-side and fetches GET /v1/config on mount.

app/layout.tsx

import { TinyChat } from "@tinychat/react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <TinyChat apiKey={process.env.NEXT_PUBLIC_TINYCHAT_KEY} />
      </body>
    </html>
  );
}

Identify the user

Call identify as soon as you know who the user is. The SDK upserts the profile via POST /v1/users and persists it for the session.

components/identify.tsx

"use client";
import { useTinyChat } from "@tinychat/react";

export function IdentifyUser({ user }) {
  const tinychat = useTinyChat();
  tinychat.identify({
    id: user.id,
    name: user.fullName,
    email: user.email,
  });
  return null;
}

Open a conversation

Deep-link straight into a thread — useful for “Chat with driver” or “Contact seller” buttons. Pass an externalRef so re-opening returns the same conversation.

tsx

tinychat.open({
  externalRef: orderId,
  kind: "order",
  participants: [user.id, driverId],
});

Listen for events

Hook into widget lifecycle and inbound messages. Under the hood the SDK posts to /api/v1/conversations/:id/messages and subscribes to conv:<id> on Supabase Realtime — see Realtime in the API reference.

tsx

tinychat.on("message", (m) => {
  console.log("inbound", m);
});

tinychat.on("toggle", (open) => {
  console.log("widget open:", open);
});

Need the raw HTTP API?

Same surface, just a fetch away.

The SDKs are thin wrappers over the REST surface — anything they do, you can do directly with a request from your server.

API reference

Embedding on a static site? Use the Vanilla JS snippet above.

See it live on /support