Configurations
A configuration is the policy a conversation is analysed under. It composes a set of operators — each with its own granularity and context settings — together with the actions that fire when their results meet a condition.
The configuration is the unit you select at run time: attach one to a trunk so it applies to every call, or supply one per call when you start a session. Configurations are owned by your account and addressed by a stable uuid that survives every edit.
Granularity
Granularity decides when each operator runs. It is set on the operator reference inside the configuration, not on the operator itself — so the same operator can run at different cadences in different configurations, or even more than once within one configuration.
| Setting | Behaviour |
|---|---|
on: turn |
Run on each conversational turn |
on: turn, every: N |
Run every N turns |
on: turn, until_match: true |
Run each turn, then stop once a non-null result is produced |
on: conversation_end |
Run once when the conversation ends, over the full transcript |
A turn operator produces live signals as the conversation unfolds; a conversation_end operator produces a single post-conversation result. A configuration can mix both freely.
Context settings
Each operator reference can widen the context the operator reasons over:
context_window— how many prior turns to include in the operator's input.include_prior_results/prior_results_window— inject the operator's own recent results back into its context, for cumulative reasoning over a running assessment. The window defaults to a small number of recent results; set it to1for accumulatingmulti_tagoperators, where the latest result already holds the complete set.include_operator_results/operator_results_window— inject the recent results of other named operators in the same configuration, so one operator can reason over another's findings (for example, a guidance operator reading a protocol-adherence result).parameters— values for the operator's declared parameters, keyed by parameter name.
Operator references and versioning
Each operator reference pins to a specific operator version. Editing an operator never silently changes a configuration that references it — the reference holds its pinned version until you upgrade it explicitly.
Omit version when adding an operator to bind to its current version. When a newer version later exists, the resolved reference reports current_version and sets upgrade_available, and POST /configurations/{uuid}/upgrade-operators repoints references to the current version in one step.
Identity and lifecycle
uuid— the stable identifier. It never changes, so long-lived bindings (a trunk, a session request) keep resolving to the same configuration.version— a generation counter bumped on each write. It records that the configuration changed; it is not an addressing axis, and there is no per-version history.is_active— whether the configuration is selectable for new sessions.sync_state—liveonce the running pipeline reflects your latest edit, orpendinguntil the next sync cycle picks it up. An edit is durable immediately; it takes effect on new sessions oncesync_stateislive.
Validating before you save
POST /configurations/validate runs the same checks as a real write without persisting anything, returning valid plus any human-readable errors. Use it as a dry run before creating or replacing a configuration.
Creating a configuration
A configuration can be built from scratch, or derived from a template — a pre-populated starting point you complete and save as your own. Either way the result is a configuration you own, identified by its own uuid.