Skip to content

Credit Path — Nudge Dispatcher (Cron)

This workflow automatically sends contextual WhatsApp reminders to young entrepreneurs about following up with their debtors. Running every 30 minutes, it identifies scheduled nudges that are due, generates culturally appropriate messages in Sheng based on debtor relationships and payment history, and delivers them via WhatsApp to help youth manage their credit collection efforts.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

How It Works

  1. Schedule Check: Every 30 minutes, the workflow queries the database for nudges that are scheduled to fire
  2. Filter Due Nudges: Identifies nudges where the scheduled time has passed and haven't been fired yet
  3. Process Each Nudge: For each due nudge, the workflow:
    • Generates a contextual message based on the debtor relationship and payment outcome
    • Activates the debtor conversation in the system
    • Sends the WhatsApp message to the youth entrepreneur
    • Marks the nudge as fired to prevent duplicates
  4. Loop Continuation: Processes all due nudges in batches before completing

The workflow handles different nudge types including day-before reminders, refusal re-engagement, forgotten payment follow-ups, and same-day check-ins, with messages tailored to relationship types (friend, family, stranger, regular customer).

Workflow Diagram

graph TD
    A[Cron Every 30m] --> B[Find Due Nudges]
    B --> C{Has Due Nudges?}
    C -->|Yes| D[Loop Over Nudges]
    C -->|No| E[End]
    D --> F[Build Nudge Message]
    F --> G[Activate This Debtor]
    G --> H[Send WhatsApp Nudge]
    H --> I[Mark Followup Fired]
    I --> D
    D -->|Complete| E

Trigger

Schedule Trigger: Runs automatically every 30 minutes using a cron expression (*/30 * * * *)

Nodes Used

Node Type Node Name Purpose
Schedule Trigger Cron Every 30m Triggers workflow every 30 minutes
PostgreSQL Find Due Nudges Queries database for nudges ready to be sent
If Has Due Nudges? Checks if any nudges were found
Split in Batches Loop Over Nudges Processes each nudge individually
Code Build Nudge Message Generates contextual Sheng messages based on relationship and outcome
PostgreSQL Activate This Debtor Updates debtor status and conversation state
Twilio Send WhatsApp Nudge Delivers the message via WhatsApp
PostgreSQL Mark Followup Fired Prevents duplicate nudges by marking as sent

External Services & Credentials Required

PostgreSQL Database

  • Credential: sifaV4Dev
  • Purpose: Stores youth entrepreneur data, debtor information, and nudge scheduling
  • Tables Used: v4_creditpathHistory, v4_creditpathFollowup, v4_youthEntrepreneurs

Twilio WhatsApp API

  • Credential: Twilio account 3
  • Purpose: Sends WhatsApp messages to youth entrepreneurs
  • From Number: +12402623539

Environment Variables

No environment variables are explicitly used in this workflow. All configuration is handled through n8n credentials and hardcoded values.

Data Flow

Input

  • Database records from scheduled nudges query including:
    • Youth entrepreneur phone number and first name
    • Debtor name, amount, and relationship type
    • Payment outcome and current balance
    • Schedule signal type and timing

Output

  • WhatsApp messages sent to youth entrepreneurs
  • Database updates marking nudges as fired
  • Debtor conversation state changes

Key Data Transformations

  • Phone number formatting for WhatsApp delivery
  • Currency formatting for Kenyan Shillings (KES)
  • Relationship-based message generation in Sheng
  • Outcome-specific nudge timing and content

Error Handling

The workflow includes basic error handling through: - Conditional checks to ensure nudges exist before processing - Database constraints preventing duplicate nudge firing - Defensive message generation with fallback text for unknown scenarios

No explicit error nodes or retry mechanisms are implemented in the current workflow.

Known Limitations

Based on the workflow implementation: - Limited to 50 nudges per execution cycle - No retry mechanism for failed WhatsApp deliveries - Hardcoded Twilio phone number limits portability - No validation of phone number formats before sending - Messages are only in Sheng/Swahili language

No related workflows are mentioned in the available context.

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance

  2. Configure Database Credential:

    • Create PostgreSQL credential named sifaV4Dev
    • Configure connection to database containing the required tables

  3. Configure Twilio Credential:

    • Create Twilio API credential named Twilio account 3
    • Ensure WhatsApp sandbox is configured or production WhatsApp Business API is enabled

  4. Verify Database Schema:

    • Ensure tables exist: v4_creditpathHistory, v4_creditpathFollowup, v4_youthEntrepreneurs
    • Verify required columns match the SQL queries in the workflow

  5. Test Execution:

    • Run manually to verify database connections
    • Check that WhatsApp messages are delivered successfully
    • Confirm nudges are marked as fired after execution

  6. Activate Workflow: Enable the workflow to start automatic execution every 30 minutes

  7. Monitor Performance: Watch execution logs to ensure the 30-minute interval handles the expected volume of nudges without timeout issues