Web SDK

The Web SDK, @harmona-ai/chat-sdk, puts an agent on your site as a launcher button and a chat panel. It streams replies, renders rich cards and runs in its own Shadow DOM, so your page's styles and the widget's never collide. It works with React, Vue, Angular, Svelte or plain HTML.

Turn it on in Harmona

1. 1Open the agent in Studio → Agents and open its Output Channels.
2. 2Turn on Web SDK. The widget talks through the API, so API Access is turned on with it.
3. 3Under API Keys, create a key for the widget. See REST API.
4. 4Select Configure the widget to set its look and texts.

Install with npm

The package is private, on GitHub Packages. Harmona gives you a read-only access token for it. Add the token to an .npmrc, then install:

# .npmrc (keep this token out of source control)
@harmona-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${HARMONA_ACCESS_TOKEN}

npm install @harmona-ai/chat-sdk

import HarmonaChat from "@harmona-ai/chat-sdk";

const chat = HarmonaChat.init({
  baseUrl: "https://api.harmona.ai",
  apiKey: "hapi_your_widget_key",
});

That is all the code you need. The launcher appears at the bottom right, and everything else comes from what you configured in Harmona. Call init once, for example in your root layout, and chat.destroy() when you unmount it. In Next.js, call it from a client component, because it needs the browser window.

Use a script tag

The package also contains a standalone browser build, dist/harmona-chat.global.js, which defines window.HarmonaChat. Serve that file from your own site and load it with a script tag:

<script src="/assets/harmona-chat.global.js"></script>
<script>
  HarmonaChat.init({
    baseUrl: "https://api.harmona.ai",
    apiKey: "hapi_your_widget_key",
  });
</script>

Configure it without code

Configure the widget opens an editor with a live preview of the real widget. The widget fetches this configuration when it starts, so your changes reach your site without a deploy.

What you pass to init always wins, field by field: SDK defaults, then the Harmona configuration, then your code. Pass remoteConfig: false to ignore the Harmona configuration entirely.

Init options

init returns a handle with open, close, toggle, show, hide, destroy, setColorScheme, setUser, setFallback and setAgent. The widget never navigates on its own: links and link cards go through your onRedirect hook. Each widget session starts a new conversation.

Live-support bar

The handoff bar lets a visitor ask for a person. Turn it on in the Live support tab, where you set its title, subtitle, colour and icon (support, WhatsApp, phone, mail or your own image). When a visitor selects it, the widget calls your onHandoff hook. Without a hook, it opens the target link you set, for example a WhatsApp link.

HarmonaChat.init({
  baseUrl: "https://api.harmona.ai",
  apiKey: "hapi_your_widget_key",
  handoff: { enabled: true, label: "Talk to a representative" },
  fallbacks: {
    onHandoff(ctx) {
      // ctx.transcript: { agent_name, messages: [{ role, content }] }
      sendToSupportDesk(ctx.transcript);
      window.open("https://wa.me/15550000000", "_blank");
    },
  },
});

The hook receives the conversation so far in ctx.transcript: the agent's name and a plain list of the visitor's and the agent's messages, ready to forward to your support team. It is the same data as GET /b2c/v1/chat/handoff in the REST API.

Language

The widget's labels come in English and Turkish. Set Widget language in the Content tab, or locale in code. It is independent of the language you use Harmona in.

Events and billing errors

fallbacks.onEvent receives every notable interaction as { name, data }: open, close, session_start, response_start, response_end, response_error, grid_click, starter_click, quick_reply_click, message_send, redirect and handoff.

If the workspace can't spend (HTTP 402), visitors see "The assistant is temporarily unavailable. Please try again later." and keep the text they typed. Your code receives response_error with code payment_required, so you can alert your team:

HarmonaChat.init({
  baseUrl: "https://api.harmona.ai",
  apiKey: "hapi_your_widget_key",
  fallbacks: {
    onEvent({ name, data }) {
      if (name === "response_error" && data?.code === "payment_required") {
        reportToOps("Harmona chat unavailable: " + data.error);
      }
    },
  },
});