Waniwani SDK — Build MCP funnels

The chat embed is a self-contained IIFE bundle that drops the Waniwani chat into any website. It talks directly to app.waniwani.ai, so no backend proxy is required on your side.

Platform feature. The dashboard generates the embed snippet for your project. Open app.waniwani.ai to get yours, or read more about the Platform.

Quick start

Open your project on app.waniwani.ai and copy the chat embed snippet from the project settings.
Paste it into your site’s HTML, alongside a mount point where you want the chat to appear:

<!-- Where the chat appears, sized by your CSS -->
<div data-waniwani-embed style="height: 600px; max-width: 480px;"></div>

<!-- The <script> tag you copied from the dashboard goes here. -->

That’s it. The chat mounts inside your marker div via Shadow DOM (so its styles never leak into your page). The snippet carries identifiers only — your project token, the channel ID, and the API URL. Title, welcome message, placeholder, suggestions, thread history and tool-call display are never baked in: the embed fetches them from your channel at runtime, so changing them in the dashboard updates live sites with no redeploy. Theming is the exception — it has no dashboard equivalent and is set on the tag (data-theme) or in CSS. Don’t hand-author the snippet — the channel ID is issued by the Platform and required for the embed to route correctly.

Modes

The embed renders in one of four modes, set with data-mode on the <script> tag:

Mode	What it does
`inline` (default)	Mounts the chat into a `<div data-waniwani-embed></div>` marker on the page. You control the size with CSS or `data-height`. If no marker exists, one is created in front of the `<script>` tag, so a bare snippet works with no markup changes — note that a container we create renders as a centered card (max-width `28rem`, rounded, bordered), while one you place is styled entirely by you.
`floating`	Docks a compact composer bar at the bottom center of the viewport. Clicking it expands the bar, and starting a conversation opens the full chat panel — bottom-anchored and width-capped on desktop, full-screen on mobile. No marker element needed.
`composer`	Mounts just the input, plus the channel’s suggestion pills, into your `<div data-waniwani-embed></div>` marker. Sending the first message (Enter, the send button, or a pill) opens the same panel `floating` uses, over the page. The box is content-height and as wide as its container, so you place it like any other page element.
`off`	Mounts no chat at all: no dock, no marker box, no panel. The tag still publishes your site’s MCP tools to a browsing agent standing on the page, and `WaniWani.chat.track` / `.identify` still work, so a site can carry the script without showing a widget to its visitors. The chat methods (`open()`, `sendMessage()`, …) become no-ops and no `page.viewed` event fires.

Use inline when the chat is the page section. Use floating when it should be available everywhere without taking up layout space. Use composer for a search-box entry point inside your own layout (a hero, a help-center header, a row under a pricing table), where a full chat panel takes too much room and a corner bubble is too easy to miss. Use off when you want the tag’s non-chat behavior on a page that should look untouched: publishing tools to browsing agents, or host-page tracking, with nothing on screen.

<!-- Inline: the chat lives in your layout -->
<script src="…/embed.js" data-token="wwp_..." data-channel-id="..." defer></script>

<!-- Floating: a docked composer bar at the bottom of the viewport -->
<script src="…/embed.js" data-token="wwp_..." data-channel-id="..." data-mode="floating" defer></script>

<!-- Composer: an input in your layout that opens the panel on send -->
<div data-waniwani-embed style="max-width: 560px; margin: 0 auto;"></div>
<script src="…/embed.js" data-token="wwp_..." data-channel-id="..." data-mode="composer" defer></script>

<!-- Off: the script runs, the page shows nothing -->
<script src="…/embed.js" data-token="wwp_..." data-channel-id="..." data-mode="off" defer></script>

In composer mode the panel is appended to <body> rather than nested in your marker, so a transform or filter on an ancestor of the marker can’t drag the fixed panel out of position. Give the marker whatever width and margins your layout needs; data-height and the 500px inline default don’t apply. The conversation survives closing the panel: clicking the box again reopens it with the history intact. If you want React-component-level control over the inline mount, see Chat in React.

Sizing

Inline mode only. In floating mode the panel sizes itself, and in composer mode the box is content-height inside a container you size. The embed fills its container. Give the <div data-waniwani-embed> a definite size via CSS, or set data-height on the script tag:

<!-- Fixed height -->
<div data-waniwani-embed style="height: 600px;"></div>

<!-- Bounded by max-height -->
<div data-waniwani-embed style="max-height: 80vh;"></div>

<!-- Flex column child -->
<div style="display: flex; flex-direction: column; max-height: 800px;">
  <div data-waniwani-embed style="flex: 1 1 auto; min-height: 0;"></div>
</div>

A container you leave unstyled is 500px tall. That default is written with :where(), so it carries no specificity and any rule you write beats it — including height: auto to let the chat grow with its content. A ResizeObserver mirrors the container’s max-height onto the embed so padding and borders are respected.

Overriding attributes

You can edit data-* attributes on the <script> tag to tweak behavior. Do it sparingly: an attribute set here permanently outranks the channel config the embed fetches from the dashboard (resolution order is dashboard → data-* → init()), so a title pinned on the tag can no longer be changed by whoever owns the channel.

Attribute	Type	Notes
`data-mode`	string	`"inline"` (default), `"floating"`, `"composer"`, or `"off"`. See Modes.
`data-height`	string	Height of the inline container. Any CSS length (`"500px"`, `"80vh"`) or a bare number treated as px. Defaults to `500px`. Ignored in `floating` and `composer` mode.
`data-title`	string	Header title. No default — with no title (and no thread history) the chat renders headerless.
`data-hide-header`	boolean	Force-hide the sticky header when your page already provides its own chrome.
`data-welcome-message`	string	Greeting shown before the first message.
`data-placeholder`	string	Input field placeholder.
`data-suggestions`	string (comma-separated)	Initial suggestion chips.
`data-suggestion-origins`	string (comma-separated)	Which providers may fill the per-turn pill row: any of `"channel"`, `"page"`, `"flow"`, `"followup"`. Defaults to `"channel,page,followup"` — include `"flow"` to render pills from a flow’s `interrupt({ suggestions })`. An empty value renders none. Initial chips (`data-suggestions`) show either way.
`data-enable-thread-history`	boolean	Persist threads in IndexedDB. Defaults to `false`.
`data-locale`	string	UI language for built-in labels: `"en"`, `"fr"`, `"es"`. Defaults to detecting from `<html lang>` / `navigator.language`, falling back to English.
`data-disclaimer`	string \| `"false"`	AI transparency notice under the input (EU AI Act). A string overrides the default wording; `"false"` (or `"0"`) hides it.
`data-css`	string	URL to a custom stylesheet loaded into the shadow root. Targets the stable `.ww-*` classes — see Theming.
`data-theme`	string	`"light"` (default), `"dark"`, or `"auto"` (follows `prefers-color-scheme`).
`data-assistant-bubble`	boolean	Render assistant replies in a filled, themeable bubble. Defaults to `false` (plain text).
`data-visitor-id`	string	Override the anonymous visitor id with one you already track (a PostHog / Amplitude / Segment distinct id, your own cookie). See Link visitors to your analytics.
`data-show-tool-calls`	boolean \| `"titles-only"`	`true` (default) makes each step expandable to its request/response JSON, `"titles-only"` shows step labels, `false` hides the chain and reasoning trace.
`data-disable-page-view`	boolean	Opt out of the `page.viewed` event fired once on mount. Set on surfaces where a page view would pollute the funnel (internal tools, previews, authenticated app shells).

Floating and composer modes:

Attribute	Type	Notes
`data-launcher-text`	string	Placeholder for the entry input: the docked bar in `floating` mode, the in-page box in `composer` mode (e.g. `"Ask anything…"`). Falls back to `data-placeholder`, then to a localized prompt. The in-panel input keeps `data-placeholder`.
`data-appear-delay`	number	Floating only. Milliseconds before the dock animates in, letting the page settle first. Defaults to `2000`. `0` shows it immediately. A `composer` box is page content and renders with the page.

Composer mode only. The box sits in your layout, so its chrome is adjustable:

Attribute	Type	Notes
`data-composer-variant`	string	`"glow"` (default) or `"outline"`. See Composer variants.
`data-composer-size`	string	`"sm"`, `"md"` (default), or `"lg"`. Moves padding, type scale, and the send button together.
`data-composer-suggestions`	boolean	Render the channel’s suggestion pills under the box. Defaults to `true`.
`data-composer-align`	string	`"start"` (default) or `"center"`. Centers the pills, and the label when the composer renders as a trigger.
`data-composer-trigger`	boolean	Render the box as a tap target instead of a live input, at every width. Defaults to `false`. See Trigger instead of an input.
`data-composer-mobile-trigger`	boolean	On phone-width viewports, render the box as a tap target instead of a live input. Defaults to `true`. See On mobile.

Composer variants

Every variant behaves the same: the first message opens the panel. Only the chrome differs.

Variant	Looks like	Reach for it when
`glow`	Filled box on a card shadow, with a one-off colored border sweep once the config resolves.	The composer is the page’s main call to action and should pull the eye.
`outline`	The same box without the sweep.	It sits inside a card or a form that already has its own chrome.

Two, because a variant is a starting point rather than the ceiling. Radius, fill, border, shadow and the send button are CSS custom properties, so a fully rounded search bar is one declaration rather than a third variant. See Restyling with CSS.

Trigger instead of an input

data-composer-trigger="true" renders the box as a tap target: nothing is typed in the page, and a click opens the panel where the caret lands. For a host that wants one tap into the full chat and no in-page composing. The box keeps its variant and whatever CSS you set on it — only the textarea is swapped for the trigger. It is the same swap On mobile applies automatically below 640px; this option applies it at every width.

<script
  src="…/embed.js"
  data-token="wwp_..."
  data-channel-id="..."
  data-mode="composer"
  data-composer-variant="outline"
  data-composer-size="lg"
  defer
></script>

Restyling with CSS

The box reads its fill, border, radius, shadow and send button from --ww-composer-* custom properties. Set them wherever you set the rest of the widget’s variables ([data-waniwani-embed] works, and so does :root); they inherit through the widget’s Shadow DOM. Anything you leave alone keeps the variant’s own value.

Variable	Default	Controls
`--ww-composer-bg`	`var(--ww-color-input)`	Box fill.
`--ww-composer-radius`	12 / 16 / 20px by size	Corner radius.
`--ww-composer-border-color`	`var(--ww-color-border)`	Border color.
`--ww-composer-border-width`	`1px`	Border width. Takes the full `border-width` shorthand, so `0 0 1px 0` leaves only a rule underneath.
`--ww-composer-shadow`	the theme’s `--ww-shadow`	Box shadow.
`--ww-composer-send-bg`	`var(--ww-color-foreground)`	Send button fill.
`--ww-composer-send-fg`	`var(--ww-color-background)`	Send arrow.

A flat box with a single rule under it:

[data-waniwani-embed] {
  --ww-composer-bg: transparent;
  --ww-composer-radius: 0;
  --ww-composer-shadow: none;
  --ww-composer-border-width: 0 0 1px 0;
}

A fully rounded search bar:

[data-waniwani-embed] {
  --ww-composer-radius: 9999px;
  --ww-composer-shadow: none;
}

A tinted box with a branded send button:

[data-waniwani-embed] {
  --ww-composer-bg: #eef2ff;
  --ww-composer-border-color: #c7d2fe;
  --ww-composer-send-bg: #4f46e5;
  --ww-composer-send-fg: #ffffff;
  --ww-composer-shadow: none;
}

Text color, placeholder color, and the font come from the widget-wide variables in Theming & customization, not from a composer-specific one.

On mobile

Below 640px the composer renders as a tap target rather than a live input, whatever variant you picked. One tap opens the panel, which is already a full-screen sheet at that width, and the visitor types there. This is the default because in-page typing on a phone is the worse half of the handoff: the soft keyboard covers the box, the first message opens a full-screen panel over it, and focus has to move mid-sentence. Going straight to the panel skips all of it. The box keeps its variant and whatever CSS you set on it; only the textarea is swapped out. Set data-composer-mobile-trigger="false" to keep a real input at every width. Programmatic callers pass the same options as an object:

WaniWani.chat.init({
  mode: "composer",
  composer: { variant: "outline", size: "lg", showSuggestions: false },
});

Per-URL show/hide rules are configured in the dashboard, not on the script tag. They gate every mode; in inline and composer mode the marker div collapses too, so a hidden page shows no empty box. In off mode there is nothing to gate. Leave the wiring attributes (data-token, data-channel-id, data-api, the script src) as the dashboard generated them. Beyond the data-theme preset and data-assistant-bubble, individual colors, fonts, and bubble shapes have no data-* equivalent — set --ww-* CSS variables instead. They inherit through the widget’s Shadow DOM, so declare them on [data-waniwani-embed] in inline or composer mode, or anywhere on the host page (:root works) in floating mode, where there is no container of your own. See Theming & customization for the full variable list and deep-customization recipes. Full type definitions: EmbedConfig and ChatTheme.

Programmatic init

For runtime control (computing options dynamically, mounting on demand), drop the data-token attribute from the script tag and call init() manually. You still need the wiring attributes from a dashboard-issued snippet:

<div data-waniwani-embed></div>

<!-- Keep the script src and data-channel-id from the dashboard snippet,
     just remove data-token so the embed doesn't auto-init. -->
<script
  src="https://cdn.jsdelivr.net/npm/@waniwani/sdk@latest/dist/chat/embed.js"
  data-channel-id="..."
  defer
></script>
<script>
  window.addEventListener("DOMContentLoaded", () => {
    window.WaniWani.chat.init({
      token: "wwp_...", // from the dashboard snippet
      welcomeMessage: computeGreetingForUser(),
    });
  });
</script>

init() returns an instance with destroy() and sendMessage(text). You can also call window.WaniWani.chat.destroy() and window.WaniWani.chat.sendMessage("...") directly on the global. init() also accepts an onEvent callback that mirrors chat lifecycle events (opens, messages, errors, link clicks) into your own analytics — Amplitude, Segment, gtag — with your page’s identity attached automatically. See Widget events (onEvent).

Link visitors to your analytics

By default the embed mints its own anonymous visitor id, a stable opaque value persisted in the browser’s localStorage. It rides on every chat request and tracking event, so a visit is attributable before the first message mints a session (see Sessions). If your site already tracks visitors with PostHog, Amplitude, Segment, or a first-party cookie, override that id with your own. Waniwani then correlates its sessions and events to the same visitor you see in your analytics, and your server-side MCP tools and flows read the id back as context.waniwani.visitorId, so they can send events straight to the same analytics tool the id came from. There are three ways to set it. Pick the one that matches when your id is available.

If you know the id up front

Set it declaratively on the script tag:

<script
  src="https://cdn.jsdelivr.net/npm/@waniwani/sdk@latest/dist/chat/embed.js"
  data-token="wwp_..."
  data-channel-id="..."
  data-visitor-id="the-id-from-your-system"
  defer
></script>

Or pass it to init() when you initialize programmatically. init() accepts a string or a resolver (sync or async), so you can read the id inline:

window.WaniWani.chat.init({
  token: "wwp_...",
  visitorId: "the-id-from-your-system",
  // or a resolver: visitorId: () => posthog.get_distinct_id(),
});

If the id resolves asynchronously (the common case)

Analytics SDKs usually assign a distinct id only after they bootstrap, so read it when it’s ready and hand it to the widget. setVisitorId() is safe to call at any time, before or after init(), and the new id applies to the next chat request and tracking event:

// PostHog
posthog.onFeatureFlags(() => {
  window.WaniWani.chat.setVisitorId(posthog.get_distinct_id());
});

// Amplitude
const amplitudeId = amplitude.getDeviceId();
if (amplitudeId) {
  window.WaniWani.chat.setVisitorId(amplitudeId);
}

A blank value is ignored, so an id that isn’t ready yet never wipes a good one. Read the id the widget will send with window.WaniWani.chat.getVisitorId().

The visitor id identifies a device / browser, not a signed-in account. When a visitor logs in, keep the visitor id and additionally call identify() with your account id, so anonymous and known activity stitch together.

Self-hosting the JS bundle

If you’d rather not load from a CDN, pin a specific SDK version and serve the bundled file yourself. The data-* attributes still come from the dashboard snippet — you’re only swapping where embed.js is served from:

bun add @waniwani/sdk
cp node_modules/@waniwani/sdk/dist/chat/embed.js public/waniwani-embed.js

Then point the dashboard-issued snippet at your local copy:

<div data-waniwani-embed></div>
<script
  src="/waniwani-embed.js"
  data-token="wwp_..."
  data-channel-id="..."
  defer
></script>

How it works

The script reads its own data-* attributes (token, channel ID, mode, theming, content overrides).
On DOMContentLoaded (or immediately, if the DOM is already ready), it mounts the chat via Shadow DOM — inside [data-waniwani-embed] in inline and composer mode, or in its own anchored container in floating mode. composer mode adds a second, <body>-level container for the panel.
The chat calls app.waniwani.ai/api/mcp/chat with the project token and streams responses back through Server-Sent Events.
Conversation history lives only in memory by default; set data-enable-thread-history to persist threads in IndexedDB on the user’s device.

No server-side integration on your side.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Modules

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Chat embed

Quick start

Modes

Sizing

Overriding attributes

Composer variants

Trigger instead of an input

Restyling with CSS

On mobile

Programmatic init

Link visitors to your analytics

If you know the id up front

If the id resolves asynchronously (the common case)

Self-hosting the JS bundle

How it works

​Quick start

​Modes

​Sizing

​Overriding attributes

​Composer variants

​Trigger instead of an input

​Restyling with CSS

​On mobile

​Programmatic init

​Link visitors to your analytics

​If you know the id up front

​If the id resolves asynchronously (the common case)

​Self-hosting the JS bundle

​How it works

Quick start

Modes

Sizing

Overriding attributes

Composer variants

Trigger instead of an input

Restyling with CSS

On mobile

Programmatic init

Link visitors to your analytics

If you know the id up front

If the id resolves asynchronously (the common case)

Self-hosting the JS bundle

How it works