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.

The embed supports two modes: mode: "inline" (default) mounts the chat wherever you place a <div data-waniwani-embed></div> marker, sized by your CSS on that container; mode: "floating" renders a docked bar that expands into a full chat panel.

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 ships pre-wired with your project token, channel ID, and any defaults you configured in the dashboard. Don’t hand-author it — the channel ID is issued by the Platform and required for the embed to route correctly.

Sizing

The embed fills its container. Give the <div data-waniwani-embed> a definite size via CSS:

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

If the parent is fully unbounded the chat grows with content. A ResizeObserver mirrors the container’s max-height onto the embed so padding and borders are respected.

Overriding attributes

The snippet you paste is a starting point. After pasting, you can edit data-* attributes on the <script> tag to tweak behavior:

Attribute	Type	Notes
`data-title`	string	Header title. Defaults to `"Assistant"`.
`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-enable-thread-history`	boolean	Persist threads in IndexedDB. Defaults to `false`.
`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.

Leave the wiring attributes (data-token, data-channel-id, data-api, the script src) as the dashboard generated them. Colors, fonts, and bubble shapes are not set through data-* attributes — set --ww-* CSS variables on the container instead. 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, theming, content overrides).
On DOMContentLoaded (or immediately, if the DOM is already ready), it locates [data-waniwani-embed] and mounts the chat inside it via Shadow DOM.
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. If you want React-component-level control instead of the script tag, see Chat in React.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Chat embed

Quick start

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

​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

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