Install the widget on your site

Every surface a customer touches (the chat widget, the customer portal, the feedback boards) is powered by one small loader script. This page covers how to install it and what it actually does on the page. Everything else a developer needs (the JavaScript API, signed identity, the REST API, webhooks, realtime) is covered in the rest of this Developer section.

Get your publicKey

Each widget you create in Settings > Widgets gets its own publicKey, a short opaque id that scopes every public request to that one widget's organization and configuration. Create a widget from the "New widget" form in that page, then open it to reach the Install tab, which shows the exact snippet for that widget.

The publicKey is meant to be public. It is embedded in a script tag that ships in your page source, so it carries no authentication power on its own beyond identifying which widget's theme, behavior, and content to serve. Anything that needs to trust who the visitor actually is goes through signed identity instead (see the Signed identity article).

The install snippet

Paste one line before the closing </body> tag on every page where you want the widget available:

<script src="https://yourapp.example.com/api/embed/{publicKey}" async></script>

Replace https://yourapp.example.com with your Hark deployment's URL and {publicKey} with the key from the Install tab. The async attribute is safe to keep: the script has no dependencies and does not block page rendering.

What the script does

The endpoint returns a small, dependency-free JavaScript file built specifically for your widget's current configuration. When it runs, it:

• Injects a floating launcher button, positioned and styled from your widget's appearance settings (palette, launcher style, size, offset).
• Adds a hidden iframe pointing at {origin}/embed/{publicKey}, which is where the actual chat UI lives. The iframe only becomes visible when the launcher is clicked or the widget is opened programmatically.
• Resolves its own origin from the src of the script tag that loaded it, so the same snippet works unmodified across your dev, staging, and production hosts.
• Applies your configured launcher visibility rules (device, audience, URL conditions, delay, and scroll gates) and arms any proactive messages you have set up.
• Sets window.Hark, an object with open, close, identify, and setContext methods your own page code can call. See the JavaScript API article for the full signatures.

The script sets no cookies and loads nothing from a third-party host. A visitor's conversation is tracked with a widget-scoped identity the embed assigns on first load.

One script per widget

If you run multiple widgets (for example, a different theme or flow set for different products or brands), install a separate script tag for each widget's publicKey. Each loader is self-contained and namespaced by its key, so multiple widgets can coexist on the same page without colliding.

Domains

Today the widget loads on any site that includes the snippet; there is no domain allow-list enforced yet. If your publicKey were to leak, someone could embed your widget's public-facing surface on another site, though they still could not read or act on data that requires signed identity or your organization's session. Treat the key as public but not something you advertise unnecessarily.

Where to go next

• JavaScript API: call open, close, identify, and setContext from your own code, and receive events back from the widget.
• Signed identity: prove who a logged-in visitor is with an HMAC-signed token, generated on your server.
• Embed REST API: the underlying public endpoints the loader and the widget UI call, with an interactive explorer to try them.