Widget options

Options are data-attributes on the script tag. The greeting, colours, away message and pre-chat form are set on the inbox in Kommio and apply everywhere; these attributes only change how the widget behaves on the site that carries the tag.

<script src="https://app.kommio.io/widget/widget.js"
  data-key="INBOX_PUBLIC_KEY"
  data-position="left"
  data-color="#1F4D3A"
  data-locale="pt-BR"
  data-launcher="hidden"
  data-theme="dark"
  async></script>

data-key

Type string · Required

The public key of a website chat inbox, shown on the inbox's Install tab. It addresses the inbox and is safe to publish; which sites may show the chat is set separately under allowed websites. Without data-key the script loads but does not start, so you can start it yourself with Kommio.init().

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" async></script>

data-position

Type right | left · Default right

The bottom corner that holds the button and the chat panel. Use left when another element, such as a cookie banner or a back-to-top button, already sits bottom right.

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-position="left" async></script>

data-color

Type #RRGGBB · Default the inbox colour, else the workspace brand colour, else #0062D1

The launcher button's colour on this site. It wins over the inbox and workspace colours for the button only; the chat panel keeps the inbox's theme. Six hex digits with a leading #; short forms like #FFF and colour names are ignored. Pick a colour that keeps the white chat icon readable.

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-color="#1F4D3A" async></script>

If your workspace sets a logo mark in Branding, it replaces the chat icon on the button.

data-locale

Type language tag · Default the visitor's browser

The language of the chat's own texts: en, pt-BR, es, fr, de, it, nl, pl, tr, id, ja, ko, zh-CN, hi, fil or ur. Set it when your site has its own language switcher, so the chat follows the page rather than the browser. A language Kommio does not ship falls back to the visitor's browser languages, then English. Texts you write on the inbox, such as the greeting, are shown as you wrote them.

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-locale="pt-BR" async></script>

data-launcher

Type hidden · Default button shown

hidden removes the round button: the chat panel stays closed until your page opens it with Kommio.open() or Kommio.toggle(), for example from a "Chat with us" link in your navigation. The unread count is then yours to show, from the unread event. A complete example is under Your own chat button. (default is also accepted and means the same as leaving the attribute out.)

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-launcher="hidden" async></script>

The launcher button

Each website chat inbox sets its button under Settings → Inboxes → the inbox → Install → Appearance, with a live preview closed and open, in light and dark:

• Shape: circle (the default), rounded square, pill with an icon and a label, or a tab on the edge of the screen, vertically centred, with the chat opening beside it. On screens up to 480 px wide a pill shows as a circle so it never covers your content.
• Label for the pill and the tab: up to 30 characters of plain text. Left empty, it reads "Chat with us" in the visitor's language.
• Icon: chat bubble, two bubbles, headset, question mark, smile, waving hand, or your workspace mark (the default, so existing buttons look unchanged).
• Icon while open: a close cross (the default) or a chevron, swapped with a short turn and fade, instantly for visitors who prefer reduced motion.
• Size: small, medium or large (48, 56 or 64 px), always with a touch target of at least 44 px.
• Distance from the side and bottom edges: 0 to 120 px (20 by default), for example to clear a cookie bar. The tab ignores it.

A page can override the shape, icon and size with data-launcher-shape, data-launcher-icon and data-launcher-size (or launcherShape, launcherIcon and launcherSize in Kommio.init()); the label, the open icon and the distances are set on the inbox only. The button is named "Open chat" for screen readers (a pill or tab by its visible label) and "Close chat" while the chat is open. Try every combination on the demo store, which also takes ?shape=, &icon= and &size= in its address.

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-launcher-shape="pill" data-launcher-icon="headset" data-launcher-size="large" async></script>

data-theme

Type auto | light | dark · Default the inbox's Chat colours setting (auto unless changed)

The chat's colours on this site. It wins over the inbox's setting, so a site that is always dark can say dark, and a site with its own theme switch can leave it out and let auto follow the page. How auto decides is under Colours (light and dark).

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-theme="dark" async></script>

data-proactive

Type off · Default proactive messages on

Keeps the inbox's proactive messages off this page, for example a checkout or a payment step, while the chat itself stays available.

<script src="https://app.kommio.io/widget/widget.js" data-key="INBOX_PUBLIC_KEY" data-proactive="off" async></script>

Colours (light and dark)

Each website chat inbox has a Chat colours setting (Settings → Inboxes → the inbox → Widget settings): auto (the default), light or dark. A page can choose for itself with data-theme or Kommio.init({ theme }), which wins over the inbox's setting.

auto follows the page the chat is on:

1. a page that declares one colour scheme (color-scheme: dark on the root element, or <meta name="color-scheme" content="dark">) gets that one;
2. otherwise the page's own background decides: an opaque body (or root) background darker than mid-grey is a dark page, so sites that switch themes with a class or with prefers-color-scheme rules work without declaring anything;
3. a page that declares both (light dark) on a transparent background follows the visitor's system setting;
4. anything else is light.

The loader watches the visitor's system setting and the root and body attributes (a theme toggle that swaps a class, a data-theme or a style), and the chat follows while it is open. The launcher, its online dot, the new-message preview, the satisfaction survey card and file cards all follow the chat's theme.

Dark uses Kommio's own dark palette (surface #181B1F, thread #14171A). The brand colour stays yours, with white or near-black text on it, whichever reads at 4.5:1; where the brand colour is used as text on a dark surface (links, outlines) it is lightened just enough to read. With a dark theme the header shows the workspace's dark wordmark (branding.logo_dark_url) and the launcher its dark mark (branding.mark_dark_url) when they are set, else the light ones.

The widget reads all of this from its config (GET /api/widget/{key}/config, in the API reference):

{
  "color": "#1F4D3A",
  "theme": "auto",
  "logo": "https://app.kommio.io/<path>/logo.svg",
  "logo_dark": "https://app.kommio.io/<path>/logo-dark.svg",
  "mark": "https://app.kommio.io/<path>/mark.png",
  "mark_dark": "https://app.kommio.io/<path>/mark-dark.png"
}

data-base-url

Type URL · Default the origin the script was loaded from

Where the chat frame and its API live. The loader normally works this out from its own src, so you need this only when you serve widget.js from somewhere other than Kommio, for example a copy on your own CDN. Trailing slashes are removed.

<script src="https://cdn.example.com/kommio/widget.js"
  data-key="INBOX_PUBLIC_KEY"
  data-base-url="https://app.kommio.io"
  async></script>

The same options in JavaScript

When the tag has no data-key, as with tag managers and frameworks, start the chat with Kommio.init() once the script has loaded. It takes the same options under camel-case names, plus a signed identity for a visitor who is signed in on your site.

<script src="https://app.kommio.io/widget/widget.js" async
  onload="Kommio.init({ key: 'INBOX_PUBLIC_KEY', position: 'left', color: '#1F4D3A', locale: 'es', launcher: 'hidden', theme: 'auto' })"></script>

A second init() while the chat is running is ignored; call Kommio.destroy() first to start again with other options.