Skip to content

Daily Nudge System for Youth Entrepreneurs

This workflow sends automated daily nudges to youth entrepreneurs participating in a business tracking program, encouraging them to report their daily sales figures. It intelligently routes messages through either WhatsApp or SMS based on user preferences and interaction history, ensuring maximum engagement across different communication channels.

Purpose

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

How It Works

The workflow operates on two main schedules and includes a manual trigger for testing:

  1. 7PM Daily Trigger: Activates the evening session by marking users as ready for nudges, then sends personalized messages asking about daily sales
  2. 8PM Daily Trigger: Sends follow-up nudges to users who haven't responded recently
  3. Manual Testing: Allows administrators to test the nudge system on users who aren't fully onboarded

For each user, the system: - Retrieves active youth entrepreneurs from the database - Checks their communication channel preference (WhatsApp vs SMS) - For WhatsApp users: Verifies recent interaction history to avoid spam - Sends appropriate nudge messages in Swahili asking about daily sales - Logs all sent messages to the chat history database - Processes users in batches to manage system load

The workflow includes intelligent filtering to prevent over-messaging users who have interacted recently (within 24 hours) and routes messages through the most effective channel for each individual.

Workflow Diagram

graph TD
    A[7PM Nudge] --> B[setEveningSessionStarted]
    B --> C[getUserRecord10]
    C --> D[Remove Duplicates1]
    D --> E[If1 - Check Channel]

    E -->|WhatsApp| F[Loop Over Items4]
    E -->|SMS| G[Loop Over Items3]

    F --> H[Execute a SQL query1]
    H --> I[checkIfWeFindAChatlogRecord1]
    I -->|Found| J[ifLessThen24hrsPassed1]
    I -->|Not Found| K[setNudgeMessage3]

    J -->|Recent| L[Send WhatsApp response via Twilio2]
    J -->|Old| K
    K --> M[Send SMS via Africa's Talking4]

    L --> N[getUserRecord9]
    M --> O[getUserRecord8]

    P[8PM Nudge] --> Q[getUserRecord7]
    Q --> R[Remove Duplicates]
    R --> S[Loop Over Items]

    S --> T[Get Chat History]
    T --> U[getChatHistory]
    U --> V[Filter]
    V --> W[Aggregate]
    W --> X[data - Check Empty]

    X -->|Empty| Y[If - Check Channel]
    X -->|Has Data| S

    Y -->|WhatsApp| Z[Execute a SQL query]
    Y -->|SMS| AA[setNudgeMessage]

    Z --> BB[checkIfWeFindAChatlogRecord]
    BB --> CC[ifLessThen24hrsPassed]
    CC --> DD[Send WhatsApp response via Twilio1]

    AA --> EE[Send SMS via Africa's Talking]

    FF[Manual Trigger] --> GG[getUserRecord6]
    GG --> HH[Execute a SQL query2]
    HH --> II[Insert rows in a table]

Triggers

  • 7PM Nudge: Schedule trigger that fires daily at 7:00 PM (Africa/Nairobi timezone)
  • 8PM Nudge: Schedule trigger that fires daily at 8:00 PM (Africa/Nairobi timezone)
  • Manual Trigger: For testing and manual execution of the nudge system

Nodes Used

Node Type Purpose
Schedule Trigger Automated daily execution at 7PM and 8PM
Manual Trigger Testing and manual workflow execution
PostgreSQL Database operations for user data, chat logs, and message history
HTTP Request Sending SMS messages via Africa's Talking API
Twilio Sending WhatsApp messages
If/Filter Conditional logic for channel routing and spam prevention
Set Message composition and data transformation
Split in Batches Processing users in manageable batches
Remove Duplicates Ensuring users don't receive multiple messages
Aggregate Combining filtered chat history data
No Operation Workflow organization and flow control

External Services & Credentials Required

Africa's Talking SMS API

  • Purpose: Sending SMS messages to users
  • Credentials: API key for toll_free_sms_ke username
  • Sender IDs: "24436" and "Educate"

Twilio WhatsApp API

  • Purpose: Sending WhatsApp messages
  • Credentials: Twilio API credentials (KIdaZWKXNQtH7wvH)
  • Phone Number: +254203892316

PostgreSQL Database

  • Purpose: User data storage and chat history logging
  • Credentials: PostgresOnSupabase connection
  • Tables:
    • youthEntrepreneursReal (user profiles)
    • youthProgressReport (progress tracking)
    • chatLog (interaction history)
    • n8n_chat_histories (message logging)

Environment Variables

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

Data Flow

Input Data

  • User records from youthEntrepreneursReal table
  • Progress data from youthProgressReport table
  • Chat interaction history from chatLog table

Processing

  • Filters active users who are not internal team members
  • Removes duplicates based on phone numbers
  • Checks communication preferences and recent interactions
  • Composes personalized messages in Swahili

Output Data

  • SMS messages sent via Africa's Talking API
  • WhatsApp messages sent via Twilio
  • Message logs stored in n8n_chat_histories table
  • Updated user status in database

Error Handling

The workflow includes several error handling mechanisms:

  • Always Output Data: Several PostgreSQL nodes are configured to continue execution even if queries fail
  • Continue on Error: The getUserRecord3 node has error output handling to prevent workflow failure
  • Conditional Checks: Multiple If nodes validate data existence before processing
  • Batch Processing: Split in Batches nodes prevent system overload and allow partial success

Known Limitations

  • The workflow contains hardcoded API keys that should be moved to secure credential storage
  • Message content is fixed in Swahili and not dynamically localized
  • No retry mechanism for failed message deliveries
  • Limited to Kenya-based phone numbers and services
  • Duplicate node names may cause confusion during maintenance

No related workflows are explicitly mentioned in the current configuration.

Setup Instructions

  1. Import the Workflow

    • Copy the workflow JSON into n8n
    • The workflow will be imported as "checkWhatNudgeChannel2UseAndSendNudge - Francis"

  2. Configure Credentials

    • Set up PostgreSQL connection named "PostgresOnSupabase"
    • Configure Twilio API credentials as "Twilio WhatsApp kdp"
    • Ensure Africa's Talking API key is properly secured

  3. Database Setup

    • Ensure the following tables exist:
      • youthEntrepreneursReal with required columns
      • youthProgressReport for tracking user progress
      • chatLog for interaction history
      • n8n_chat_histories for message logging

  4. Test the Workflow

    • Use the manual trigger to test with non-active users
    • Verify message delivery through both SMS and WhatsApp channels
    • Check database logging is working correctly

  5. Schedule Activation

    • Activate the workflow to enable the 7PM and 8PM triggers
    • Monitor initial runs to ensure proper execution

  6. Security Considerations

    • Replace hardcoded API keys with credential references
    • Review database permissions and access controls
    • Implement proper error monitoring and alerting