Getting Started with the Statisfy SDK

​

Prerequisites

• A React 18 or 19 application.
• A publishable key for your workspace (pk_live_… or pk_test_…) — see Publishable Keys & Secrets.
• Embedding in your own app only: a JWT secret (generated alongside the publishable key) and a backend that can sign a short-lived JWT with it. The secret must never reach the browser. A Statisfy-hosted Portal needs neither — <PortalAuthGate> owns sign-in, so there is no secret to hold and no backend to write.

​

1. Install

npm install @statisfy/ai-react

import '@statisfy/ai-react/styles.css'

npm install @statisfy/portal-react

import '@statisfy/portal-react/styles.css'

npm install @statisfy/portal-react @statisfy/ai-react

import '@statisfy/portal-react/styles.css'
import '@statisfy/ai-react/styles.css'

npm install @statisfy/ai-react @statisfy/sdk-core

​

2. Supply a session token

​

In your own app: your backend signs it

// YOUR BACKEND — the secret never leaves your server.
import jwt from 'jsonwebtoken'

app.get('/statisfy-token', requireYourOwnAuth, (req, res) => {
  const token = jwt.sign(
    { email: req.user.email },
    process.env.STATISFY_JWT_SECRET,     // your workspace's JWT secret
    { algorithm: 'HS256', expiresIn: '1h' }
  )
  res.json({ token })
})

// YOUR FRONTEND — fetch from your own endpoint; no Statisfy secret here.
async function fetchStatisfyToken(): Promise<string> {
  const res = await fetch('/statisfy-token')
  if (!res.ok) throw new Error(`Token mint failed: ${res.status}`)
  const { token } = await res.json()
  return token
}

​

In a Statisfy Portal: <PortalAuthGate> handles it

import { PortalAuthGate, PortalUserMenuSlot } from '@statisfy/portal-react'
import { portalConfig } from '../portal.config'

export function App() {
  return (
    <PortalAuthGate
      baseUrl={portalConfig.apiBaseUrl}
      portalId={portalConfig.portalId}
      publishableKey={portalConfig.publishableKey}
    >
      <header>
        <PortalUserMenuSlot />
      </header>
      <YourPortal />
    </PortalAuthGate>
  )
}

​

Multi-account customers: the account switcher

import { PortalAccountSwitcherSlot, PortalSignOutButton } from '@statisfy/portal-react'

// Beneath <PortalAuthGate>, in place of <PortalUserMenuSlot />:
<header>
  <PortalAccountSwitcherSlot />
  <PortalSignOutButton>Sign out</PortalSignOutButton>
</header>

• The switcher always names the account; it’s a control only when there’s a choice. A customer contact who holds two or more accounts gets a dropdown; a single-account contact sees a static label naming their account (falling back to the account’s domain, then its id, when it has no name). If the contact holds no account it reads “No account”, and if the listing failed it reads “Couldn’t load account”. Nothing renders while the first listing is in flight, and <PortalAccountSwitcherSlot> renders nothing in the editor preview or during an impersonation session. The wrapper publishes data-dw-state (switcher | single | empty | error) so you can style each state — see Theming.
• Your own team gets a searchable picker. When the portal’s Your team switch is on and a teammate signs in, the switcher renders a button naming the account they’re on instead of a dropdown, because their book can run to hundreds of accounts. The button opens <PortalAccountPicker> in a popover with the search box focused; picking an account, pressing Escape, or clicking outside closes it. <PortalUserMenu> shows the same picker inside its own popover. It has a scope control for My Book, My Team, and All Accounts (the last only if their role can see all accounts), a search box that matches account name or domain, and a Show more button that loads the next page. Nothing changes for customer contacts.
• Only accounts the viewer may act as are offered. For a contact, that’s the accounts they’re a contact of; for a teammate, the accounts in the scopes their role allows. The server validates every switch against the same rules.
• Switching refreshes all account-scoped data. The session token is re-minted for the chosen account and the subtree under the gate remounts, so the project, tasks, comments, and chat reload under the new account.
• The choice is remembered per portal in the browser, so a returning viewer lands on the account they last used. A stale selection — an account the contact has since been detached from — quietly falls back to their primary account.

import { usePortalAccounts } from '@statisfy/portal-react'

const { accounts, activeCustomerId, loading, switching, error, switchAccount } = usePortalAccounts(client)
await switchAccount('1102')

​

Naming the signed-in viewer

const [email, setEmail] = useState<string | null>(client.getEmail())
useEffect(() => client.subscribe(() => setEmail(client.getEmail())), [client])

​

3. Wrap your app in StatisfyProvider

import { StatisfyProvider } from '@statisfy/portal-react'
import { useCallback } from 'react'

function Root() {
  // Return the current session token; re-mint when needed. Memoize so the
  // provider doesn't re-render its subtree on every render.
  const getToken = useCallback(async () => {
    return await getCachedOrFreshStatisfyToken() // your caching around the step-2 token source
  }, [])

  return (
    <StatisfyProvider
      publishableKey="pk_live_your_key"
      getToken={getToken}
    >
      <YourApp />
    </StatisfyProvider>
  )
}

​

4. Render your first component

import { DigitalWorkerChat } from '@statisfy/ai-react'

function SupportPanel() {
  return (
    <DigitalWorkerChat
      workerId="your-digital-worker-uuid"
      workerName="Onboarding Assistant"
      greeting="Hi! How can I help with your onboarding?"
      className="dw-h-[600px]"
    />
  )
}

import { OnboardingProject } from '@statisfy/portal-react'

// Resolves the signed-in customer's own onboarding project automatically.
<OnboardingProject configId="onboarding" />

​

5. Theming (optional)

• --dw-* CSS variables (~31 tokens: colors, radius, elevation, focus rings, status colors, motion), set on :root or any ancestor. Colors are space-separated RGB triplets, not hex.
• data-dw-part anatomy selectors to restyle exactly one element.

:root {
  --dw-primary: 13 148 136;     /* brand fill: send button, progress */
  --dw-radius-lg: 4px;          /* cards, bubbles, task groups */
}

[data-dw-part='task-row'] { border-radius: 0; }

​

Troubleshooting