Skip to main content
The Statisfy SDK (@statisfy/digital-workers-react) lets you embed Statisfy experiences — a Digital Worker chat and a Project (onboarding) module — directly into your own React application or customer portal. Your customers interact with their Statisfy data without ever leaving your product.
The SDK is the programmatic counterpart to Portals. A Portal is a Statisfy-hosted site; the SDK lets you build the same experiences inside an app you host yourself.

​
What you can build

Digital Worker chat

A full chat widget that talks to one of your Digital Workers — streaming replies, inline forms, conversation history, unread badges, and live replies from a human CSM.

Project module

A read/write view of a customer’s onboarding project: milestones, tasks, progress, and editable fields — as a pre-built component or composable primitives.

​
Package

The SDK is built with React and TypeScript and is fully typed — every component, hook, and client method ships with type definitions.

​
How it fits together

You wrap your app once in <StatisfyProvider>, which supplies the gateway URL and authentication. Every SDK component reads that shared config — they never take connection props themselves.
Inside a Statisfy-hosted Portal, components can take their settings from the portal’s portal.runtime.json rather than props — pass a configId instead of a workerId. See Portal Runtime Config.

​
Authentication model

The SDK authenticates each request with two pieces:
  • A bearer token — a short-lived HS256 JWT, signed with your workspace’s JWT secret. Your app supplies it through the provider’s getToken callback; the SDK never mints or stores it.
  • A publishable key — pk_live_… / pk_test_…, safe to ship in client-side code. It identifies your Statisfy tenant.
Where that token comes from depends on how you’re using the SDK — the SDK itself doesn’t care, it just calls getToken.
Your backend mints the token. It signs a short-lived HS256 JWT with your workspace’s JWT secret and hands it to your frontend, which returns it from getToken. There is no Statisfy exchange endpoint in this path.The claims Statisfy requires are the standard iat / exp plus the end user’s email, which is how the gateway resolves who is asking. Because your backend mints the token, the long-lived secret never leaves your server — see Publishable Keys & Secrets.
Only the portal path produces a token with a customer_id claim, and the project endpoints (/sdk/v1/*) require one — a vendor-minted token without it is rejected with 401 not_a_portal_session. The Digital Worker chat endpoints work with either. So ProjectModule and useProject are portal-session features today; chat is available to both.
In the portal path, the bearer is not the raw Clerk/IdP JWT — it’s the Statisfy session token returned by /sdk/auth. Never sign tokens in the browser: only the publishable key is safe client-side.
The full token lifecycle, headers, and error codes are in the API Reference.

​
Next steps

Getting Started

Install, wire up the provider, mint a token, and render your first component.

Digital Worker Chat

Embed the chat widget, render inline forms, and use the headless client.

Project Module

Show and update a customer’s onboarding project.

Portal Runtime Config

Configure components from portal.runtime.json and resolve per-customer $field values.

API Reference

Endpoints, headers, error codes, and TypeScript types.