Waniwani SDK — Build MCP funnels

Two React components ship from @waniwani/sdk/chat. Pick based on who runs the chat backend:

Component	Use when	Backend
`WaniwaniChat`	You want the hosted chat. Start here.	Ours, no setup
`ChatEmbed`	You self-host the chat backend	Yours

The React components mount inline: they render wherever you place them in your layout, and you control the container. There is no launcher, floating bubble, or overlay panel in the React path. Those live in the embed script, as floating mode (a docked bar) and composer mode (an in-page input that opens the panel on send). To put the React chat in a sidebar or drawer of your own that opens from your buttons, see In a sidebar or drawer.

Platform feature. Requires a Waniwani project token (wwp_...). Get one at app.waniwani.ai or read more about the Platform.

Install

bun add @waniwani/sdk

Add the stylesheet to your app once (e.g. in _app.tsx or your root layout):

import "@waniwani/sdk/chat/styles.css";

WaniwaniChat

The hosted chat. Pass your project token and channel ID and it talks to app.waniwani.ai directly — no API route, no proxy, no backend work on your side.

import { WaniwaniChat } from "@waniwani/sdk/chat";

<WaniwaniChat token="wwp_..." channelId="..." />;

The system prompt, welcome message, placeholder, suggestions, thread history and tool-call display are configured per channel in the dashboard, so business users can change them without a deploy. Theming has no dashboard equivalent — set it in code via overrides.appearance.

Sizing and placement

WaniwaniChat fills its parent. Put it wherever you want it and size the container:

<section style={{ height: 600, maxWidth: 480 }}>
  <WaniwaniChat token="wwp_..." channelId="..." />
</section>

To use it as a full-width page hero, give the wrapper the height you want and let the chat fill it. className is applied to the root element if you’d rather style it directly.

Per-page overrides

The dashboard is the source of truth. Use overrides only for a local tweak that doesn’t justify a separate channel:

<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    title: "Coverage guide",
    hideHeader: false,
    placeholder: "Tell me what's going on…",
    suggestions: ["I lost my coverage", "I'm turning 65 soon"],
    showToolCalls: "titles-only",
    appearance: { theme: "light", variables: { primaryColor: "#FFB929" } },
  }}
/>;

Override	Notes
`title`	Sticky header title
`hideHeader`	Force-hide the header when your page already provides chrome
`welcomeMessage`	Greeting before the first user message
`welcome`	Rich welcome screen (icon, title, suggestion cards). Takes precedence over `welcomeMessage`
`placeholder`	Input placeholder
`suggestions`	Initial suggestion chips
`suggestionOrigins`	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 })`
`enableThreadHistory`	Persist threads in IndexedDB
`showToolCalls`	`true` (default), `"titles-only"`, or `false`
`allowAttachments`	Enable file attachments in the input
`appearance`	Theme preset plus per-property overrides. Not dashboard-backed — this is where theming is set — see Theming
`classNames`	Per-slot class overrides — see Deep customization
`disclaimer`	AI transparency notice under the input. A string overrides the wording, `false` hides it
`locale`	UI language for built-in labels: `"en"`, `"fr"`, `"es"`. Detected from `<html lang>` / `navigator.language` when unset
`messages`	Per-key overrides on the resolved locale catalog, to tweak individual built-in strings
`disablePageView`	Opt out of the `page.viewed` event fired once on mount. Set on surfaces where a page view would pollute the funnel
`api`	Chat API URL. Rarely needed — defaults to `https://app.waniwani.ai/api/mcp/chat`
`mcpServerUrl`	Override the MCP server URL. Rarely needed

Control the chat from your page

Pass a ref to drive the chat from anywhere else on the page: a call to action in your hero, a link in your navigation, a pricing row that asks about itself. The ref holds a ChatHandle.

"use client";

import { useRef } from "react";
import { WaniwaniChat, type ChatHandle } from "@waniwani/sdk/chat";

export function Hero() {
  const chat = useRef<ChatHandle>(null);

  return (
    <>
      <button onClick={() => chat.current?.sendMessage("I'd like to request a demo")}>
        Request a demo
      </button>

      <section style={{ height: 600 }}>
        <WaniwaniChat ref={chat} token="wwp_..." channelId="..." />
      </section>
    </>
  );
}

Member	What it does
`sendMessage(text)`	Sends `text` as the visitor’s message.
`sendMessageAndWait(text)`	Same as `sendMessage`, and returns a promise that resolves with the assistant’s final message once it has finished streaming.
`focus()`	Scrolls to the chat input, focuses it, and flashes a highlight around it.
`reset()`	Clears the conversation and starts a new one.
`messages`	The conversation so far.
`sessionId`	The chat session id, `undefined` until the first message.
`track` / `identify`	Host-page tracking. See Tracking from the host page.

Calls made before the chat has loaded its channel config are dropped, so wire the handle to a visitor’s click rather than calling it during the first render. On a page that the dashboard’s per-URL rules hide, the component renders nothing and the chat methods do nothing. The React handle has no open() or close(), because WaniwaniChat is on screen wherever you mount it. A sidebar, drawer or modal around it is your own component, and its open state lives in your code. A button anywhere on the page flips that state, and can send a first message through the ref in the same click:

"use client";

import { useRef, useState } from "react";
import { WaniwaniChat, type ChatHandle } from "@waniwani/sdk/chat";

export function ChatSidebar() {
  const chat = useRef<ChatHandle>(null);
  const [open, setOpen] = useState(false);

  const ask = (question: string) => {
    setOpen(true);
    chat.current?.sendMessage(question);
  };

  return (
    <>
      <button onClick={() => setOpen(true)}>Talk to an advisor</button>
      <button onClick={() => ask("How much can I borrow?")}>How much can I borrow?</button>

      <aside
        style={{
          display: open ? "flex" : "none",
          flexDirection: "column",
          position: "fixed",
          top: 0,
          right: 0,
          bottom: 0,
          width: 420,
        }}
      >
        <button onClick={() => setOpen(false)}>Close</button>
        <div style={{ flex: 1, minHeight: 0 }}>
          <WaniwaniChat ref={chat} token="wwp_..." channelId="..." />
        </div>
      </aside>
    </>
  );
}

The chat stays mounted while the sidebar is closed, hidden with CSS. Rendering it only when open is true would mount it on the very click that sends the question, before it has loaded, and that first message would be dropped. Keeping it mounted also means the visitor finds their conversation where they left it when they reopen the sidebar. If you’d rather use the Waniwani panel than build your own, load the embed script in floating or composer mode and call window.WaniWani.chat.open() from your React components. See Control the chat from your page.

Tracking from the host page

The same ChatHandle carries track and identify. identify takes two positional arguments, the user id first and optional traits second:

import { WaniwaniChat, type ChatHandle } from "@waniwani/sdk/chat";

const chat = useRef<ChatHandle>(null);

<WaniwaniChat ref={chat} token="wwp_..." channelId="..." />;

chat.current?.identify(user.id, { plan: "pro" });
chat.current?.track.leadQualified({ /* … */ });

Both are present on WaniwaniChat only — the bare ChatEmbed primitive has no Waniwani credential to send events with. See Identify.

The page the visitor is on

From 0.24.1, WaniwaniChat sends the address of the current page with each message, and your agent is told which page the visitor is on. There is nothing to set up. The page the visitor is on shows what the agent gets and how to tell it what your pages are.

ChatEmbed

A bare-bones primitive for when you run the chat backend yourself. api is required and there is no default; pass any endpoint implementing the Vercel AI SDK chat protocol and the component handles the rest.

Reach for ChatEmbed only when self-hosting. If you’re using the Waniwani Platform, WaniwaniChat gives you the same UI plus dashboard configuration, visitor correlation, and tracking.

import { ChatEmbed } from "@waniwani/sdk/chat";

<ChatEmbed
  api="/api/my-chat"
  body={{ environmentId, sessionId }}
  appearance={{ theme: "dark" }}
/>;

Link visitors to your analytics

Both components accept a visitorId prop to override the anonymous id the widget generates with one you already track (a PostHog / Amplitude / Segment distinct id, your own cookie). Waniwani correlates its sessions and events to the same visitor your analytics sees, and your server-side MCP tools and flows read it back as context.waniwani.visitorId. Leave it unset to keep the auto-generated, localStorage-persisted id. visitorId accepts a string, or a resolver that returns one. The resolver may be sync or async, which is handy when your analytics SDK only exposes its id after it bootstraps:

// A string you already hold
<WaniwaniChat token="wwp_..." channelId="..." visitorId={myCookieId} />;

// A sync resolver
<WaniwaniChat token="wwp_..." channelId="..." visitorId={() => posthog.get_distinct_id()} />;

// An async resolver — the widget uses the auto id until this settles
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  visitorId={async () => (await analytics.ready()).anonymousId}
/>;

A blank or failed result is ignored, so a not-ready id never wipes a good one. The value is read live on every request, so updating it applies to the next message. See Sessions for how the three correlation ids fit together.

For an expensive async resolver, pass a stable reference (useCallback) so it isn’t re-invoked on every render.

Attachments

ChatEmbed takes the documents module’s state as a prop, since it fetches no remote config of its own:

<ChatEmbed
  api="/api/my-chat"
  documentUpload={{
    enabled: true,
    maxBytes: 52428800,
    maxPdfPages: 1000,
    maxFiles: 10,
    accept: ["application/pdf", "image/png", "image/jpeg"],
  }}
/>;

The composer offers a paperclip, a drop target and paste only while enabled is true, and the upload endpoint enforces the same flag. WaniwaniChat and the script embed read all of this from the dashboard, so they need none of it. See Documents for what an agent does with the files.

Authentication

headers goes out with every chat request, and document uploads reuse it, so one bearer usually covers both.

<ChatEmbed api="/api/my-chat" headers={{ Authorization: `Bearer ${token}` }} />;

Set uploadHeaders when your upload endpoint takes a different credential than your chat endpoint. It is merged over headers on the document upload and discard calls, and leaves the chat request alone.

<ChatEmbed
  api="/api/my-chat"
  headers={{ Authorization: `Bearer ${token}`, "X-Tenant-Id": tenant }}
  uploadHeaders={{ Authorization: `Bearer ${uploadToken}` }}
/>;

Uploads there go out with the upload token and still carry X-Tenant-Id. Only the names you repeat are replaced, and the match ignores case, so authorization overrides Authorization. Both land in the browser, so put only public credentials in them.

Theming

Both components take an appearance preset (light, dark, or auto) with optional per-property overrides layered on top:

<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    appearance: {
      theme: "light",
      variables: {
        primaryColor: "#03d916",
        borderRadius: 12,
        messageBorderRadius: 20,
        fontSize: 15,
      },
    },
  }}
/>;

auto follows the host’s prefers-color-scheme. variables accepts every ChatTheme token — colors, message-bubble radius/padding/max-width, base font size and line height. The full token and CSS-variable list lives on Theming & customization.

Deep customization

Two escape hatches when tokens aren’t enough:

appearance.assistantBubble — opt-in filled bubble for assistant replies (plain text by default), styled by assistantBubbleColor / assistantBubbleTextColor.
classNames — per-slot class overrides merged onto the widget’s own classes: root, header, message, userBubble, assistantBubble, input. Pass it directly on ChatEmbed, or as overrides.classNames on WaniwaniChat.

<ChatEmbed
  api="/api/my-chat"
  appearance={{ assistantBubble: true }}
  classNames={{
    header: "uppercase tracking-wide",
    userBubble: "shadow-md",
  }}
/>;

Recipes and the list of what remains non-themeable: Theming & customization.

Mirroring events into your analytics

The hosted WaniwaniChat component accepts an onEvent prop that fires on chat lifecycle events (messages, session start, errors, link clicks) so you can mirror widget activity into your own analytics — Segment, Amplitude, gtag — with the page’s identity attached automatically. ChatEmbed, the bring-your-own-backend primitive, does not expose it. See Widget events (onEvent).

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 in React

Install

WaniwaniChat

Sizing and placement

Per-page overrides

Control the chat from your page

In a sidebar or drawer

Tracking from the host page

The page the visitor is on

ChatEmbed

Link visitors to your analytics

Attachments

Authentication

Theming

Deep customization

Mirroring events into your analytics

​Install

​WaniwaniChat

​Sizing and placement

​Per-page overrides

​Control the chat from your page

​In a sidebar or drawer

​Tracking from the host page

​The page the visitor is on

​ChatEmbed

​Link visitors to your analytics

​Attachments

​Authentication

​Theming

​Deep customization

​Mirroring events into your analytics

Install

WaniwaniChat

Sizing and placement

Per-page overrides

Control the chat from your page

In a sidebar or drawer

Tracking from the host page

The page the visitor is on

ChatEmbed

Link visitors to your analytics

Attachments

Authentication

Theming

Deep customization

Mirroring events into your analytics