Portal Runtime Config

Inside a Statisfy-hosted Portal, SDK components can read their settings from the portal’s runtime config instead of hardcoded props. That’s what lets a non-developer repoint a chat module at a different Digital Worker from Settings without touching code — and it’s what makes a component’s values differ per signed-in customer.

This page only applies to portals. If you’re embedding the SDK in an app you host yourself, pass props directly and skip it.

The config file

Every portal repository has a portal.runtime.json at its root. Config rides the commit, so the file that ships with a build is that build’s config — there’s no separate promote step.

{
  "shared": {},
  "components": {
    "digital_worker_chat": {
      "support": { "worker_id": "your-digital-worker-uuid" }
    },
    "onboarding_module": {
      "onboarding": { "worker_id": "another-worker-uuid" }
    }
  }
}

The shape is { shared: { name: value }, components: { type: { configId: { prop: value } } } }:

Level	Meaning
`shared`	Portal-wide properties consumed by more than one component.
`components.<type>`	The component type, e.g. `digital_worker_chat`, `onboarding_module`.
`components.<type>.<configId>`	One instance’s slot, keyed by the component’s `configId` prop. Two instances with the same `configId` share this slot.

A component opts into config mode by taking a literal configId — see Config mode. The portal save gate extracts that id into the component manifest and rejects a missing or non-literal one.

Two kinds of value

{ "worker_id": "6f1c…" }                       // LITERAL — the value is the answer
{ "greeting":  { "$field": "welcome_note__c" } } // FIELD — per-customer lookup

Literal — a plain string, available at load with no network round trip (it’s bundled in the commit).
Field reference — {"$field": "<account field key>"}. Resolved per visitor to that field’s value on the signed-in customer’s account, so one build renders differently for each customer.

A field reference resolves only while the portal exposes that account field (Read or Edit) in Settings → Account fields. A reference to a hidden field resolves to null, and the save gate rejects it. See Exposing account and people fields. Locked properties are exempt and always resolve. Blank collapses to unset: "" and a missing field both resolve to null.

Reading resolved values: `useResolvedFields`

Components in config mode resolve their own values, so you rarely need this hook — reach for it when you’re writing a custom component that wants the same per-customer data. These three exports are re-exported identically from @statisfy/ai-react too — import them from whichever package you already use.

import { useResolvedFields, isFieldRef } from '@statisfy/portal-react'
import runtime from '../portal.runtime.json'

function WelcomeBanner() {
  const { resolve, loading, error, refetch } = useResolvedFields()
  const configured = runtime.components?.hero?.main?.greeting

  if (error) return <button onClick={refetch}>Retry ({error.message})</button>

  // Literals return immediately; $field refs are null until the fetch lands.
  const greeting = resolve(configured)
  if (loading && isFieldRef(configured)) return <Skeleton />

  return <h1>{greeting ?? 'Welcome'}</h1>
}

`UseResolvedFieldsResult`

Field	Type	Description
`fields`	`Record<string, string \| null>`	Account-field key → the signed-in customer’s value. Empty until the fetch lands, and on error.
`locked`	`Record<string, string \| null>`	Schema-locked property name → resolved value (e.g. `onboarding_project_id`).
`resolve`	`(value) => string \| null`	Substitute one config value. Literals return immediately; `$field` refs read the fetched map — `null` while loading, for unknown keys, and for unset values.
`loading`	`boolean`	True while a fetch is in flight, including refetches. Only field-dependent values need to wait on it.
`error`	`Error \| null`	The last fetch failure; cleared when a refetch starts.
`refetch`	`() => void`	Re-run the fetch.

isFieldRef(value) narrows a config value to { $field: string } — use it to decide whether a value needs to wait on loading.

resolve returns null for an unknown or unset field, so always supply a fallback. A $field value is not guaranteed to exist: the account field may be blank for this customer.

Outside React: `fetchResolvedFields`

The same payload, without the hook:

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

const { field_values, locked_values } = await fetchResolvedFields(
  { baseUrl: 'https://api.statisfy.com', getToken, publishableKey: 'pk_live_…' },
  { signal: controller.signal }
)

It resolves against GET /sdk/v1/config/portal for the session’s customer — see the API Reference.

Editing config

Surface	How
Settings UI	The portal’s Settings screen renders controls from the component schema — the intended path for non-developers.
Editing the file	Treat `portal.runtime.json` like any other portal file. The server re-formats it canonically on save.

Locked properties are pinned platform-wide: they’re absent from the file by definition, resolve server-side under a stable schema name, and can’t be overridden per portal.

Unknown or inactive values fail the build — a worker_id that doesn’t exist, or points at an inactive worker, won’t ship. Validate before saving.

Getting Started

Accounts

People & Contacts

Opportunities

Activities

Views

Filters & Custom Fields

Projects

Tasks

Reports

Workflows

Dashboard

Workbench

Stella AI

Campaigns

Knowledge Base

Approvals

Portals

Statisfy SDK

Digital Workers

Portal Runtime Config

The config file

Two kinds of value

Reading resolved values: `useResolvedFields`

`UseResolvedFieldsResult`

Outside React: `fetchResolvedFields`

Editing config

​The config file

​Two kinds of value

​Reading resolved values: useResolvedFields

​UseResolvedFieldsResult

​Outside React: fetchResolvedFields

​Editing config

The config file

Two kinds of value

Reading resolved values: `useResolvedFields`

`UseResolvedFieldsResult`

Outside React: `fetchResolvedFields`

Editing config