Nodes

A flow draft is a single JSON object, { "trigger": { ... } }, with the whole graph nested inside the trigger. Every node is an object whose stepClass names its type. It is the same shape the draft read endpoint returns and every template payload carries, so the most reliable way to write one is to start from a template and change it.

This page covers what comes after the trigger. The trigger itself, its exits and its re-entry settings are in Triggers and exits; the five kinds of wait are in Delays and waits.

How nodes chain

• A sequential node continues on nextStep, one node object. A node with no nextStep ends that line.
• A branch node has paths and, on most branches, a defaultPath. Each path is { "name"?, "nextStep", ...its condition }. When a path's chain ends, the contact continues on the branch's own nextStep, shared by every path; a path with no nextStep goes straight there.
• There are no merges or loops. The graph is a tree, and a node reachable from more than one place is a validation error.
• Exits are not nodes in the chain. They live in the trigger's exitSteps.
• uid is optional on every node and path. Keep the one you read so the node keeps its identity across saves; omit it on nodes you add.

{
  "trigger": {
    "stepClass": "TRIGGER_CONTACT_EVENT",
    "eventType": "update",
    "eventDatasource": null,
    "eventQueryFilter": { "root": { "type": "group", "join": "and", "children": [
      { "type": "event_condition", "key": "update.new-contact", "operator": "matches-bool", "values": [true] }
    ] } },
    "maxActivationsPerContact": 1,
    "nextStep": {
      "stepClass": "ACTION_BRANCH_SMART_DELAY",
      "minDelaySeconds": 300,
      "maxDelaySeconds": 86400,
      "preset": "recommended",
      "urgency": "balanced",
      "legalHours": true,
      "paths": [
        {
          "outcome": "waitComplete",
          "nextStep": {
            "stepClass": "ACTION_SEQUENTIAL_SEND",
            "channelType": "sms",
            "channel": {
              "channelType": "sms",
              "compliancePolicy": "no-opt-out",
              "options": [
                { "sender": "67bdfa983114d0062d733795", "template": "Welcome, {{_first_name}}! Unsubscribe: {{unsubscribe}}", "allowUnicode": false }
              ]
            }
          }
        },
        { "outcome": "cannotSatisfy" }
      ]
    }
  }
}

Relations are bare ids

A node that references something else — a sender, a data source, a segment — takes the bare id string, never an object such as { "id": "..." }. The read shape of some other endpoints uses objects; the draft does not (an object carrying an id is tolerated and flattened, but write the string).

Every reference must belong to this project: sender ids from GET /channel/sms/sender or GET /channel/rcs/sender, data source ids from the event volumes probe, segment uids from GET /segment. An id that does not exist is a 422; one that exists in another project or organization is a validation error on the draft. Copy ids from those responses; never retype or guess them.

The nodes the API accepts

Only these stepClass values may be placed through the API. A draft containing any other is refused with a 400 before anything is saved, and the message lists the allowed ones.

The dashboard has a few more — a delay where a model picks the moment, and a trigger that fires on a schedule — which cannot be placed through the API. A flow built in the dashboard with one of them can be read, but a replace that carries it back is refused, so leave such flows to the dashboard.

The send

ACTION_SEQUENTIAL_SEND sends one SMS or RCS message and moves on at once: it has no success or failure path. To act on whether the message arrived, follow it with a delivery wait.

Translations

An option may carry localizations: [{ "language", "template" }]: the same message in other languages. At send time each contact receives the translation matching their language, and anyone else receives the option's own template. A translation uses the option's sender; leave its sender out and it takes it on save, so setting the option's sender is enough. Multi-language messages depend on the organization's plan; template payloads only carry a translation when the plan allows it.

Fallback

An RCS channel may carry fallback: another channel object — in practice an sms one, with its own sender and text — sent when RCS cannot reach the contact. It applies the parent's consent policy.

• An SMS channel cannot have a fallback, and a channel cannot fall back to its own type.
• skipFallback: true switches the fallback off without deleting it.
• sendUnsupported (default true) also sends RCS to contacts whose RCS support is unknown.

With channel=rcs, the template list builds every send this way: a plain-text RCS message with the original SMS as its fallback. Both levels need a sender.

Sequential nodes

All continue on nextStep.

Branches

Fixed outcomes

The node decides which paths exist; you fill each path's nextStep.

• ACTION_BRANCH_CONTACT_CONSENT routes by whether the contact would pass a consent check: channelTypes (sms, rcs), channelMatchMode (all or any) and compliancePolicy. paths holds exactly one "outcome": "allowed" and one "outcome": "blocked", and there is no defaultPath. It routes, it does not replace the send's own policy. To split a journey by consent, use this branch rather than a segment.
• ACTION_BRANCH_TIMEZONE_DELAY and ACTION_BRANCH_SMART_DELAY: one waitComplete and one cannotSatisfy path. See Delays and waits.
• ACTION_BRANCH_MESSAGE_DELIVERY_WAIT: paths by delivery outcome. See Waiting for delivery.

Conditions

paths are evaluated in order and the first that matches wins; defaultPath, which is required and carries no condition, takes everyone else.

The branch that pauses until the contact acts, ACTION_BRANCH_CONTACT_EVENT_WAIT, is a wait as much as a branch: see Waiting for an event.

Random split

ACTION_BRANCH_ABTEST splits contacts at random. Each entry of paths has an integer percentage, and defaultPath carries the remainder as its own percentage. The paths must leave the default a share.

What's next