Holaboss Docs

Embed a Holaboss employee conversation and render it yourself — createHolaClient, the useChat / useThread hooks, streaming handlers, and the optional <Chat> component.

Reference · SDK

The chat surface lets you drop an employee conversation into your own app and render whatever UI you want. You get a client and a hook; the bubbles, composer, and layout are yours.

The client

import { createHolaClient } from "@holaboss/client";

const client = createHolaClient({
  baseUrl: "https://api.holaos.ai",
  token: "CONNECTOR_TOKEN",            // string or an async getter
});

Drive it manually with streaming or one-shot sends:

await client.streamMessage("hello", {
  onText: (delta) => {/* append to the live bubble */},
  onTool: (step) => {/* show a tool step */},
  onComplete: ({ reply, artifacts }) => {/* final reply + generated files */},
  onError: ({ error }) => {/* surface it */},
});

await client.sendMessage("hello"); // non-streaming variant

`useChat`

The hook manages message state, the composer input, and a streaming send:

import { useMemo } from "react";
import { createHolaClient, useChat } from "@holaboss/client";

function Chat() {
  const client = useMemo(
    () => createHolaClient({ baseUrl, token }),
    []
  );
  const { messages, input, setInput, send, sending } = useChat(client);

  return (
    <YourLayout>
      {messages.map((m) => (
        <YourBubble key={m.id} role={m.role} text={m.text} artifacts={m.artifacts} />
      ))}
      <YourComposer value={input} onChange={setInput} onSend={send} busy={sending} />
    </YourLayout>
  );
}

useThread is the sibling for a persistent thread (one durable conversation per customer, restored across reloads); mergeMessage is the helper it uses to fold streaming deltas into a message.

Streaming helpers

When you handle raw stream events yourself, these narrow them for you:

import { textDeltaOf, thinkingDeltaOf, toolEventOf } from "@holaboss/client";

textDeltaOf / thinkingDeltaOf pull the text (or the model's thinking) out of an event; toolEventOf recognizes a tool step. Together with HolaStreamHandlers they're all you need to render a live turn.

Optional starter UI

If you just want something on screen, there's a minimal, unstyled <Chat>:

import { Chat, createHolaClient, HolaProvider } from "@holaboss/client";

<HolaProvider client={client}>
  <Chat />
</HolaProvider>;

It's a convenience, not the product — real apps use useChat + their own components. useHolaClient reads the client from context anywhere below the provider.

Verified visitors

Turn an anonymous visitor into an identified one (so the employee gets per-user memory) by signing their id on your server and passing it as identity:

createHolaClient({
  baseUrl,
  token,
  identity: {
    externalUserId: user.id,
    userHmac, // hex HMAC-SHA256(user.id, secret), computed server-side
  },
});

The HMAC must be computed on your server with your secret — never in the browser. It's what lets Holaboss trust that this visitor really is user.id.

Chat

The client

useChat

Streaming helpers

Optional starter UI

Verified visitors

On this page

`useChat`