Skip to content

How calls run

From a saved flow to the verbs Jambonz plays: the compiler, the webhook exchange, and the limits on each hook. The internals behind each step are in docs/internals/runtime.md and docs/internals/compiler.md (indexed from AGENTS.md).

raw JSON / dict
│
▼
[1] Normalizer: Apply each component type's defaults across the tree
│
▼
[2] Validator: Per-component checks, branch-outlet legality, goto targets
│
▼
[3] CodeGen: Flatten the component tree → flat node_map of Jambonz verb dicts
│ keyed by dotted-path ids (main.menu.tsales), with routing metadata
▼
[4] Graph: Synchronous cycle detection over the flattened map
│
▼
[5] Pipeline: Assemble CompiledFlow (4 handler entry ids) → CompilerResult

Jambonz is stateless; each call leg is a series of HTTP webhook exchanges:

Inbound call
│
▼ POST /webhooks/{flow_name}
Execute from the main entry node
→ Accumulate Jambonz verbs
→ Stop at a blocking component (menu/collect_input/voice_input/transfer/sip_refer/
enqueue/dequeue/conference/ai_agent)
→ Return verb array (with an actionHook URL carrying the node's dotted id)
│
▼ POST /webhooks/{flow_name}/continue/{node_id}
(Jambonz sends gathered digits/speech, dial_call_status, queue_result /
dequeue_result, refer_status)
Resolve the branch (digit → invalid → default; dial status → success/failure/timeout;
queue outcome → the outlet of that name; no input → timeout), resume execution
→ Return next verb array

A Jambonz application has two webhooks, and both point here: the calling webhook (/webhooks/{flow_name}) and the call status webhook (/webhooks/{flow_name}/callstatus). There is no error or disconnect hook in Jambonz, so:

  • the Error handler runs when a component fails (on whichever hook that happens);
  • the Call Status handler runs on every status event of the call ({{call_status}} says which: trying, ringing, early-media, in-progress, then completed / failed / busy / no-answer), but only for the leg the flow drives: the status hook also hears every leg a Transfer dials, and those (the ones carrying a parent_call_sid) are ignored;
  • the Disconnect handler runs once, from the call status webhook, on the call’s final status. Without the call status webhook configured, neither of the last two runs.

/error and /disconnect still answer, for deployments that point something at them, but nothing in Jambonz calls them. A named subflow runs at /subflows/{subflow_name}. Jambonz also fetches the flow’s application environment variables with an OPTIONS request to /webhooks/{flow_name}. The full route list is in API.md.

Hooks are not idempotent, and Jambonz’s retry option stays on the call webhook. Jambonz waits about 10 s for a hook and does not retry unless the URL carries a #rc= fragment (#rc=2&rp=ct). Such a fragment on the calling webhook applies to that request only: the continuation URLs this app hands back (/continue/…) carry none. That is on purpose: a resumed hook re-run would capture the input and run the flow’s side effects (HTTP requests, SMS, logs) a second time.

A subflow component runs the named subflow and, when the subflow reaches its end (right away or after any number of menus and transfers), the call continues with the component after it. The return address rides on the call with the other variables, and one subflow can be used from as many places as you like. Calls nest; a subflow that calls itself (directly or through others) is refused at save. Inside a subflow, Exit Call Flow and Disconnect end the whole call, and a Connector to a component outside the subflow leaves it for good (nothing returns afterwards).

Call context (variables, digits, from/to) rides on the call, not in the manager: before each suspension a tag verb persists the working variables under customerData.internal, which Jambonz echoes back on the next webhook. The driver holds no local call state, so a restarted instance picks up calls already in progress. That is not a licence to run several: the file store is single-writer, every instance takes an exclusive lock on its store directory, and an instance on a copy of the store has its own writable editor that diverges from the first save; so run exactly one instance per store. See OPERATIONS.md.

Three guards bound one hook. _MAX_ITERATIONS caps how many nodes may run (a runaway run is discarded and the flow’s Error handler runs instead); MAX_HOOK_SECONDS caps how long they may take; and WEBHOOK_MAX_CONCURRENCY caps how many hooks execute at once, shedding rather than queueing beyond it.

Jambonz waits about 10 seconds for a hook’s answer (the feature server’s JAMBONES_HTTP_TIMEOUT) and does not retry: an answer after that reaches nobody, and the caller hears the line drop. So MAX_HOOK_SECONDS defaults to 8: every http_request ends by the end of that budget (or its own HTTP_REQUEST_TIMEOUT, whichever is sooner, failing into {{http_error}} like any timeout); past it the hook routes to the flow’s Error handler, which runs on what is left of the same budget rather than a fresh one, as does the Disconnect handler the call-status hook runs after its Call Status handler. A hook as a whole therefore answers within about 8 s. Raising the budget above ~9 s buys nothing, because Jambonz has stopped waiting. A shed hook that a caller is listening to answers with a short apology and a hangup; the disconnect/call-status notifications answer 503. Every shed answer carries the header X-Jamhooks-Shed: 1, which is how the load test (OPERATIONS.md) counts them.

Every log line names its call. Each hook opens a call scope, so flow, call_sid, hook and the current node_id are stamped onto every record written beneath it, including from a flow’s own Log nodes and from third-party libraries. With LOG_FORMAT=json they are top-level fields, so call_sid:"..." is the query that answers “what happened on this call?”. Every hook also ends with one completion line, the deployment’s metrics source (OPERATIONS.md).

Every routing decision is a line too (logger app.routing): waiting when a hook leaves the call waiting at a component (a Menu, User Input, Transfer, queue, …), and routed when that answer comes back, or when a Conditional or Date & Time picks its branch on the way. Each carries the component (node_id, node_type, its label) and, when routed, a result (what happened, in the component’s outlet names: 2, timeout, invalid, failure, hangup, a rule’s key with its name in result_label) and an outlet, the branch the call took (the result’s own when it is wired; else the fallback, or next, end, error_handler). Never the digits or speech themselves. Only a real call writes them: Simulate runs the same steps and writes none. The dashboard’s Routing panels read them (OPERATIONS.md).

The editor’s Debug tab (in the right-hand sidebar, node-red style, beside Simulate) streams what real calls are doing to this flow, as they do it: per node, the outcome, the verbs emitted and any unresolved {{vars}}, then a closing line per webhook with what went back to Jambonz. Rows are grouped by call, and a filter narrows them to a call sid, a node or a hook. It is the deployed counterpart to Simulate (the same per-node record, from a real call) and usually the fastest way to answer “why did this caller end up in the wrong branch?”.

Nothing is stored, anywhere. Events are pushed over a websocket (/ws/trace/{flow_id}) to whoever is watching and then forgotten: no buffer, no history, no catch-up. A call that happens while nobody is watching leaves no trace, and the rows you can see live only in your browser tab, capped at the most recent 300.

The pane’s Start button is what switches tracing on, not opening the tab. The pane starts detached; Start attaches it, and tracing runs for a flow exactly while at least one pane is attached to it, held in memory. Once attached it stays attached while you switch sidebar tabs or select components (which brings up Properties), and reconnects if the connection drops. Stop detaches it, and so does leaving or closing the page, or the sign-in ending. There is no setting to enable and forget about: with nobody watching, the runtime builds no trace at all, so an untraced call costs a dictionary lookup. CALL_TRACE_ENABLED=false is the deployment’s veto: the socket then refuses every connection, for a deployment that will not have live call data on a screen at all.

The socket authenticates itself (session login, or the trusted header when auth is delegated), and read-only accounts may watch. It has to: neither the auth beforeware nor any middleware in this app runs for a websocket scope.