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 or floating bubble in the React path — for that, use the embed script in floating mode.

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

Tracking from the host page

The ref exposes a ChatHandle with track and identify alongside the chat controls. identify takes the user id as its first argument, with optional traits second — it is not an object:

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.

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

Tracking from the host page

ChatEmbed

Link visitors to your analytics

Attachments

Authentication

Theming

Deep customization

Mirroring events into your analytics

​Install

​WaniwaniChat

​Sizing and placement

​Per-page overrides

​Tracking from the host page

​ChatEmbed

​Link visitors to your analytics

​Attachments

​Authentication

​Theming

​Deep customization

​Mirroring events into your analytics

Install

WaniwaniChat

Sizing and placement

Per-page overrides

Tracking from the host page

ChatEmbed

Link visitors to your analytics

Attachments

Authentication

Theming

Deep customization

Mirroring events into your analytics