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 two 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.

Use inline when the chat is part of the page (a section, or the page hero). Use floating when it should be available everywhere without taking up layout space.

<!-- 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>

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. 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) or `"floating"`. 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` 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 mode only:

Attribute	Type	Notes
`data-launcher-text`	string	Placeholder shown in the docked composer bar (e.g. `"Ask anything…"`). Falls back to `data-placeholder`, then to a localized prompt.
`data-appear-delay`	number	Milliseconds before the dock animates in, letting the page settle first. Defaults to `2000`. `0` shows it immediately.

Per-URL show/hide rules for the floating bar are configured in the dashboard, not on the script tag. 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 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 mode, or in its own anchored container in floating mode.
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

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

​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

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