Handler contract

A node handler is the runtime behaviour behind one kind of node on the flow canvas. It implements Fapost\Foundation\Contracts\NodeHandlerInterface.

interface NodeHandlerInterface
{
    public function type(): string;
    public function version(): int;
    /** @return int[] */
    public function supportedVersions(): array;
    public function label(): string;
    public function category(): string;
    /** @return array<string, mixed> */
    public function configSchema(): array;

    public function execute(
        array $nodeConfig,
        array $state,
        NodeExecutionContext $context,
    ): NodeExecutionResult;
}

Identity

type() is the node’s unique identifier, such as send_message. It must be unique across every registered handler, including those from other extensions. version() is the handler’s current version; the engine resolves a handler by the pair (type, version) from an in-memory registry, with no database query on the hot path. label() and category() are what the builder shows: the node’s name and the group it appears under.

Configuration

configSchema() returns the schema the builder uses to validate the node and draw its form. This is the mechanism that lets an extension be configurable without shipping any front-end code — see Builder UI extensions.

Execution

execute() receives three things:

Argument	What it is
`$nodeConfig`	The node’s payload from the flow definition JSON: `id`, `type`, `version`, `config`, and so on
`$state`	Namespaced session state, read-only for the handler
`$context`	`NodeExecutionContext` — tenant, contact, and session metadata, plus the writers a handler is allowed to use

It returns a NodeExecutionResult, built through one of its named constructors:

NodeExecutionResult::executed(sourceHandle: 'default', stateChanges: [
    'flow.answer' => $value,
]);

NodeExecutionResult::waiting();   // the flow pauses for input
NodeExecutionResult::delayed();   // pauses like waiting() — see below
NodeExecutionResult::delayed(resumeAt: $when);   // pauses until a specific time

delayed() has two forms:

Call	Session	Contact message meanwhile	When the handler runs again
`delayed()`	`waiting_input`, same as `waiting()`	runs your handler again	with the next inbound message
`delayed(resumeAt: $when)`	`paused`	answered with the assistant’s busy notice, not delivered to your handler	at `$when` (a queued wake-up), or with the first message after it

Without resumeAt, the session waits exactly as after waiting(): the contact’s next message runs your handler again, and the handler decides whether it is time to move on — the built-in delay node works this way. Nothing wakes the node without an inbound message. With resumeAt, nothing the contact sends reaches your handler until that time: the engine wakes the node itself, and only then does the flow resume. Your handler tells the two situations apart through NodeExecutionContext::$resumedAfterDelay — true only on the run the engine triggered for this resumeAt, false on every other call, including the one that first asked for it:

public function execute(array $nodeConfig, array $state, NodeExecutionContext $context): NodeExecutionResult
{
    if ($context->resumedAfterDelay) {
        // The engine woke this node at the time it asked for — move on.
        return NodeExecutionResult::executed();
    }

    return NodeExecutionResult::delayed(resumeAt: now()->addHour());
}

Do not read the resume_at you asked for back out of $state. The marker the engine uses to schedule and match the wake-up is an internal detail, not part of the handler contract, and may change — rely on $resumedAfterDelay.

The handler must be graph-unaware

A handler returns a sourceHandle, never the id of the next node.

The engine resolves what comes next from the flow’s edges, using the source node id together with the handle the handler returned. A handler that decides which node runs next has taken a decision that belongs to the flow definition, and the same handler can then no longer be reused in a differently-shaped flow. sourceHandle defaults to 'default'. A node with several outcomes — a branch, a validation that can fail — returns a different handle per outcome, and the person building the flow wires each handle where they want it to go.

Writing outside the session

State changes go back through stateChanges on the result. Mutations that live outside the session JSON — contact attributes, contact language — are performed by the handler through the writer it receives on NodeExecutionContext, such as ContactWriterInterface.

Do not return a legacy effects[] array. It was removed; handlers use the writer or port from the execution context instead.

Overview

Development environment

Extension model

Building extensions

Flow nodes

Extension surfaces

Shipping an extension

Core internals

Contributing to Core

Handler contract

Identity

Configuration

Execution

The handler must be graph-unaware

Writing outside the session

​Identity

​Configuration

​Execution

​The handler must be graph-unaware

​Writing outside the session

Identity

Configuration

Execution

The handler must be graph-unaware

Writing outside the session