Waniwani SDK — Build MCP funnels

Platform feature. Requires WANIWANI_API_KEY on the server. Browser surfaces authenticate with a public token (wwp_...) or an injected widget token instead. About the Platform.

Events are a single typed taxonomy, sent through one track surface that is identical everywhere it appears:

await track({ event: "link.clicked", properties: { url: "https://acme.com/pricing" } });
await track.priceShown({ amount: 49, currency: "EUR" });
await track.leadQualified({ email: "jane@acme.com" });
await track.converted({ amount: 85, currency: "EUR" });

That same track exists on four surfaces, each of which attaches session identity for you:

Surface	Where `track` lives	Identity attached automatically
MCP tool handler / flow node	`context.waniwani.track` (scoped client)	`sessionId` from the request meta
MCP-app widget (browser)	`useWaniwani().track`	`sessionId` injected by `withWaniwani`
Chat host page	`WaniWani.chat.track` / `ChatHandle.track`	`visitorId` always; `sessionId` too once assigned
Your backend / scripts	`waniwani().track`	none, pass `externalUserId` or `sessionId`

The first three need no identity plumbing at all. Only the top-level backend client requires you to say who the event belongs to. See Sessions for the identity model and Widgets for the browser surfaces.

The event catalog

The EventType union is a closed, typed set, exported at runtime as EVENT_TYPES from @waniwani/sdk. These are all the events:

Event	Sent by	Properties	When
`page.viewed`	Chat widget, automatic	`PageViewedProperties`	A visitor lands on a page where the chat widget is present. Attributed to the anonymous `visitorId`, never a session.
`session.started`	Waniwani backend, automatic	none	First time the backend sees a new `sessionId`. Never send it yourself.
`tool.called`	`withWaniwani(server)`, automatic	`ToolCalledProperties`	Every tool invocation: name, type, duration, status, input/output, KB retrieval traces. A handler that throws also carries `cause`; a handler that returns `{ isError: true }` does not.
`widget_render`	`useWaniwani()`, automatic	none	A widget initialized with resolved tracking config. The top of the widget funnel.
`session.error`	Flow engine, automatic	`SessionErrorProperties`	The flow engine hit a failure. `code: "agent_failed"` covers step execution: an unknown node, a missing outgoing edge (including a missing start edge), a throwing step handler, or the iteration cap. `code: "upstream_failed"` covers flow state store reads and writes that fail. Carries no error message, stack, or handler input, only bounded tokens. There is no public API to send it; application code never emits it.
`user.identified`	`identify()` on any surface	free-form traits	A stable user id was attached. Prefer calling `identify()` over sending this directly.
`lead_qualified`	you, `track.leadQualified()`	`LeadQualifiedProperties`	The lead qualified: the conversation produced a concrete handoff toward your business. Once per flow run. See the definition below.
`price_shown`	you, `track.priceShown()`	`PriceShownProperties`	You showed the user one price.
`prices_compared`	you, `track.pricesCompared()`	`PricesComparedProperties`	You showed two or more options side by side.
`option_selected`	you, `track.optionSelected()`	`OptionSelectedProperties`	The user picked one of the options.
`converted`	you, `track.converted()`	`ConvertedProperties`	The user became paying, possibly later and off-platform.
`link.clicked`	you, generic `track()`	`LinkClickedProperties`	An outbound link was followed.

Type shapes for every property interface live in the event schema reference. Placement guidance (which event belongs at which flow node) lives in Instrumentation. Any event name outside this table is rejected: the TrackEvent union will not typecheck it, and the ingest API does not power funnels with it. Model your funnel with the events above instead of inventing names.

What counts as a qualified lead

lead_qualified means the conversation produced a concrete handoff toward your business. A lead is qualified whenever the user:

is redirected to your pricing page or to your own website,
books a call or a meeting,
is sent an email (a quote recap, a follow-up, a booking confirmation),
or otherwise meets an explicit qualification bar you defined (finished the qualifying questions, requested a demo, matched your target profile).

Knowing who the user is does not qualify them. When you learn an email, a phone number, or a first and last name, call identify(): that attaches identity to the session and is the join key for later attribution, but it does not mean the lead is qualified yet. identify says “we know who this is”; lead_qualified says “this person is worth your sales attention”. Most funnels emit both, at different moments. See Identify and Instrumentation for placement. The chat backend also logs chat.user_message and chat.assistant_message server-side for every exchange; you never send those from code. Everything on this page is platform ingest: events sent to Waniwani to power funnel analytics. The chat widget also offers a separate host-callback channel — onEvent — that mirrors widget lifecycle events into your own page-side analytics (Amplitude, Segment, gtag) without touching the Waniwani ingest. See Widget events (onEvent).

Revenue helpers

The five revenue funnel events have flat typed helpers on track (there is no track.revenue.* namespace). Each accepts its event’s properties plus the shared tracking context (sessionId, externalUserId, visitorId, meta).

Helper	Event
`track.leadQualified({ externalId?, email?, name? })`	`lead_qualified`
`track.priceShown({ amount, currency, itemId?, label? })`	`price_shown`
`track.pricesCompared({ options: [{ id, amount, currency }] })`	`prices_compared`
`track.optionSelected({ id, amount, currency })`	`option_selected`
`track.converted({ amount, currency, occurredAt? })`	`converted`

occurredAt on converted backdates an off-platform sale to when it actually happened; the event itself may arrive months later.

Sending events

From a tool handler or flow node

Wrap the server once with withWaniwani(server), then use the scoped client from the handler context. Session identity is already attached; you pass nothing.

.addNode("show_quote", async ({ state, waniwani }) => {
  await waniwani?.track.priceShown({ amount: state.premium, currency: "EUR" });
  return {};
})

server.registerTool("get_quote", { /* config */ }, async ({ amount }, extra) => {
  const waniwani = extra["waniwani/client"];
  await waniwani?.track.priceShown({ amount, currency: "EUR" });
  return { content: [{ type: "text", text: "Quoted" }] };
});

The scoped client also exposes the resolved session id as waniwani.sessionId. Store it with your own records (a lead, an order) and you can attribute an off-platform event back to the conversation later. The browser surfaces expose the same track. See Widgets for setup; the calls are identical:

const wani = useWaniwani();
wani.track.optionSelected({ id: "pro", amount: 49, currency: "EUR" });

WaniWani.chat.track.converted({ amount: 85, currency: "EUR" });

From your backend

Create one top-level client (for example in lib/waniwani.ts) and pass identity explicitly on every call. This is how an off-platform conversion finds its original lead:

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

const client = waniwani(); // reads WANIWANI_API_KEY from env

await client.track.converted({
  amount: 85,
  currency: "EUR",
  externalUserId: "user_123",           // the join key captured during the funnel
  occurredAt: "2026-06-09T10:00:00Z",
});

If you stored the scoped client’s sessionId during the conversation, sessionId: storedSessionId works as the join key too.

The identity rule

Every event must carry a sessionId, an externalUserId, or a visitorId. The ingest API rejects events with none, and the SDK warns at enqueue time. The scoped client, the widget hook, and the chat embed satisfy this automatically; the top-level backend client is the one place you pass identity yourself.

Return value

const { eventId } = await client.track({ event: "link.clicked", properties: { url: "https://acme.com/pricing" }, externalUserId: "user_123" });

eventId is stable and safe to log. It is assigned before the envelope leaves the process, so logging it tells you an event was accepted into the buffer, not that it reached the backend. track() returns as soon as the envelope is enqueued, before the network request completes.

Flushing

The transport flushes on a timer and on batch size. In long-running processes you do not need to call flush() yourself. In serverless functions, call it before the function returns:

await client.flush();

Or stop the transport entirely:

const { timedOut, pendingEvents } = await client.shutdown({ timeoutMs: 5000 });

Browser surfaces additionally flush with keepalive requests when the page is hidden or unloading, so events survive navigation.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Modules

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Events

The event catalog

What counts as a qualified lead

Revenue helpers

Sending events

From a tool handler or flow node

From a widget or the chat embed

From your backend

The identity rule

Return value

Flushing

​The event catalog

​What counts as a qualified lead

​Revenue helpers

​Sending events

​From a tool handler or flow node

​From a widget or the chat embed

​From your backend

​The identity rule

​Return value

​Flushing

The event catalog

What counts as a qualified lead

Revenue helpers

Sending events

From a tool handler or flow node

From a widget or the chat embed

From your backend

The identity rule

Return value

Flushing