Digital Worker Chat

The chat components let your customers converse with one of your Digital Workers from inside your app — with streaming replies, inline forms, conversation history, unread badges, and live replies from a human CSM. All components on this page must be rendered inside a <StatisfyProvider>.

`DigitalWorkerChat`

The full chat widget. The only required prop is the worker to talk to.

import { DigitalWorkerChat } from '@statisfy/digital-workers-react'

<DigitalWorkerChat
  workerId="your-digital-worker-uuid"
  workerName="Onboarding Assistant"
  greeting="Hi! Ask me anything about getting set up."
  className="dw-h-[600px]"
/>

Props

Prop	Type	Default	Description
`workerId`	`string`	—	Required. UUID of the Digital Worker to converse with.
`workerName`	`string`	`"Digital Worker"`	Display name in the header.
`greeting`	`string`	—	First message shown before the user types.
`className`	`string`	—	Extra classes on the root container (e.g. height).
`initialThreadId`	`string`	—	Pin a deterministic thread on the first turn. Consulted only before the first message; later turns continue the server’s thread.
`formRenderer`	`FormRenderer`	—	Render callback for inline `present_form` tool calls. See Inline forms.
`autoLoadConversation`	`boolean`	`false`	On mount, load prior history and the orchestrator’s current next action (e.g. the form to show) without faking a user turn.
`presented`	`boolean`	`true`	Whether the chat is currently on-screen. Pass your launcher’s open state; while `false`, inbound replies accrue as unread instead of being auto-read.
`onUnreadChange`	`(count: number) => void`	—	Fires when the total unread count across the customer’s threads changes. Badge your own launcher with it.
`onClose`	`() => void`	—	When set, renders a close (✕) button in the header that calls this. Omit for always-visible inline embeds.
`history`	`boolean`	`true`	Enable the history panel, unread badge + “new reply” toast, and the background poll that powers them.
`newChat`	`boolean`	`true`	Show a “New chat” affordance.

Embedding in a launcher

For a collapsible chat bubble, pass your open state to presented and badge the launcher with onUnreadChange:

function ChatLauncher() {
  const [open, setOpen] = useState(false)
  const [unread, setUnread] = useState(0)

  return (
    <>
      <button onClick={() => setOpen(true)}>
        Chat {unread > 0 && <span className="badge">{unread}</span>}
      </button>
      {open && (
        <DigitalWorkerChat
          workerId="your-digital-worker-uuid"
          presented={open}
          onUnreadChange={setUnread}
          onClose={() => setOpen(false)}
        />
      )}
    </>
  )
}

Unread is tracked client-side (per-thread last-seen counts in localStorage, refreshed by a background poll roughly every 30s). The active thread auto-marks read while presented is true.

Live CSM replies

When a human CSM replies to a conversation from Statisfy, the chat detects the new message on its next poll and surfaces it in the open thread — and as unread elsewhere. No extra wiring is needed; just keep history enabled (the default).

`OnboardingModule`

A thin wrapper around DigitalWorkerChat for onboarding surfaces. It:

Reads the customer_id from the session token and pins initialThreadId to onboarding:<customer_id> — so the same customer always resumes the same onboarding thread.
Enables autoLoadConversation, so the chat opens with the right form (or closing message) already on screen and prior history restored across refreshes.
Defaults formRenderer to DefaultFormRenderer.

import { OnboardingModule } from '@statisfy/digital-workers-react'

<OnboardingModule workerId="your-onboarding-worker-uuid" />

OnboardingModuleProps accepts the same props as DigitalWorkerChat except initialThreadId and autoLoadConversation (both are derived for you).

Inline forms

When the agent needs structured input it emits a present_form tool call. Provide a formRenderer to render it as a real form; on submit, the chat posts a new turn with the collected values as structured_input. The SDK ships a ready-made renderer, DefaultFormRenderer:

import { DigitalWorkerChat, DefaultFormRenderer } from '@statisfy/digital-workers-react'

<DigitalWorkerChat workerId="…" formRenderer={DefaultFormRenderer} />

To render forms in your own design system, supply a custom FormRenderer:

import type { FormRenderer } from '@statisfy/digital-workers-react'

const myFormRenderer: FormRenderer = (formSpec, ctx) => (
  <form
    onSubmit={(e) => {
      e.preventDefault()
      const data = Object.fromEntries(new FormData(e.currentTarget))
      ctx.onSubmit(data) // posts a new turn with structured_input
    }}
  >
    <p>{formSpec.prompt}</p>
    {formSpec.fields.map((f) => (
      <label key={f.key}>
        {f.label}
        <input name={f.key} placeholder={f.placeholder} required={f.mandatory} />
      </label>
    ))}
    <button type="submit" disabled={ctx.disabled}>Submit</button>
  </form>
)

FormSpec has { prompt, fields }; each FormField has { key, label, type, options?, placeholder?, mandatory? }. The ctx.onSubmit(values) call replays the turn with those values; ctx.disabled is true while a submission is in flight.

If you omit formRenderer, present_form calls render as a generic “tool running” chip and the agent falls back to free-text input.

Headless client

Need full control of the conversation UI? Skip the components and drive the transport directly with createDigitalWorkerClient. (The provider isn’t required for the headless client — you pass config explicitly.)

import { createDigitalWorkerClient } from '@statisfy/digital-workers-react'

const client = createDigitalWorkerClient({
  baseUrl: 'https://api.statisfy.app',
  workerId: 'your-digital-worker-uuid',
  getToken: async () => sessionToken,
  publishableKey: 'pk_live_your_key'
})

The client exposes four methods:

`sendMessage(content, threadId?, structuredInput?, formPrompt?)`

One-shot send; resolves with the full reply.

const res = await client.sendMessage('What are my open tasks?')
// res: { reply, thread_id, conversation_id, agent_message_id, pending_approval?, next_action? }
console.log(res.reply, res.thread_id)

`streamMessage(options)`

Streams the reply token-by-token over Server-Sent Events. Drive your UI from the handler callbacks.

await client.streamMessage({
  content: 'Walk me through onboarding',
  threadId: existingThreadId, // optional
  handlers: {
    onTextDelta: (chunk) => appendToBubble(chunk),
    onToolCallStarted: (tool) => showToolChip(tool),
    onToolCallCompleted: (tool) => clearToolChip(tool),
    onToolCallError: (tool, err) => showError(tool, err),
    onDone: ({ threadId, conversationId, agentMessageId, nextAction }) => finish(threadId),
    onError: (err) => showError(err.message)
  },
  signal: abortController.signal // optional; abort on unmount / thread switch
})

`loadConversation({ threadId, signal? })`

Load a thread’s prior messages plus the orchestrator’s current next action.

const snapshot = await client.loadConversation({ threadId })
// snapshot: { thread_id, conversation_id, messages[], next_action? }

Each message includes role (user | assistant | system), content, and a sender_kind (customer | agent | teammate) so you can distinguish AI replies from a human CSM’s.

`listConversations({ source?, limit?, signal? })`

List the customer’s conversations for a history panel.

const { conversations, total } = await client.listConversations({ limit: 20 })
// each: { thread_id, conversation_id, title, last_message_at, message_count }

Statisfy doesn’t store read-state — compute unread client-side by diffing each thread’s message_count against the last count you saw. See the API Reference for the underlying endpoints, request/response shapes, and error codes.

Getting Started

Accounts

People & Contacts

Opportunities

Activities

Views

Filters & Custom Fields

Projects

Portals

Tasks

Reports

Workflows

Dashboard

Workbench

Digital Workers

Stella AI

Campaigns

Knowledge Base

Approvals

Digital Worker Chat