Delays and waits

Timing decides more of a flow's results than its copy does. A reminder that lands at 3 a.m. annoys; one that lands the instant a checkout starts looks like surveillance; one that lands days late misses the moment. Five nodes control when things happen: three wait for a time, two wait for something to happen.

Every wait counts towards the limit on a flow's longest path: the waits along any path may add up to at most 180 days, and validation reports a flow that exceeds it.

Which one to use

• Before a marketing message, a smart delay. Including before the first one: it waits at least its minimum, picks each contact's best moment, and with legalHours never lands at an hour when marketing is not allowed.
• For an exact gap, a fixed delay. Two messages ten minutes apart, for example. It does not look at the clock, so do not put one directly before a marketing send.
• For a wait longer than 14 days, a fixed delay followed by a smart delay. A winback that waits 30 days after the last order uses a 30-day fixed delay, then a smart delay to pick the moment.
• Only a message that confirms what the contact just did — an order confirmation — goes out with no delay at all.

Fixed delay

ACTION_SEQUENTIAL_DELAY counts down from the moment the contact reaches it, then continues on nextStep. No time zone, no allowed hours, no paths.

Window delay

ACTION_BRANCH_TIMEZONE_DELAY waits for the first allowed moment in the contact's local time zone, inside a window.

Allowed hours and days are the brand's own courtesy calendar. The platform adds no legal restriction here; that is the smart delay's legalHours.

Smart delay

ACTION_BRANCH_SMART_DELAY has the same window, allowed hours and days, and the same two paths as the window delay. Instead of taking the first allowed moment, it scores every allowed moment and waits for the best one for that contact. Configure it by name, and always send all three names:

{
  "stepClass": "ACTION_BRANCH_SMART_DELAY",
  "minDelaySeconds": 1800,
  "maxDelaySeconds": 28800,
  "preset": "purchase",
  "urgency": "soon",
  "legalHours": true,
  "paths": [
    { "outcome": "waitComplete", "nextStep": { "stepClass": "ACTION_SEQUENTIAL_SEND", "...": "..." } },
    { "outcome": "cannotSatisfy" }
  ]
}

Put the send inside the waitComplete path. cannotSatisfy means no allowed — or legal — moment fitted the window, so nothing should send there. A send placed after the two paths rejoin goes out anyway, at a possibly illegal hour. A narrow window with tight hours or days sends more contacts to cannotSatisfy; widen maxDelaySeconds rather than drop the hours the brand asked for.

What happens when a name is missing:

• No preset (and no hand-written signals): the node is saved with nothing to rank by and no legal filter. Nothing fills it in for you.
• No urgency: a balanced default applies.
• legalHours absent or null: on, with any named preset.
• A name wins over hand-written values. With preset set, the signals are rebuilt from it on every save; with urgency set, a raw urgency value is ignored. To change the behaviour, change the name.

Legal hours

legalHours removes the moments at which sending marketing is not allowed in the contact's country. It acts only where a country restricts marketing hours or days; elsewhere, and when the contact's country cannot be determined, every moment passes. It does not replace the brand's allowedHours, and it applies to marketing only: a transactional message is not held back by it.

Waiting for an event

ACTION_BRANCH_CONTACT_EVENT_WAIT pauses until the contact does something, and branches by what they did first.

Matchers, by their by field:

• Put catch-all matchers last. A path with anyClick, anyTap or anyInboundText must come after every path with a specific matcher, or it would take their contacts.
• Click, tap, token and reply matchers listen to the message the flow just sent. Without a send before the node on that path, they can only time out.
• For "they left", use kind: any. A contact already suppressed who unsubscribes again arrives only as suppression.

Waiting for delivery

ACTION_BRANCH_MESSAGE_DELIVERY_WAIT binds itself to the send just before it and branches on its result. There is no timeout to configure: a fixed platform window applies, and a message with no result by then goes to notDelivered. An interaction with the message proves delivery early.

An optional unableToSend path is taken at once when the send was never attempted — no phone, no consent, a blocked number. Without it, those contacts go to notDelivered, mixed with real delivery failures.

With no send before it, delivered can never be reached: every contact goes straight to unableToSend or notDelivered.

What's next