Headless Hook

Have your own design system? useChatterflyRun drives the connection and state machine with no UI, so you can render the conversation with your own components.

Overview

useChatterflyRun is the same auto-start + WebSocket logic that powers <ChatterflyWidget>, exposed as a hook. Pair it with the exported input components (InputText, InputBoolean, etc.) or your own to build a fully custom participant surface.

Note: ChatterflyWidget/ChatAdapter implement the same auto-start contract independently rather than consuming this hook internally — both follow identical endpoints and the same session-persistence module, so behavior is consistent either way.

Usage

tsx

import { useChatterflyRun, InputText, InputBoolean } from "@chatterfly/widget";

function MyCustomChat() {
  const {
    status, activeSession, timeline, output,
    submitHandback, sendMessage, restart, disconnect, connecting, error,
  } = useChatterflyRun({
    workflowId: "wf_abc123",
    apiBase: "https://api.chatterfly.ai",
    // persistSession defaults to true — pass false to opt out
  });

  if (connecting) return <MySkeleton />;
  if (error) return <MyError code={error.code} message={error.message} />;

  // render `timeline` and `activeSession` with your own components
  return null;
}

Note: Just like ChatterflyWidget, persistSession defaults to true for serverless (workflowId/deploymentId) configs, and the hook drives the same active/dormant/hibernating connection lifecycle and token re-mint-on-expiry behavior — see Connection Lifecycle. Note: the choice-card UI (resumePrompt/clickToStart/showCompletedHistory) is a ChatterflyWidget-only convenience today — headless hosts render their own gating on top of status/connecting.

Return value

Name	Description
status	RunStatus — the client state machine (including offline/expired on connection loss/token expiry).
activeSession	The currently open HITL session, if any.
timeline	Ordered TimelineEntry[] for the whole run.
messages	Deliberation chat messages for the active session.
streamingText	Accumulated in-progress LLM tokens.
output	Final run state once the run reaches a terminal status.
submitHandback	(output?, idempotencyKey?) => Promise<ValidationError[] \| null>
sendMessage	(content: string) => Promise<void>
restart	Mints a new run (auto-start) or reconnects (direct runId).
disconnect / reconnect	Manual connection control.
connecting	True while the serverless auto-start request is in flight.
error	WidgetError \| null — set on config/start failures.