Skip to content

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. It intelligently routes messages through WhatsApp or SMS based on user preferences and recent activity, helping maintain engagement with the SIFA coaching system.

Purpose

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

Based on the workflow structure, this system appears to serve youth entrepreneurs in a business coaching program by: - Sending daily reminders to track sales and profit data - Maintaining engagement through personalized messages in Swahili - Routing communications through preferred channels (WhatsApp vs SMS) - Supporting both regular users and internal team members - Preventing message fatigue by checking recent activity before sending nudges

How It Works

The workflow operates on two daily schedules (7PM and 8PM) and follows this logic:

  1. Schedule Check: Triggers fire at 7PM and 8PM daily, but skip Sundays to avoid weekend interruptions
  2. User Segmentation: Fetches active users from the database, excluding new users who haven't completed onboarding
  3. Channel Detection: Determines whether each user prefers WhatsApp or SMS communication
  4. Activity Analysis: For WhatsApp users, checks if they've had recent conversations (within 24 hours) to avoid over-messaging
  5. Message Routing:
    • WhatsApp users with recent activity get WhatsApp messages asking about daily sales
    • WhatsApp users without recent activity get SMS fallback messages with WhatsApp links
    • SMS-only users get direct SMS messages asking about sales figures
  6. Message Logging: All sent messages are saved to the chat history database for tracking
  7. Batch Processing: Users are processed in batches to manage system load

The system also handles internal team members separately with similar logic but different user queries.

Workflow Diagram

graph TD
    A[7PM Nudge Trigger] --> B{Is Sunday?}
    C[8PM Nudge Trigger] --> D{Is Sunday?}

    B -->|No| E[Flag Evening Session Started]
    D -->|No| F[Fetch Active Users 8PM]

    E --> G[Fetch Active Users 7PM]
    E --> H[Fetch Internal Team Users]

    G --> I[Dedup Users 7PM]
    H --> J[Dedup Users Internal]
    F --> K[Dedup Users 8PM]

    I --> L{Is WhatsApp User? 7PM}
    J --> M{Is WhatsApp User? Internal}
    K --> N[Loop Users 8PM]

    L -->|Yes| O[Loop WhatsApp Users 7PM]
    L -->|No| P[Loop SMS Users 7PM]

    M -->|Yes| Q[Loop WhatsApp Users Internal]
    M -->|No| R[Loop SMS Users Internal]

    N --> S[Fetch Chat History 8PM]
    S --> T{Has Recent Chat Data?}

    T -->|No| U{Is WhatsApp User? 8PM}
    U -->|Yes| V[Check WhatsApp Activity]
    U -->|No| W[Send SMS Nudge]

    O --> X[Check WhatsApp ChatLog 7PM]
    P --> Y[Send SMS 7PM]
    Q --> Z[Check WhatsApp ChatLog Internal]
    R --> AA[Send SMS Internal]

    V --> BB{Recent WhatsApp Activity?}
    BB -->|Yes| CC[Send WhatsApp Message]
    BB -->|No| DD[Send SMS Fallback]

    X --> EE{Recent Activity?}
    EE -->|Yes| FF[Send WhatsApp 7PM]
    EE -->|No| GG[Send SMS Fallback 7PM]

    CC --> HH[Save to Database]
    DD --> II[Save to Database]
    Y --> JJ[Save to Database]
    FF --> KK[Save to Database]

Trigger

  • Schedule Trigger (7PM): Fires daily at 19:00 (7PM) local time
  • Schedule Trigger (8PM): Fires daily at 20:00 (8PM) local time
  • Sunday Skip Logic: Both triggers check if it's Sunday (weekday = 7) and skip execution to avoid weekend interruptions

Nodes Used

Node Type Purpose Count
Schedule Trigger Initiates workflow at 7PM and 8PM daily 2
Postgres Database queries for users, chat logs, and message storage 15
If/Filter Conditional logic for user routing and activity checks 12
Split in Batches Process users in manageable batches 5
Set Create message content with personalized greetings 6
HTTP Request Send SMS messages via Africa's Talking API 6
Twilio Send WhatsApp messages 3
Remove Duplicates Ensure unique users in each batch 3
Aggregate Combine chat history data for analysis 1
No Operation Pass-through node for data flow 1

External Services & Credentials Required

Required Credentials

  • Postgres Database: Two separate database connections
    • sifaV4Dev - for chat history operations
    • Postgres account 2 - for user and progress data
  • Twilio: For WhatsApp message delivery
    • Account SID and Auth Token required
    • Configured sender number: +254203892316
  • Africa's Talking SMS API: For SMS delivery
    • API Key: atsk_ae3de07489f045ef1532a7e407df689bcadff2dbc2555361f3055c6774d779c77c5d9954
    • Username: toll_free_sms_ke
    • Sender IDs: 24436, Educate

External Services

  • Africa's Talking: SMS delivery service (api.africastalking.com)
  • Twilio: WhatsApp Business API integration
  • PostgreSQL: Database for user data and message logging

Environment Variables

No explicit environment variables are defined in this workflow. All configuration is handled through: - Hardcoded API keys in HTTP request nodes - Database connection credentials stored in n8n credential system - Static phone numbers and sender IDs in message nodes

Data Flow

Input Data

  • User Records: Retrieved from youthEntrepreneursReal and youthProgressReport tables
  • Chat History: Recent conversation data from n8n_chat_histories and chatLog tables
  • Time Context: Current time and weekday for scheduling logic

Processing

  • User segmentation by communication preference (WhatsApp vs SMS)
  • Activity analysis to prevent message fatigue
  • Message personalization using user's first name
  • Batch processing for system performance

Output Data

  • WhatsApp Messages: Personalized sales tracking requests
  • SMS Messages: Sales questions or WhatsApp redirect links
  • Database Records: All sent messages logged to n8n_chat_histories table
  • API Responses: Delivery confirmations from messaging services

Error Handling

The workflow includes several error handling mechanisms:

  • Continue on Error: Most SMS and WhatsApp sending nodes are configured to continue execution even if message delivery fails
  • Always Output Data: Database save operations continue processing even if individual saves fail
  • Fallback Messaging: If WhatsApp delivery fails, users receive SMS fallbacks
  • Graceful Degradation: Missing chat history or user data doesn't stop the entire workflow

Error paths ensure that: - Failed message deliveries don't block other users from receiving nudges - Database connection issues don't crash the entire workflow - Missing user data is handled gracefully with default behaviors

Known Limitations

Based on the workflow structure, potential limitations include:

  • Hardcoded API Keys: Security risk with API keys embedded in workflow nodes
  • Time Zone Dependency: Scheduling assumes specific timezone (Africa/Nairobi)
  • Language Limitation: Messages are only in Swahili, limiting international use
  • Manual User Segmentation: WhatsApp vs SMS preference appears to be manually managed
  • No Delivery Confirmation: Limited tracking of actual message delivery success
  • Weekend Gaps: Complete skip of Sunday may miss users who work weekends

No related workflows are explicitly referenced in the current workflow structure. This appears to be a standalone nudging system that integrates with: - User onboarding workflows (referenced by onboardingStatus checks) - Chat/conversation systems (integrates with existing chat history) - Progress tracking systems (uses youthProgressReport data)

Setup Instructions

1. Import Workflow

  1. Copy the workflow JSON into n8n
  2. Save the workflow with name: checkWhatNudgeChannel2UseAndSendNudge

2. Configure Database Connections

  1. Set up PostgreSQL credentials:
    • Create sifaV4Dev credential for chat history database
    • Create Postgres account 2 credential for user data database
  2. Ensure database tables exist:
    • youthEntrepreneursReal (user profiles)
    • youthProgressReport (onboarding status)
    • n8n_chat_histories (message logging)
    • chatLog (WhatsApp activity tracking)

3. Configure External Services

  1. Twilio Setup:
    • Create Twilio credential with Account SID and Auth Token
    • Verify WhatsApp Business number: +254203892316
  2. Africa's Talking Setup:
    • Obtain API key and update in HTTP request nodes
    • Verify SMS sender IDs: 24436 and Educate

4. Customize Messages

  1. Update message templates in Set nodes to match your brand voice
  2. Modify phone numbers and sender IDs as needed
  3. Adjust timezone in schedule triggers if not using Africa/Nairobi

5. Test and Deploy

  1. Test with internal team users first
  2. Verify database logging is working correctly
  3. Check message delivery across both WhatsApp and SMS channels
  4. Activate the workflow to begin daily execution

6. Monitor and Maintain

  1. Regularly check error logs for failed deliveries
  2. Monitor database growth in n8n_chat_histories table
  3. Update API keys before expiration
  4. Review message effectiveness and adjust content as needed