How a flow works

A flow decides what happens to a lead. It is a document with two lists:

• Steps (nodes). Each has a type, such as If / else or Show calendar, and its own settings.
• Links (edges). Each joins one exit of a step to the next step.

A person draws the flow on a canvas in the app. An agent writes the same document through its tools. There is one shape for both.

The draft and the live version

A flow has a draft. Once published, it also has a live version.

• Leads always run a published version. Editing the draft changes nothing a visitor sees.
• Publishing turns the draft into a new numbered version. Old versions never change.
• A lead keeps the version it started on, even if you publish again while it waits.
• A saved draft names the revision it started from. If someone else saved since, the save is refused, so one person cannot overwrite another’s work unseen.

Only an admin can publish, pause or delete a flow.

The trigger

Every flow starts with one trigger. It says what starts the flow.

The flow starts when	What to know
A HubSpot form is submitted	The usual case. The visitor is on the page and can be shown a calendar, questions or a message.
Another system posts to the flow’s address	Post a JSON object with an email field. Its other top-level values become fields, as form.<name>. Anyone who has the address can start the flow, so keep it private.
A HubSpot contact is created or changed	Contacts only. The flow starts at most once a minute for one contact, and never for a change Signalbox made.
A meeting Signalbox booked has an outcome	Held, a no-show, cancelled or rescheduled. Signalbox reads the outcome from HubSpot once an hour, for two weeks after the meeting.

Nobody is on a page when a flow starts from anything but a form. A step that shows the visitor something is passed over, and the checker warns you of each one. Such a flow cannot be given to a form.

The two automatic steps

Two steps follow the trigger in every flow, in this order. You cannot remove or move them.

1. Clean and enrich cleans the email address and looks the company up in Sopro Data. It adds the clean.* and sopro.* fields.
2. HubSpot lookup checks HubSpot for the contact, the company and its deals. It adds the hs.contact.*, hs.company.* and hs.deals.* fields.

So every step you add can already read who the lead is and what HubSpot holds.

Steps

You add steps after the automatic two. The app groups them as below.

Group	Steps
Logic	If / else, Branch, Split test, Wait, Wait until, End
Data	Score, Lookup table, Set value, AI classify
HubSpot	Update record, Create deal, Create record, Create task, Enrol in HubSpot
Routing	Assign from queue, Assign to existing owner, Assign to a person, Reassign
Lead sees	Show calendar, Ask questions, Show message, Redirect, Email the lead
Tell the team	Slack message, Email the team, Send webhook

The Step reference group in this section has a page for each step, with its settings and exits. It is made from the code. An agent reads the same reference with list_node_types and get_node_type.

Exits

A step hands the lead on through an exit. Most steps have one exit, Next. Some have several:

Step	Exits
If / else	Yes, No
Branch	One for each branch you add, then Else
Split test	A, B
Wait until	Happened, Timed out
Lookup table	Found, Not in table
Assign to existing owner	Owner, None, Away
Show calendar	Booked, Not booked, Cancelled
Ask questions	Answered, Left

End has no exit: the flow stops there.

The rules for links:

• A step with more than one exit must have every exit linked. The one exception is Cancelled on Show calendar, which may be left unlinked.
• An exit has one link.
• Every step must be reachable from the trigger.
• A flow cannot loop back on itself. A lead only moves forward.

Steps that wait

Some steps stop and wait: Show calendar and Ask questions wait for the visitor, and Wait and Wait until wait for a time or an event. When a wait’s limit passes, the lead takes the exit for that, such as Not booked, Left or Timed out.

What the visitor waits for

The visitor is on the page while the first steps run. Signalbox gives that part three seconds. After the first step that shows the visitor something, or when the time runs out, the rest of the flow runs in the background.

AI classify and Send webhook are slow. Put them after the step that shows the visitor something. The checker warns when one comes before it.

Fields in braces

Many settings take text. That text can hold a field in double braces, which is filled in for each lead:

Thanks {{form.firstname}}, {{flow.rep_name}} will be in touch.

A field that is not there becomes nothing. See Fields for the full list.

IDs, not names

A setting that points at something holds its ID, never its name. That covers a queue, a rep, a meeting type, a HubSpot pipeline and stage, and a HubSpot workflow. The app fills these in from lists. An agent looks each ID up first, with tools such as list_queues, list_reps, list_meeting_types and list_hubspot. It must never invent one.

The checker

The checker reads a draft and lists what is wrong, each issue with the step it belongs to. In the app it is the Issues list. An agent calls check_flow.

An issue is one of two kinds:

• An error blocks publish. Examples: an exit that leads nowhere, a step that cannot be reached, a calendar a lead can reach with no rep assigned, a step that uses the deal before any Create deal.
• A warning does not. Examples: a slow step before the visitor is shown something, two Create deal steps on one path, a step that shows the visitor something in a flow that does not start from a form.

Dry run

A dry run runs the draft on a sample lead. You give it an email address. The company look-up and the HubSpot check are real. Nothing is written, nobody is assigned and nothing is booked. In the app the path the lead takes is drawn in green. An agent calls dry_run_flow.

Use it to see that each kind of lead goes down the branch you meant.

Versions

Every publish makes a version. History in the app lists them all, and can copy an old one back into the draft. An agent uses list_flow_versions and restore_flow_version.

Restoring changes the draft only. Nothing a visitor sees changes until you publish again.