Node Delay & Timeout System

The Node Delay & Timeout System enables granular, node-level timing controls directly within the SMSPort Visual Bot Builder. It eliminates the need for sprawling standalone delay chains while providing robust response timeouts to recover dropped leads and safeguard WhatsApp 24-hour service level agreements.

Architectural Lifecycle

graph TD
    A["Node Activated"] --> B{"Pre-Execution Delay Configured?"}
    B -- "Yes (duration > 0)" --> C["Set status = waiting_for_delay
Persist waitingDelayUntil in DB
Enqueue BullMQ delayed job"]
    C --> D["Worker wakes up when delay expires"]
    D --> E["Advance execution into node"]
    B -- "No" --> E

    E --> F["Render & Send Node Content"]
    F --> G{"Is Ask Node Waiting for User?"}
    G -- "Yes" --> H{"Response Timeout Configured?"}
    H -- "Yes (duration > 0)" --> I["Generate atomic timeoutToken
Set waitingTimeoutUntil in DB
Enqueue BullMQ timeout resume job"]
    H -- "No" --> J["Wait indefinitely for user reply"]

    I --> K{"Inbound Reply Received in Time?"}
    K -- "Yes" --> L["Atomic token invalidation
(waitingTimeoutToken = null)
Continue normal flow"]
    K -- "No (Timer expires)" --> M{"Token matches DB state?"}
    M -- "Yes" --> N{"Execute Timeout Action"}
    N -- "goto_node" --> O["Branch to Fallback Node"]
    N -- "handoff" --> P["Escalate to Human Agent"]
    N -- "end" --> Q["Gracefully complete execution"]
    M -- "No (Cancelled)" --> R["Discard stale timeout cleanly"]

1. Node Delay ("Set Delay")

The pre-execution delay pauses the bot for a configured duration before executing the node. This introduces natural conversational pacing and prevents multiple consecutive messages from bursting instantly.

Supported Nodes

Node delay is universally supported on all visual canvas cards:

• Send Message Cards: send_text, send_media, send_template, send_whatsapp_flow, send_location
• Ask Question Cards: ask_text, ask_button, ask_list, ask_date, ask_phone, ask_email, ask_number, ask_location
• Logic & Integration Cards: condition, switch, data_lookup, google_sheets, http_request, persist_lead, notify_team

Configuration Schema

{
  "timing": {
    "delay": {
      "enabled": true,
      "duration": 2,
      "unit": "seconds",
      "typingIndicator": true
    }
  }
}

Parameters

Operational Behavior

• When execution reaches a delayed node, the engine transitions VisualBotExecutionStateEntity to status: 'waiting_for_delay'.
• A delayed job is enqueued in BullMQ (VISUAL_BOT_DELAY_RESUME_JOB).
• When the delay expires, the worker resumes execution cleanly without duplicate message delivery or hanging server threads.

2. Response Timeout ("Set Timeout")

The response timeout sets a maximum inactivity window while an Ask node is waiting for customer input. If the customer does not respond within this window, the bot automatically takes a predetermined action.

Supported Nodes

Response timeouts apply to all interactive user-input cards:

• ask_text, ask_number, ask_phone, ask_email, ask_date, ask_location
• ask_button (Quick Replies)
• ask_list (Interactive List Menus)

Configuration Schema

{
  "timing": {
    "timeout": {
      "enabled": true,
      "duration": 15,
      "unit": "minutes",
      "action": "goto_node",
      "fallbackNodeId": "node_human_handoff",
      "noticeMessage": "We haven't heard back from you, connecting you to an agent."
    }
  }
}

Parameters

Atomic Token Cancellation

To prevent race conditions where a customer replies at the exact moment a timeout triggers:

1. When entering waiting_for_input, a unique cryptographic token (waitingTimeoutToken) is generated and stored in the database state alongside waitingTimeoutUntil.
2. When the customer sends an inbound reply, continueExecutionFromInbound atomically clears waitingTimeoutToken = null.
3. If the timeout BullMQ job subsequently fires, the worker compares its token with the database state. Because the token is cleared, the worker discards the job as a safe no-op.

3. Fallback Actions

When a timeout expires without customer response, the bot executes one of three actions:

A. Branch to Node (`goto_node`)

Routes execution directly to a specified canvas node. Commonly used for:

• Sending a polite follow-up nudge ("Are you still there? Here's our catalogue link.").
• Directing the user to an alternate FAQ or support branch.

B. Handoff to Human (`handoff`)

Transfers the conversation directly to the live team queue in the SMSPort Inbox:

• Updates conversation handoffMode = 'human'.
• Releases bot control and notifies agents for proactive follow-up.

C. End Flow (`end`)

Completes bot execution cleanly without further automated messages:

• Marks VisualBotExecutionStateEntity as completed.
• Leaves the chat open for future customer-initiated triggers.

4. Master Starter Templates with Timing Presets

The following master templates in the SMSPort template library include production-ready timing presets:

5. Visual Property Inspector Usage

In the visual canvas:

1. Click any canvas node to open the right-side Node Property Inspector.
2. Scroll to the Set Delay section:
   • Toggle Enable Delay.
   • Click quick presets (1s, 2s, 5s, 10s, 30s, 1m) or type a custom duration.
   • Toggle Show WhatsApp Typing Indicator.
3. On Ask nodes, scroll to the Set Timeout & Fallback section:
   • Toggle Enable Inactivity Timeout.
   • Select quick presets (5m, 15m, 30m, 1h, 6h, 24h) or type a custom duration.
   • Choose the fallback action: Branch to Node, Handoff to Human, or End Flow.
   • When Branch to Node is selected, pick the target node from the dropdown list.