Flows API reference
Manage flow definitions, nested nodes, branching, and draft lifecycle through the public REST API.
Use flows to define the sequence of questions, offers, branches, and actions shown by a widget or hosted page. Creating a flow does not attach it to a widget or publish it.
Authentication and flow operations
Paths below follow https://api.rightmessage.com/v1/{teamPid}. GET requires read or write; mutations require write. The * ability satisfies both. The shared request conventions cover bearer authentication, headers, project access, and rate limits.
| Method and path | Request | Success |
|---|---|---|
GET /flows | No filters or pagination parameters | 200, {"data":[RESOURCE]} |
GET /flows/{flow} | Resource ID from the list | 200, {"data":RESOURCE} |
POST /flows | Create body below | 201, {"data":RESOURCE} |
PUT or PATCH /flows/{flow} | Partial body below | 200, {"data":RESOURCE} |
DELETE /flows/{flow} | No body | 204, empty body |
PUT and PATCH have the same partial-update behavior. An omitted top-level field retains its value. A collection with no resources returns {"data":[]}. Reads return the draft when one exists, otherwise the stable configuration.
Errors and draft effects
The shared error contract applies. Invalid request fields return 422 with message and field-keyed errors. Full-configuration validation can return 500 instead.
Mutations save a draft, not live changes. Publishing applies the whole project draft, including edits made elsewhere. The draft contract covers snapshots, dashboard updates, and save failures.
Flow request and response fields
name is required on create and optional on update. It is a nonempty string with a maximum of 255 characters. definition is an optional object. When omitted on create, it defaults to {"type":"root","child":[]}.
A root definition requires type: "root" and a child array of nodes. It accepts an optional string _uuid. No other root properties are allowed. The service generates missing node UUIDs. A supplied definition replaces the complete stored definition, including every branch. It is not a node-level patch.
The resource contains exactly id, name, and definition. Flow IDs use ofn_.
Node schema
Every node has its listed type and an optional string _uuid, generated when absent. Except for data-action objects, node objects reject undeclared fields. A node run is an ordered array of these nodes.
| Type | Fields, defaults, and nesting |
|---|---|
sg | Optional nullable segmentGroupId identifying a dim_ group or raq_ question. Boolean ask defaults true. split defaults false, or is an array of objects requiring nullable segmentId and a child node run. Branch objects allow no extra fields. |
offer | Optional nullable offerId identifying an ofr_ offer or form. Optional desiredType is form or offer. |
yesno | Optional string note; condition logic object, default {}; yes and no node runs, each default []. |
random | Required split array. Each branch contains only a required child node run. |
highscore | Required split array of objects requiring score, a string or null fallback, and child. Optional mode is scores or variables; optional inverse is boolean. |
redirect | Required string url. Boolean open defaults false. Boolean sendSubscriberData defaults false. |
data | actions array defaults []. Each action requires type and an act_ string id, generated if absent. Types are score, field, variable, add_tag, remove_tag, and set_segment. Actions accept extra action-specific fields. Declared optional strings are tagId, segmentGroupId, and segmentId. For set_segment, a known segment supplies its group ID when omitted. |
message | Required string content. |
code | Required strings name and code; optional string selector. |
webhook | Required string url beginning with https://. Optional string name; method is POST, PUT, or PATCH, default POST; string customPayload defaults empty; boolean fireOnce defaults true; numeric timeoutMs defaults 10000; optional boolean includeVisitorContext. The schema declares no timeout range. |
embed | Senja embed with app, content, and target, detailed below. |
exit | No fields beyond type and UUID. |
The REST request checks nonempty sg.segmentGroupId and offer.offerId references against the current project. These checks recurse through child, split[].child, yes, and no. They do not establish a universal referential-integrity guarantee for every action key.
Data-action runtime fields
The action object is open, but that does not mean arbitrary keys produce a visitor action. Supply the names the runtime reads:
| Action type | Runtime fields |
|---|---|
score | score, the score name; numeric adjust, the amount to add |
field | field, the connected provider's field identifier; string value, parsed as a Liquid template |
variable | variableName and string variableValue, parsed as Liquid. Empty output removes the variable. Optional expiresType: "duration" uses a positive expiresDuration and expiresUnit of minutes, hours, days, or weeks; without duration expiry it stores no expiry timestamp. |
add_tag, remove_tag | tagId, the provider tag ID |
set_segment | segmentGroupId and segmentId |
Provider actions require a connected runtime integration. Tag actions can be queued until the visitor is identified; saving the flow does not perform those provider writes. set_segment records the chosen answer, clears other answers in that group, refreshes visitor segmentation, and requests active synchronization when the visitor reaches it. The REST schema does not validate every one of these runtime fields, so a successful save alone does not establish that an incomplete action will run.
Embed nodes
app defaults to senja, the only schema-supported value. content defaults null. A non-null content object must match one of these closed shapes:
- Widget:
kind: "widget", nonblank stringid, stringname, and stringdesign. - Wall of Love:
kind: "wall_of_love", nonblank stringslug, nonblank stringpermalink, and stringname.
target is either a closed element object requiring kind: "element", string selector, position of inside, before, or after, and a pages logic object; or a closed page object requiring kind: "page" and pages.
An omitted target defaults to {"kind":"element","selector":"","position":"after","pages":{"and":[]}}. New or changed embeds require a registered embed app connected to this project. Unchanged saved embeds do not fail solely because that app was disconnected later. Content is a public resource snapshot, never provider credentials.
Logic objects
Logic objects can contain recursive and and or arrays or a not object. Answer conditions use the question condition contract. Other stored condition fields pass through this open logic schema. Preserve the returned condition representation rather than inventing another rule syntax.
Failure and deletion behavior
Unknown question, group, or offer references produce a 422 field error such as definition.child.0.segmentGroupId. Invalid node shapes, an HTTP webhook URL, an unknown embed app, or a disconnected app can instead produce 500 through the service exception path. The request's shallow array rules are not the complete schema.
Deleting a flow clears the flow reference from widgets that use it. It does not delete those widgets or their recorded analytics. Creating or updating a flow does not start a resource split test. All site behavior still depends on publishing the project.
Illustrative requests and responses
These illustrative examples use the fictional WorkForge project. The same resource schema covers every CRUD response.
The PATCH example also works with PUT. The create, item-read, and update envelopes have this shape. The list places these resource objects in its data array. An update returns the updated values. DELETE returns no JSON.