Skip to main content
Version: 0.9.12

Source view

platform v0.9.11verified 2026-05-14

A Delphi flow is, underneath, a flow definition JSON document. The Flow Designer renders it on the canvas; the AI Flow Builder generates it from a brief; the source view lets you read or write it directly.

Why use it​

  • Portability — paste a flow definition into another app on the same platform, or into the same app on another environment (staging → production).
  • Hand edits the UI doesn't expose — for example pinning audio.linkFormat on a phone endpoint, or tuning detection thresholds on a managed integration.
  • Diff and review — copy the source into your reviewer of choice, or compare two versions side-by-side with Version history.
  • Programmatic generation — produce flows from a script and paste them in.

How it looks​

Open from the toolbar. The drawer shows the definition formatted JSON, with a toggle for the authoring form (what the UI works with) and the runtime form (what the platform actually executes). The Flow Designer compiles between the two on the fly.

Edits are validated against the platform's flow schema; invalid edits show inline errors and prevent save. Valid edits replace the current draft definition.

Shape of a flow definition​

At a high level a flow definition has:

{
  "flow": {
    "entryPoints": [
      /* one entry per endpoint */
    ],
    "nodes": [
      /* conversation nodes */
    ],
    "sideFlows": [
      /* optional sub-graphs */
    ],
    "providers": {
      /* default provider config */
    },
    "variables": [
      /* declared flow variables */
    ],
    "settings": {
      /* language, recording, ... */
    }
  },
  "metadata": {
    /* author, timestamps, version */
  }
}

Each conversation node has at least id, type, a per-type configuration, and zero or more transitions. Each entry point has a type (phone, web_voice, web_chat) and the fields the Endpoint Inspector exposes.

The full schema is shipped as part of the platform's @delphi/validation contract. The TelPhi SDK reference and API reference describe the shape clients see at runtime.

Portability rules of thumb​

  • Provider credentials (API keys) are not part of the flow definition. They live in Team variables and are referenced by name.
  • Base numbers on phone endpoints are platform-specific. When pasting between environments expect to re-pick the base number after import.
  • Slugs for Web Voice / Web Chat endpoints must be unique inside the destination app — the Flow Designer auto-renames on conflict.
  • Tool handlers referenced by name need to exist on the destination team / platform.

Validation​

Every save runs the same validation as the manual canvas, plus structural checks (no orphan nodes, every transition has a valid target, every variable reference resolves). Errors block save; warnings (e.g. "two voice agents with the same name") are surfaced but non-blocking.

See also​