Surfaces & Transports

The four axes

Channel configuration is described by four independent axes. Keeping them separate is what makes the model predictable:

Transport families

Voice styles

Any voice-capable transport picks a style in its config. The style — not the surface name — determines how turn-taking works:

{
  "name": "caller",
  "bind": "run_initiator",
  "surface": "widget/voice",
  "config": { "style": "live", "provider": "gemini", "voice": "Kore" }
}

The live style additionally supports latency tuning in config. Defaults are already tuned for snappy turn-taking; override them only when you need different trade-offs:

Connections vs. surfaces

Connections and surfaces are the two ways a workflow touches the outside world, and they are easy to confuse. The distinction is about direction and whether the run waits:

The same vendor can be both. A messaging/telegram surface is where a participant chats with the run and their replies advance it; a telegram connection is a bot token a Notify node uses to fire a one-way alert and move on. One waits for a human; the other does not.

Triggers vs. surfaces

A trigger decides when a run begins; a surface decides how a participant talks to it during the run. They are independent. An inbound phone call (delivered as a webhook from the telephony provider) starts a run whose caller participant is bound to the phone surface — but the same workflow could just as easily be started by a cron trigger that places a phone/outbound call.

Hold policy & async

The engine is always asynchronous at its core. Whether a surface can hold a synchronous leg open while it waits for the next step is a capability, not a workflow setting. Text transports gracefully suspend and resume on the next inbound message; phone and live legs end after config.hold_timeout seconds; email is high-latency and never holds a leg.

Node permissions

Node types and features are trait-gated per surface. The save-time validator checks every node against the capability traits of its effective participant's surface and reports errors (must fix) or warnings (feature degrades gracefully):

The authoritative registry — every surface with its traits, voice styles, config fields, and the full permission table — is served at GET /api/management/surfaces (CLI: chatterfly surfaces, MCP: list_surfaces). Config keys that don't apply to the chosen surface draw a save-time warning.

Per-node overrides

A participant declares a default surface. A Workflow group node may carry a surface override for its subtree — the bare mode formis resolved against the active participant's family (e.g. widget → widget/form) and is only valid on form-capable surfaces. Bare form is never a participant surface. A WorkflowCallnode can override a participant's surface for a single sub-workflow invocation via participant_surfaces, using a full surface id (e.g. messaging/sms).

Support matrix

For outbound calls to external services — the other half of how a workflow touches the world — see Connections. For the design rationale and migration details see Workflows & DSL.