Daily Nudge System for Youth Entrepreneurs

This workflow automatically sends daily engagement messages to youth entrepreneurs participating in a business tracking program, using both SMS and WhatsApp channels based on user preferences and interaction history.

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 or tracking program by: - Sending daily reminders to collect business data (sales figures) - Using personalized messages in local language (Swahili) - Adapting communication channels based on user preferences and recent interactions - Managing onboarding status and tracking engagement

How It Works

The workflow operates on two main schedules (7PM and 8PM) and includes a manual trigger for testing:

1. Evening Session Initialization (7PM): Updates all active users to mark the evening session as started
2. User Data Retrieval: Fetches active youth entrepreneurs who haven't submitted today's data
3. Channel Intelligence: For each user, checks their recent WhatsApp interaction history
4. Smart Channel Selection:
   • If user has WhatsApp interactions within 24 hours → sends WhatsApp message
   • If no recent WhatsApp activity → sends SMS with WhatsApp invitation
   • If no WhatsApp preference → sends direct SMS
5. Message Personalization: Creates culturally appropriate messages in Swahili using the user's first name
6. Delivery & Logging: Sends messages via appropriate channel and logs the interaction
7. Batch Processing: Handles multiple users efficiently with duplicate removal

Workflow Diagram

graph TD
    A[7PM Nudge] --> B[Set Evening Session Started]
    B --> C[Get Active Users]
    C --> D[Remove Duplicates]
    D --> E{Channel Check}

    F[8PM Nudge] --> G[Get Users Without Data]
    G --> H[Remove Duplicates]
    H --> I[Loop Over Items]

    E -->|WhatsApp Users| J[Loop Over Items - WhatsApp Path]
    E -->|SMS Users| K[Loop Over Items - SMS Path]

    J --> L[Get Chat History]
    L --> M[Filter Recent Messages]
    M --> N[Check Data Availability]
    N --> O{Has Recent WhatsApp Activity?}

    O -->|Yes| P[Send WhatsApp Message]
    O -->|No| Q[Send SMS with WhatsApp Link]

    K --> R[Set SMS Message]
    R --> S[Send SMS]

    P --> T[Log to Database]
    Q --> U[Log to Database]
    S --> V[Log to Database]

    T --> W[Continue Loop]
    U --> W
    V --> W

    I --> X[Check User Channel]
    X --> Y{WhatsApp or SMS?}
    Y -->|WhatsApp| Z[Check Recent Activity]
    Y -->|SMS| AA[Send Direct SMS]

    Z --> BB{Recent Activity?}
    BB -->|Yes| CC[Send WhatsApp]
    BB -->|No| DD[Send SMS Invitation]

    CC --> EE[Log Interaction]
    DD --> EE
    AA --> EE

Triggers

• Schedule Trigger (7PM): Daily at 19:00 to initialize evening session
• Schedule Trigger (8PM): Daily at 20:00 for main nudge delivery
• Manual Trigger: For testing and manual execution

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 and chat history
HTTP Request	SMS delivery via Africa's Talking API
Twilio	WhatsApp message delivery
If/Filter	Conditional logic for channel selection
Set	Message content preparation and data transformation
Split in Batches	Efficient processing of multiple users
Remove Duplicates	Data deduplication
Aggregate	Data consolidation for decision making
No Op	Workflow organization and clarity

External Services & Credentials Required

Africa's Talking SMS API

• Purpose: SMS message delivery
• Credentials: API key (currently hardcoded - should be moved to environment variables)
• Endpoint: https://api.africastalking.com/version1/messaging

Twilio WhatsApp API

• Purpose: WhatsApp message delivery
• Credentials: Twilio API credentials (stored as "Twilio WhatsApp kdp")
• From Number: +254203892316

PostgreSQL Database

• Purpose: User data and chat history storage
• Credentials: "PostgresOnSupabase" connection
• Tables Used:
  • youthEntrepreneursReal: User profiles and status
  • n8n_chat_histories: Message logging
  • chatLog: WhatsApp interaction history

Environment Variables

Currently, the workflow has hardcoded values that should be moved to environment variables: - Africa's Talking API Key - SMS sender IDs ("24436", "Educate") - WhatsApp phone number (+254203892316)

Data Flow

Input Data

• User records from youthEntrepreneursReal table
• Recent chat history from chatLog and n8n_chat_histories
• Current timestamp for activity checking

Processing

• Filters active users who haven't submitted today's data
• Analyzes recent WhatsApp interactions (within 24 hours)
• Generates personalized messages in Swahili
• Routes messages through appropriate channels

Output Data

• SMS messages via Africa's Talking
• WhatsApp messages via Twilio
• Logged interactions in n8n_chat_histories
• Updated user status in database

Error Handling

The workflow includes basic error handling: - alwaysOutputData flags on database queries to continue processing even with empty results - onError: continueErrorOutput on some database operations - Conditional checks to prevent sending to users without phone numbers - Filters to exclude internal team members from messaging

Known Limitations

• API keys are hardcoded in the workflow (security risk)
• No rate limiting for API calls
• Limited error recovery mechanisms
• Duplicate message prevention relies on database state
• No delivery confirmation tracking
• Hardcoded message templates (not easily customizable)

Related Workflows

No related workflows identified from the current context.

Setup Instructions

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

2. Configure Database Connection:

   • Set up PostgreSQL credentials named "PostgresOnSupabase"
   • Ensure access to required tables: youthEntrepreneursReal, n8n_chat_histories, chatLog

3. Configure Twilio:

   • Create Twilio credentials named "Twilio WhatsApp kdp"
   • Verify WhatsApp Business API setup for +254203892316

4. Configure Africa's Talking:

   • Replace hardcoded API key with environment variable
   • Verify SMS sender IDs ("24436", "Educate") are registered

5. Environment Variables (Recommended):

   AFRICASTALKING_API_KEY=your_api_key_here
   AFRICASTALKING_USERNAME=toll_free_sms_ke
   WHATSAPP_FROM_NUMBER=+254203892316
   SMS_SENDER_ID_1=24436
   SMS_SENDER_ID_2=Educate
   

6. Database Schema: Ensure your database has the required tables with appropriate columns:

   • Users table with phone numbers, names, and status fields
   • Chat history tables for interaction tracking

7. Test Execution: Use the manual trigger to test the workflow before enabling scheduled execution

8. Activate Schedules: Enable the 7PM and 8PM schedule triggers for production use