Advanced embed

The dashboard generates everything most sites need (Getting started). This page is for developers: script attributes, the chat language, the JavaScript API and the legacy mode.

An integration always shows one channel. To show another channel, create another integration in the dashboard, or use @komozu/react with the channel’s slug or externalId.

Script attributes

The script is pasted where the chat should appear (or anywhere for the bubble). Explicit attributes win over the integration’s settings (cascade: Komozu theme < project color < integration < attributes).

<script src="https://embed.komozu.com/komozu-embed.js" data-komozu-integration="int_…"
        data-komozu-primary-color="#0369A1" data-komozu-theme="dark" defer></script>

Attribute	Values
`data-komozu-integration`	Integration public id (`int_…`), required
`data-komozu-token`	The signed-in member’s token, written by your server (Identify your users). Empty or missing: the chat asks to sign in
`data-komozu-lang`	`en` or `fr` (default: the visitor’s browser language)
`data-komozu-target`	CSS selector of the element that receives the inline chat (default: right after the script tag)
`data-komozu-primary-color`	`#RRGGBB`
`data-komozu-theme`	`auto`, `light`, `dark`
`data-komozu-surface`	`card`, `blend`
`data-komozu-height`	`auto` or a number of pixels
`data-komozu-max-height`	pixels (auto height)
`data-komozu-position`	`bottom-right`, `bottom-left` (bubble)
`data-komozu-radius`	`none`, `sm`, `md`, `lg`, `full`
`data-komozu-title`	chat title
`data-komozu-api-url`	API URL, only for a self-hosted API (default `https://api.komozu.com`)

Images and videos are a setting of the channel (channel page → Settings), not of the page.

Language

The chat (buttons, statuses, error messages) is in English or French. By default it follows the visitor’s browser (French for fr, fr-CA…, English otherwise). To force it:

script: data-komozu-lang="fr";
React: <KomozuChat … locale="fr" /> (@komozu/react).

`window.Komozu`

The loader exposes one API for every chat of the page. Calls made before the chat is ready are queued; a komozu:ready DOM event fires on window.

Komozu.open();                   // bubble
Komozu.close();
Komozu.toggle();
Komozu.setUser({ token });       // a user signs in without reloading the page
Komozu.setUser({ token: null }); // signs out: the chat asks to sign in again
Komozu.setTheme({ primaryColor: '#047857', mode: 'dark' });

Hosted widget messages (`postMessage`)

Between the page and the iframe (origins checked on both sides):

page → iframe: komozu:set_user { token }, komozu:set_theme { theme };
iframe → page: komozu:ready, komozu:resize { height } (inline, auto height), komozu:close (bubble), komozu:token_expired (the API refused the member token: the loader logs [Komozu] The member token was refused (revoked or invalid). Get a new one from your backend.).

Errors in the console

When the chat can’t be shown, nothing is rendered and the loader explains why in the browser console:

[Komozu] This integration doesn't exist or is disabled.
[Komozu] This domain isn't allowed for this project. Add it in Settings → Allowed domains.
[Komozu] data-komozu-integration is required. Copy the code of an integration from your dashboard.

Legacy mode

Scripts without data-komozu-integration keep working, configured entirely by attributes:

<script src="https://embed.komozu.com/komozu-embed.js" data-komozu-client-id="kz_live_…" data-komozu-channel="general"
        data-komozu-layout="inline" data-komozu-surface="card" defer></script>

Add data-komozu-token the same way. The dashboard no longer generates this form; prefer integrations, which you can change without touching your site.