docs
    site-kit: Website chat
    v7.2.0.md

    Website chat — @sonordev/site-kit/chat

    Echo's chat launcher and conversation on your site, configured in Sonor (Messages → Chat settings). AI answers, live handoff to your team, and an offline form when nobody's around.

    Usage

    SiteKitLayout mounts it for you, after the page goes idle:

    <SiteKitLayout>{children}</SiteKitLayout>                          // chat on (default)
<SiteKitLayout chat={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>
<SiteKitLayout chat={false}>{children}</SiteKitLayout>             // no chat

    On a site without SiteKitLayout, mount SiteChat the same way:

    'use client'
import { SiteChat } from '@sonordev/site-kit/chat'

export function Chat() {
  return <SiteChat position="bottom-right" />
}

    SiteChat waits for the browser to go idle, skips cross-origin frames and localhost (like analytics), and downloads the chat widget only when it renders. ChatWidget is the widget itself, for a page that resolves those choices on its own.

    Props

    interface SiteChatProps {
  apiUrl?: string                            // Default: from SiteKitLayout, else https://api.sonor.io
  apiKey?: string                            // Default: from SiteKitLayout
  projectId?: string                         // For chat routing. Resolved from the key when absent
  position?: 'bottom-right' | 'bottom-left'  // Default: 'bottom-right'
  offsetBottom?: string | number             // Default: '20px'. See "Launcher placement"
  zIndex?: number                            // Default: 9999. See "Stacking"
  allowInFrame?: boolean                     // Show inside a cross-origin frame. Default: false
  allowLocalhost?: boolean                   // Show on localhost. Default: false
}

    Through SiteKitLayout, the placement options go in chat={{ ... }}. The deprecated engage={{ ... }} still works through 7.x.

    The chat switch

    Echo follows the project's Show the chat widget switch in Sonor (Messages → Chat settings). A project that has never saved chat settings counts as on, so Echo is on by default and only an owner who switches it off hides it. It also needs the project's Website chat module on (Project Settings); without it Sonor answers off, since the chat has nowhere to take a visitor's message.

    • The launcher appears once GET /engage/widget/config answers. Nothing renders before that, so a switched-off site never flashes a launcher, and it never starts Echo's availability polling.
    • If the config can't be fetched, the launcher stays hidden. The chat can't run without the API anyway.
    • chat={false} in code still turns chat off whatever the switch says. Code can turn Echo off; it can't force it on over the owner's switch.

    Liquid Glass (6.1.0)

    Echo's launcher and chat window are made of the kit's shared Liquid Glass recipe (src/shared/glass.tsx), the same material as the mobile CTA bar (@sonordev/site-kit/cta-bar), so the two always match.

    • Launcher: brand-tinted glass (86% brand over a blurred backdrop) with a specular rim. The icon turns dark on a light brand colour; it used to stay white and disappear.
    • Chat window: a glass panel (86% tint, 28px blur) that grows out of the launcher's corner. The header is part of the sheet, washed with the brand at the top, and the brand sits on the avatar tile, the visitor's bubbles, the send button and the launcher.
    • Bubbles and the composer stay near-opaque (94%). The glass is depth, never the surface text reads against.
    • Brand text always reads (6.1.2). Where the brand is text on the panel (quick-action chips, the phone link, link buttons, suggestion chips, "Talk to a person"), Echo uses the brand as-is when it clears WCAG AA against the panel, and otherwise pulls it toward black (light panel) or white (dark panel) just far enough to clear it: #d4af37 gold becomes #887023. Fills (launcher, avatar, the visitor's bubbles, buttons) keep the raw brand. One helper decides this, src/chat/brand-color.ts; route any new brand foreground through it. --sk-primary can be hex, rgb() or hsl().
    • Fields are 16px. iOS Safari zooms the whole page into any focused field under 16px; the chat input and the inline Echo forms were 13.5-14px.
    • Fallbacks: no backdrop-filter, reduced transparency, or more contrast all get the same surfaces solid. Reduced motion skips the open animation.

    Tune it with the shared tokens, from your own stylesheet:

    :root {
  --sk-glass-panel-opacity: 92%;   /* denser chat window (default 86%) */
  --sk-glass-brand-opacity: 100%;  /* solid brand launcher (default 86%) */
  --sk-glass-tint: #0b0b0c;        /* dark glass; pair with --sk-text-primary */
}

    --sk-glass-panel-opacity: 100% gives the pre-6.1 solid window back, with the glass header.

    Launcher placement

    The Echo launcher is a 60px circle, fixed 20px from the side and 20px above the bottom edge. Its placement is an inline style, so a stylesheet can't move it without !important. Don't write that override; declare the offset instead.

    A fixed offset, every page: pass offsetBottom.

    <SiteKitLayout chat={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>

    Any CSS length works ('5.5rem', 'calc(4rem + 8px)'); a number is pixels. The device's safe-area inset is added on top, so pass the clearance you want above your own UI, not the inset.

    An offset that depends on the page or the breakpoint: set the --sk-echo-offset-bottom custom property from your stylesheet. The launcher is portalled to <body>, so a declaration on body or :root reaches it, and the property wins over offsetBottom. This clears a sticky mobile bar only on the pages that render one:

    @media (max-width: 1023.98px) {
  body:has(.sticky-cta) {
    --sk-echo-offset-bottom: 5.5rem;
  }
}

    Pages without the bar, desktop, and any browser without :has() keep the default. No !important, no selector on the kit's markup.

    Using the kit's <CtaBar>? Write nothing. It sets --sk-echo-offset-bottom itself while it's on screen, below its breakpoint, and the launcher glides up and back down as the bar shows and hides. Delete any rule like the one above that was written for a hand-rolled bar.

    The popup follows. It opens 10px above the launcher and keeps 30px clear of the top edge, wherever the offset puts the launcher. (An override that moved only the <button> left the popup behind, with the launcher over its input row.)

    The resolved position is:

    launcher bottom = offset + env(safe-area-inset-bottom) + var(--sk-vv-layout-gap, 0px)
popup bottom    = launcher bottom + 70px
popup maxHeight = 100dvh - launcher bottom - 100px

    Stacking

    zIndex is the layer the chat launcher sits on, with the chat window one layer beneath it. Through SiteKitLayout the same number also stacks the site's popups, banners and toasts. The default is 9999, above almost anything a site draws, so lower it when your own fixed UI (a mobile menu, a cookie banner) has to cover the chat:

    <SiteKitLayout chat={{ zIndex: 40 }}>{children}</SiteKitLayout>
    launcher z-index = zIndex (default 9999)
popup z-index    = zIndex - 1

    At zIndex 0 or below the chat window shares the launcher's layer instead, because -1 would put it behind the page's own content. The launcher still paints on top.

    Layout vs visual viewport on phones

    On a phone the layout viewport can be taller than what the visitor can see (browser chrome, in-app browsers, pinch zoom), and position: fixed is measured against the layout viewport, so a bottom-fixed launcher can sit below the fold. Mount VisualViewportGap to publish the difference as --sk-vv-layout-gap on <html>. The launcher and popup already read it, and your own fixed bottom UI can too:

    import { VisualViewportGap } from '@sonordev/site-kit/client'

<SiteKitLayout>
  <VisualViewportGap />
  {children}
</SiteKitLayout>
    .mobile-cta {
  bottom: calc(24px + env(safe-area-inset-bottom, 0px) + var(--sk-vv-layout-gap, 0px));
}

    It's opt-in: while a field has focus the gap grows to the keyboard's height, so everything that reads it rides above the keyboard. useVisualViewportGap() is the hook form for an existing client component.

    Chat config

    AI mode (Echo), live mode, and hybrid (AI with a human handoff). ChatWidget takes these as config; Sonor sends the rest from Chat settings:

    interface ChatConfig {
  position: 'bottom-right' | 'bottom-left'
  offsetBottom?: string | number   // See "Launcher placement"
  zIndex?: number                  // Default: 9999. See "Stacking"
  mode: 'ai' | 'live' | 'hybrid'
  buttonColor?: string
  aiSettings?: {
    skillId?: string
    handoffToLive?: boolean
    handoffKeywords?: string[]
  }
  operatingHours?: { ... }
  offlineMode?: 'form' | 'ai' | 'message'
  offlineFormSlug?: string
}

    Popups

    Popups, banners and toasts are their own module now: Popups and banners (@sonordev/site-kit/website/popups).

    @sonordev/site-kit/engage (deprecated)

    Engage was retired in Sonor. Its entry stays through 7.x so old imports keep building: ChatWidget and the chat types re-export from here, and EngageWidget draws SiteChat and SitePopups. Engage Studio's renderer (DesignRenderer) is gone; popups render from blocks. Import @sonordev/site-kit/chat and @sonordev/site-kit/website/popups instead.