Waniwani SDK — Build MCP funnels

Every surface of the chat widget is themeable through the same token system, whether you use the script embed or the React component. Defaults are pinned so an untouched widget looks the same across releases — you only override what you care about.

Presets

Pick light (default), dark, or auto (follows the visitor’s prefers-color-scheme):

<!-- Script embed -->
<script src="…/embed.js" data-token="wwp_..." data-theme="dark"></script>

// React
<WaniwaniChat token="wwp_..." channelId="..." overrides={{ appearance: { theme: "auto" } }} />

Theme tokens

Layer per-property overrides on top of a preset. The same keys work everywhere:

// React — ChatEmbed or WaniwaniChat (via overrides.appearance)
<ChatEmbed
  api="/api/my-chat"
  appearance={{
    theme: "light",
    variables: {
      primaryColor: "#0a6c74",
      userBubbleColor: "#0a6c74",
      userBubbleTextColor: "#ffffff",
      messageBorderRadius: 20,
      messagePaddingX: 18,
      messageMaxWidth: "75%",
      fontFamily: "Georgia, serif",
      fontSize: 15,
      lineHeight: "1.6",
    },
  }}
/>

// Script embed — programmatic init
window.WaniWani.chat.init({
  token: "wwp_...",
  appearance: {
    theme: "light",
    variables: { primaryColor: "#0a6c74", messageBorderRadius: 20 },
  },
});

CSS variables

The widget exposes a --ww-* namespace that pierces the Shadow DOM boundary, so the script embed can be themed from your page’s own CSS:

<style>
  [data-waniwani-embed] {
    --ww-primary: #0a6c74;
    --ww-msg-radius: 20px;
    --ww-font: "Inter", sans-serif;
  }
</style>
<div data-waniwani-embed></div>

In floating mode there is no container of your own, so declare the variables on any ancestor — :root is the simplest. They inherit down into the widget either way. Unset variables fall back to the preset’s defaults, and your overrides win in both light and dark modes. borderWidth and boxShadow are the panel’s opt-in chrome — both are no-ops until you set them, so a widget slotted into your own bordered container doesn’t draw a second border. In the script embed they apply to the [data-waniwani-embed] container rather than the chat inside it, since the container clips anything drawn within.

CSS Variable	Theme token	Property	Default (light)	Default (dark)
`--ww-primary`	`primaryColor`	Primary brand colour	`#6366f1`	`#6366f1`
`--ww-primary-fg`	`primaryForeground`	Text on primary	`#1f2937`	`#ffffff`
`--ww-bg`	`backgroundColor`	Panel background	`#ffffff`	`#212121`
`--ww-text`	`textColor`	Default text colour	`#1f2937`	`#ececec`
`--ww-muted`	`mutedColor`	Secondary text	`#6b7280`	`#8e8ea0`
`--ww-border`	`borderColor`	Border colour	`#e5e7eb`	`#444444`
`--ww-border-width`	`borderWidth`	Panel border width (px)	`0`	`0`
`--ww-shadow`	`boxShadow`	Panel box-shadow shorthand	`none`	`none`
`--ww-assistant-bubble`	`assistantBubbleColor`	Assistant bubble bg	`#f3f4f6`	`#2f2f2f`
`--ww-assistant-bubble-text`	`assistantBubbleTextColor`	Assistant bubble text	`#1f2937`	`#ececec`
`--ww-user-bubble`	`userBubbleColor`	User bubble bg	`#f4f4f4`	`#303030`
`--ww-user-bubble-text`	`userBubbleTextColor`	User bubble text	`#1f2937`	`#ffffff`
`--ww-input-bg`	`inputBackgroundColor`	Input field bg	`#f9fafb`	`#2f2f2f`
`--ww-header-bg`	`headerBackgroundColor`	Header background	`#ffffff`	`#1e1e1e`
`--ww-header-text`	`headerTextColor`	Header text	`#1f2937`	`#ececec`
`--ww-status`	`statusColor`	Status dot	`#22c55e`	`#22c55e`
`--ww-tool-card`	`toolCardColor`	Tool call card bg	`#f4f4f5`	`#262626`
`--ww-glass-tint`	`glassTint`	Floating bar glass tint	`unset`	`unset`
`--ww-glass-tint-opacity`	`glassTintStrength`	Floating bar glass tint strength	`unset`	`unset`
`--ww-radius`	`borderRadius`	Panel border-radius	`16px`	`16px`
`--ww-msg-radius`	`messageBorderRadius`	Message bubble radius	`8px`	`8px`
`--ww-msg-pad-x`	`messagePaddingX`	Message bubble padding X	`16px`	`16px`
`--ww-msg-pad-y`	`messagePaddingY`	Message bubble padding Y	`12px`	`12px`
`--ww-msg-max-width`	`messageMaxWidth`	Message bubble max width	`80%`	`80%`
`--ww-font`	`fontFamily`	Font family	system stack	system stack
`--ww-font-size`	`fontSize`	Base message font size	`1rem`	`1rem`
`--ww-line-height`	`lineHeight`	Base message line height	`1.5`	`1.5`

glassTint and glassTintStrength tint the floating bar’s frosted-glass surface — the expanded suggestion card and open panel in floating mode — layering a colour over the existing backdrop blur. glassTint takes any CSS colour string; glassTintStrength is a unitless string from "0" to "1" setting how strongly the tint is applied. Both are set programmatically through appearance.variables:

// React — tint the floating bar's frosted glass with a brand colour
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    appearance: {
      variables: { glassTint: "#0a6c74", glassTintStrength: "0.12" },
    },
  }}
/>

Like borderWidth and boxShadow, they’re additive: leave them unset and the floating bar renders exactly as before.

Assistant message bubble (opt-in)

Assistant replies render as plain text by default. Turn them into filled bubbles — styled by assistantBubbleColor / assistantBubbleTextColor, sharing the user bubble’s radius and padding — with assistantBubble:

<!-- Script tag: "true"/"1" or a bare attribute enable it; "false" forces it off -->
<script src="…/embed.js" data-token="wwp_..." data-assistant-bubble="true"></script>

// React
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{ appearance: { assistantBubble: true } }}
/>

Leave it unset and assistant messages stay bubble-less — existing widgets are unchanged.

Deep customization

Tokens cover colors, typography, and bubble shape. To restyle an element beyond what a token exposes, target it directly. React — pass classNames (available on ChatEmbed directly, or overrides.classNames on WaniwaniChat). Each string is merged onto that slot:

<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    classNames: {
      root: "my-chat",
      header: "ww:uppercase ww:tracking-wide",
      userBubble: "ww:shadow-md",
      input: "ww:ring-2 ww:ring-[#0a6c74]",
    },
  }}
/>

Slots: root, header, message, userBubble, assistantBubble, input. Script embed — the widget renders in a Shadow DOM, so your page’s own selectors cannot reach inside. Inject a stylesheet with data-css and target the stable semantic classes:

<script
  src="…/embed.js"
  data-token="wwp_..."
  data-css="https://your.site/widget.css"
></script>

/* widget.css — loaded into the widget's Shadow DOM */
.ww-header { letter-spacing: 0.02em; }
.ww-input { box-shadow: 0 0 0 2px rgba(10, 108, 116, 0.25); }
.ww-message-user .ww-bubble { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
.ww-message-assistant .ww-bubble { border: 1px solid #0a6c74; }

Stable hooks: .ww-message, .ww-message-user, .ww-message-assistant, .ww-bubble, .ww-header, .ww-input. These are guaranteed selectors — the internal ww:-prefixed utility classes are not.

What is not themeable

To set expectations for a full rebrand, these are intentionally fixed today:

Typographic scale beyond the base — fontSize / lineHeight set the message base; per-heading sizes inside markdown and built-in label sizes/weights are not individually exposed.
Chrome corner radii — messageBorderRadius shapes message bubbles only; tool-call cards, the chain-of-thought accordion, menus, and welcome-screen buttons keep their fixed radii.
Floating launcher accent — the dock’s animated border-glow uses a fixed accent gradient.
“Powered by” mark — the footer logo is not removable via theming.

For anything in this list, reach out — some are candidates for future tokens. Full type definitions: ChatTheme and ChatClassNames.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Modules

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Theming & customization

Presets

Theme tokens

CSS variables

Assistant message bubble (opt-in)

Deep customization

What is not themeable

​Presets

​Theme tokens

​CSS variables

​Assistant message bubble (opt-in)

​Deep customization

​What is not themeable

Presets

Theme tokens

CSS variables

Assistant message bubble (opt-in)

Deep customization

What is not themeable