Daily Nudge System for Youth Entrepreneurs

This workflow sends automated daily nudges to youth entrepreneurs at 7PM and 8PM to encourage them to track their business sales and profits. The system intelligently routes messages through WhatsApp or SMS based on user preferences and recent activity, helping maintain engagement with the SIFA coaching program.

Purpose

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

Based on the workflow implementation, this system appears to serve youth entrepreneurs in a business coaching program by: - Sending daily reminders to track sales and calculate profits - Maintaining engagement through personalized messages in Swahili - Providing flexible communication channels (WhatsApp and SMS) - Supporting business tracking and accountability

How It Works

The workflow operates on two daily schedules with intelligent message routing:

7PM Flow: 1. Checks if it's Sunday (skips execution if true) 2. Flags evening session as started in the database 3. Fetches active users and internal team members separately 4. For each user group, determines their preferred communication channel 5. WhatsApp users: Checks recent chat activity, sends WhatsApp message if active within 24 hours, falls back to SMS if not 6. SMS users: Sends direct SMS messages 7. Logs all nudges to the chat history database

8PM Flow: 1. Checks if it's Sunday (skips execution if true) 2. Fetches active users who haven't had recent chat activity 3. Analyzes recent chat history (last 60 minutes) to avoid duplicate nudges 4. Routes users without recent activity through the same channel logic as 7PM 5. Sends more urgent "reminder" messages since it's the second attempt

The system uses different message templates and sender IDs based on timing and channel, with comprehensive error handling to ensure the workflow continues even if individual messages fail.

Workflow Diagram

graph TD
    A[7PM Nudge Trigger] --> B{Is Sunday?}
    B -->|No| C[Flag Evening Session Started]
    B -->|Yes| END1[Skip Execution]

    C --> D[Fetch Active Users 7PM]
    C --> E[Fetch Internal Team Users]

    D --> F[Dedup Users 7PM]
    F --> G{Is WhatsApp User?}

    G -->|Yes| H[Loop WhatsApp Users 7PM]
    G -->|No| I[Loop SMS Users 7PM]

    H --> J[Fetch Last WhatsApp ChatLog 7PM]
    J --> K{Has WhatsApp ChatLog?}
    K -->|Yes| L{ChatLog Within 24hrs?}
    K -->|No| M[Set SMS Nudge - Profit Question 7PM]

    L -->|Yes| N[Send WhatsApp Nudge 7PM]
    L -->|No| M

    N --> O[Save Nudge to DB 7PM WhatsApp]
    M --> P[Send SMS Educate Sender 7PM Fallback]
    P --> Q[Save Nudge to DB 7PM WhatsApp Fallback]

    I --> R[Set SMS Nudge - Sales Question 7PM]
    R --> S[Send SMS Educate Sender 7PM SMS]
    S --> T[Save Nudge to DB 7PM SMS]

    E --> U[Dedup Users Internal]
    U --> V{Is WhatsApp User? Internal}
    V -->|Yes| W[Loop WhatsApp Users Internal]
    V -->|No| X[Loop SMS Users Internal]

    AA[8PM Nudge Trigger] --> BB{Is Sunday?}
    BB -->|No| CC[Fetch Active Users 8PM]
    BB -->|Yes| END2[Skip Execution]

    CC --> DD[Dedup Users 8PM]
    DD --> EE[Loop Users 8PM]
    EE --> FF[Fetch Chat History 8PM]
    FF --> GG[Filter Recent Chats 8PM]
    GG --> HH[Aggregate Chat Data 8PM]
    HH --> II{Has Chat Data?}

    II -->|No| JJ{Is WhatsApp User? 8PM}
    II -->|Yes| KK[Continue Loop]

    JJ -->|Yes| LL[Fetch Last WhatsApp ChatLog 8PM]
    JJ -->|No| MM[Set SMS Nudge - Sales Question 8PM]

    LL --> NN{Has WhatsApp ChatLog? 8PM}
    NN -->|Yes| OO{ChatLog Within 24hrs? 8PM}
    NN -->|No| PP[Set SMS Nudge - Profit Question 8PM]

    OO -->|Yes| QQ[Send WhatsApp Nudge 8PM]
    OO -->|No| PP

    QQ --> RR[Save Nudge to DB 8PM WhatsApp]
    PP --> SS[Send SMS Educate Sender 8PM]
    SS --> TT[Save Nudge to DB 8PM SMS Fallback]

    MM --> UU[Send SMS Shortcode 24436 8PM]
    UU --> VV[Save Nudge to DB 8PM SMS]

Trigger

• 7PM Nudge Trigger: Schedule Trigger that fires daily at 7:00 PM (Africa/Nairobi timezone)
• 8PM Nudge Trigger: Schedule Trigger that fires daily at 8:00 PM (Africa/Nairobi timezone)

Both triggers skip execution on Sundays using conditional logic.

Nodes Used

Node Type	Count	Purpose
Schedule Trigger	2	Daily execution at 7PM and 8PM
Postgres	15	Database queries for user data and chat history logging
If (Conditional)	12	Decision logic for routing and filtering
Set	6	Message template creation
Split in Batches	6	User processing loops
HTTP Request	6	SMS sending via Africa's Talking API
Twilio	3	WhatsApp message sending
Remove Duplicates	3	User deduplication
Filter	1	Recent chat filtering
Aggregate	1	Chat data consolidation
No Operation	1	Data passthrough

External Services & Credentials Required

Postgres Database: - Credential ID: EJPqF6MDH1ZwAzyv - Tables: youthEntrepreneursReal, youthProgressReport, n8n_chat_histories, chatLog

Twilio API: - Credential ID: dEOy4AckE29MTkk3 - Used for WhatsApp messaging via +254203892316

Africa's Talking SMS API: - API Key: atsk_ae3de07489f045ef1532a7e407df689bcadff2dbc2555361f3055c6774d779c77c5d9954 - Username: toll_free_sms_ke - Sender IDs: 24436, Educate

Environment Variables

No explicit environment variables are used. All configuration is embedded in node parameters, though this should be refactored to use environment variables for: - Database connection details - API keys and credentials - Sender phone numbers and IDs

Data Flow

Input: - User data from youthEntrepreneursReal and youthProgressReport tables - Chat history from n8n_chat_histories and chatLog tables - Current time and date for scheduling logic

Processing: - Filters active users (onboarding status != 'new') - Deduplicates users by phone number - Analyzes recent communication patterns - Routes messages based on user preferences and activity

Output: - WhatsApp messages via Twilio - SMS messages via Africa's Talking - Chat history records in database - Updated user session flags

Error Handling

The workflow implements comprehensive error handling:

• Continue on Error: Most critical nodes are configured to continue execution even if individual operations fail
• Always Output Data: Database operations use alwaysOutputData: true to prevent workflow interruption
• Fallback Messaging: WhatsApp failures automatically fall back to SMS delivery
• Batch Processing: User loops continue processing remaining users even if individual messages fail
• Query Parameterization: Database queries use parameterized inputs to handle special characters (like apostrophes in names)

Known Limitations

Based on the workflow implementation:

• Hard-coded API keys should be moved to environment variables
• Sunday execution is completely skipped (no weekend engagement)
• Internal team users are processed separately but with similar logic (potential code duplication)
• Chat history analysis limited to last 5 records for performance
• No retry mechanism for failed API calls
• Message templates are embedded in nodes rather than externalized

Related Workflows

No related workflows are explicitly referenced in the current implementation.

Setup Instructions

1. Import the Workflow:

   • Copy the workflow JSON into n8n
   • Set timezone to Africa/Nairobi

2. Configure Database Credentials:

   • Create Postgres credential with ID EJPqF6MDH1ZwAzyv
   • Ensure access to required tables: youthEntrepreneursReal, youthProgressReport, n8n_chat_histories, chatLog

3. Setup Twilio Integration:

   • Create Twilio credential with ID dEOy4AckE29MTkk3
   • Configure WhatsApp sandbox or production number: +254203892316

4. Configure Africa's Talking SMS:

   • Update API key in HTTP Request nodes
   • Verify sender IDs (24436, Educate) are approved
   • Test SMS delivery to Kenya numbers

5. Database Schema Requirements:

   -- Ensure these columns exist:
   -- youthEntrepreneursReal: phoneNumber, firstName, channel, eveningSessionStarted
   -- youthProgressReport: phoneNumber, onboardingStatus, onboardedAt
   -- n8n_chat_histories: session_id, message, created_time
   -- chatLog: userPhone, channel, created_at
   

6. Test Execution:

   • Run manually with test data
   • Verify message delivery on both channels
   • Check database logging functionality
   • Validate Sunday skip logic

7. Activate Workflow:

   • Enable both schedule triggers
   • Monitor execution logs for errors
   • Set up alerting for failed executions