Source view

Retained Next source

This page preserves the merged Next documentation snapshot at e1ddcf6940adb7b619ce509063749e740eecc795. It can describe implementation beyond the source revision selected for the rebuilt Next guides. Retain the implementation-scope notes below and confirm your deployed version before applying these details. This is not a current-release availability or deployment claim. For the task-based entry point, see the rebuilt guide.

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 does not expose — for example, pinning audio.linkFormat on a phone endpoint.
• 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.

Session configuration

Call-level limits and warnings live in the top-level sessionConfig object (edited in Flow Settings → Call duration). This is separate from gatewayProfile.failover — the give-up timeout here is a standalone watchdog that fires even when failover is disabled.

Unreleased (Next). The give-up fields below are documented ahead of platform PR #473 (internal implementation reference), open and draft when reviewed on 2026-09-25. Two SCRUM-689 requirements are not in it: the give-up timeout is resolved once at flow load and is not reconfigurable mid-call (the bot-originated update_bot_delay_config event updates only gatewayProfile.failover.botNoInputGiveUpTimeoutMs), and the give-up warning is synthesized text only — there is no give-up audio-URL field (AudioCodes botNoInputUrl parity applies to the intermediate comfort prompt only).

{
  "sessionConfig": {
    "maxCallDurationSeconds": 5400,
    "maxDurationWarningMessage": "This call will end shortly.",
    "botNoInputGiveUpTimeoutMS": 15000,
    "botNoInputGiveUpWarningMessage": "I didn't hear a response. Ending the call.",
    "botNoInputGiveUpTransfer": {
      "target": "+49301234567",
      "routingPool": "support-pool"
    }
  }
}

Field	Type	Range / limit	Meaning
maxCallDurationSeconds	number	10–7200 s	Source-schema range; the number input advertises a 60 s minimum. Per-flow max call duration; force-hangup classified max_call_duration.
maxDurationWarningMessage	string	max 100 chars	Spoken ~10 s before the max-duration hangup.
botNoInputGiveUpTimeoutMS	number	1000–120000 ms	Standalone bot no-input give-up timeout, resolved once at flow load (not changeable mid-call); terminal action classified bot_no_input_give_up (BotSide). Out-of-range values are clamped into range on parse by the flow schema (so legacy flows stay loadable); the Flow Builder refuses to commit out-of-range input. There is no disabled state — leaving the field unset falls back to the 15000 ms deployment default.
botNoInputGiveUpWarningMessage	string	max 100 chars	Spoken just before the give-up terminal action. Text (TTS) only — no audio-file URL is supported on this path.
botNoInputGiveUpTransfer	object	—	Transfer instead of hangup on give-up. target (phone number or sip:/sips: URI) is required; routingPool (SBC egress route) is optional and ignored for SIP URIs. Transfers via sip_refer; falls back to hangup on failure.

The sessionConfig object is optional. Within an existing object, the schema fills a missing maxCallDurationSeconds with 5400; omitting the whole object allows the deployment duration fallback. Missing warning and give-up fields use their deployment fallbacks (MAX_CALL_DURATION_WARNING_MESSAGE, BOT_NO_INPUT_GIVE_UP_TIMEOUT_MS, BOT_NO_INPUT_GIVE_UP_WARNING_MESSAGE). The botNoInputGiveUpTransfer object has no env fallback — its presence means "transfer", its absence means "hangup". The give-up timeout has no env-fallback "off" state either: the deployment default always applies when the flow omits it. See Call duration and the env var index.

Provider configuration

Provider configuration is inline-only as of v0.9.14-patch1. Flow defaults live under flow.providers, and voice-agent overrides live on the node that needs them. Older provider references such as { ref: "<provider-id>" } are not resolved by patched runtimes.

When importing or repairing older flow JSON, replace provider references with the full inline provider config before publishing the draft.

Portability rules of thumb

• Provider configuration is part of the flow definition; saved provider references are not portable and are no longer supported in v0.9.14-patch1.
• 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

• Flow Designer overview
• Inspectors
• API reference
• TelPhi SDK reference