Daily Nudge System for Youth Entrepreneurs

This workflow automatically sends daily sales tracking reminders to youth entrepreneurs at 7PM and 8PM via WhatsApp and SMS. It intelligently chooses communication channels based on user preferences and recent activity, helping young business owners maintain consistent record-keeping habits for better profit tracking.

Purpose

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

How It Works

The workflow operates on two daily schedules (7PM and 8PM) with intelligent channel selection:

1. 7PM Initial Nudge: Triggers daily at 7PM, fetches active users from the database, and splits them into WhatsApp and SMS groups
2. Channel Intelligence: For WhatsApp users, checks if they've interacted within the last 24 hours
3. WhatsApp Strategy: If recent activity exists, sends a direct WhatsApp message; otherwise uses randomized WhatsApp templates
4. SMS Fallback: Non-WhatsApp users receive SMS via Africa's Talking with shortcode 24436
5. 8PM Follow-up: Second wave at 8PM for users who haven't responded, with similar channel logic
6. Activity Tracking: All nudges are logged to the database for tracking and analytics
7. Internal Team: Separate flow handles internal team members with customized messaging

The system maintains conversation history and adapts messaging based on user engagement patterns.

Workflow Diagram

graph TD
    A[7PM Trigger] --> B[Is Sunday?]
    B -->|No| C[Flag Evening Session Started]
    B -->|Yes| Z1[Stop]

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

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

    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? 7PM]
    K -->|Yes| L[ChatLog Within 24hrs? 7PM]
    K -->|No| M[Pick Random Template 7PM]

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

    M --> O[Send WhatsApp Template 7PM]
    N --> P[Save Nudge to DB 7PM WhatsApp]
    O --> 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 Trigger] --> BB[Is Sunday?]
    BB -->|No| CC[Fetch Active Users 8PM]
    BB -->|Yes| Z2[Stop]

    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? 8PM]
    II -->|Yes| JJ[Is WhatsApp User? 8PM]
    II -->|No| KK[Set SMS Nudge - Sales Question 8PM]

    JJ -->|Yes| LL[Fetch Last WhatsApp ChatLog 8PM]
    JJ -->|No| KK

    LL --> MM[Has WhatsApp ChatLog? 8PM]
    MM -->|Yes| NN[ChatLog Within 24hrs? 8PM]
    MM -->|No| OO[Pick Random Template 8PM]

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

    OO --> QQ[Send WhatsApp Template 8PM]
    PP --> RR[Save Nudge to DB 8PM WhatsApp]
    QQ --> SS[Save Nudge to DB 8PM WhatsApp Fallback]

    KK --> TT[Send SMS Shortcode 24436 8PM]
    TT --> UU[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)
• Manual Test Trigger: Manual trigger for testing individual user flows
• Sunday Check: Both triggers skip execution on Sundays (weekday = 7)

Nodes Used

Node Type	Count	Purpose
Schedule Trigger	2	Daily 7PM and 8PM automation triggers
Manual Trigger	1	Testing and manual execution
Postgres	15	Database operations for user data and chat history
HTTP Request	8	SMS sending via Africa's Talking API
Twilio	4	WhatsApp message sending
If	12	Conditional logic for channel selection and timing
Split in Batches	4	User processing loops
Set	4	Message content preparation
Code	3	Random WhatsApp template selection
Filter	1	Recent chat activity filtering
Aggregate	1	Chat data consolidation
Remove Duplicates	3	User deduplication
No Op	1	Data passthrough

External Services & Credentials Required

Africa's Talking SMS API

• Credential Type: HTTP Header Auth
• Required: API Key for toll_free_sms_ke username
• Shortcodes: 24436 (primary), "Educate" (longcode)

Twilio WhatsApp API

• Credential Type: API credentials
• Required: Account SID, Auth Token
• Phone Number: +254203892316
• Templates: 16 pre-approved WhatsApp message templates

PostgreSQL Database

• Credential Type: Database connection
• Required: Host, database name, username, password
• Tables: youthEntrepreneursReal, youthProgressReport, n8n_chat_histories, chatLog

Environment Variables

No explicit environment variables are defined in this workflow. All configuration is handled through n8n credentials and node parameters.

Data Flow

Input Data

• User Records: Phone numbers, names, onboarding status from youthEntrepreneursReal table
• Progress Data: Onboarding dates and status from youthProgressReport table
• Chat History: Recent interactions from n8n_chat_histories and chatLog tables

Output Data

• SMS Messages: Sales tracking questions sent via Africa's Talking
• WhatsApp Messages: Direct messages or template-based nudges via Twilio
• Database Logs: All nudges recorded in n8n_chat_histories with metadata
• Activity Flags: Evening session status updates

Data Transformations

• User deduplication by phone number
• Chat history filtering (last 60 minutes, non-AI messages)
• Random template selection from 16 WhatsApp templates
• Message personalization with user first names

Error Handling

The workflow implements comprehensive error handling:

• Continue on Error: Critical nodes are configured to continue processing other users if one fails
• Always Output Data: Database and API nodes maintain data flow even on errors
• Error Workflow: Global error workflow (cuHEGQjAfvuGwIOD) handles unrecoverable failures
• Fallback Channels: WhatsApp failures fall back to SMS delivery
• Batch Processing: User loops prevent single user failures from stopping the entire process

Known Limitations

• Sunday execution is disabled (business rule)
• WhatsApp template messages require pre-approval from Meta
• SMS delivery depends on Africa's Talking service availability
• Database connection failures can halt the entire workflow
• No retry mechanism for failed message deliveries

Related Workflows

• Error Workflow: cuHEGQjAfvuGwIOD (handles unrecoverable errors)

Setup Instructions

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

2. Configure Database Credentials:

   • Create PostgreSQL credential named "Postgres account"
   • Ensure access to tables: youthEntrepreneursReal, youthProgressReport, n8n_chat_histories, chatLog

3. Set Up Africa's Talking:

   • Create HTTP Header Auth credential named "Africa's Talking api"
   • Add API key for toll_free_sms_ke account
   • Verify shortcode 24436 access

4. Configure Twilio WhatsApp:

   • Create Twilio API credential named "Twilio account"
   • Set up WhatsApp Business number +254203892316
   • Submit and approve 16 WhatsApp message templates

5. Set Timezone:

   • Ensure workflow timezone is set to "Africa/Nairobi"
   • Verify schedule triggers are set for 7PM and 8PM

6. Test Setup:

   • Use Manual Test Trigger to verify database connections
   • Test both SMS and WhatsApp delivery paths
   • Confirm error handling with invalid phone numbers

7. Activate Workflow:

   • Enable the workflow to start daily automated execution
   • Monitor initial runs for any configuration issues