Onboarding Nudge Workflow

This workflow automatically sends personalized nudge messages to youth entrepreneurs who haven't completed their onboarding or haven't interacted with the Sifa system recently. It intelligently routes messages through WhatsApp or SMS based on the user's preferred communication channel and interaction history.

Purpose

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

How It Works

The workflow operates in two main phases, each targeting different user segments:

Phase 1: New User Onboarding 1. Retrieves all users with "new" onboarding status from the database 2. Separates users by their preferred channel (WhatsApp vs SMS) 3. For WhatsApp users: Checks if they've had any interactions in the last 24 hours 4. Sends appropriate nudge messages encouraging users to complete onboarding 5. Logs all sent messages to the chat history for tracking

Phase 2: Re-engagement for Inactive Users 1. Retrieves users who aren't fully active (not in "active" status) 2. Again separates by communication channel preference 3. For WhatsApp users: Checks recent interaction history 4. Sends re-engagement messages to users who haven't interacted recently 5. Records all outbound messages for conversation continuity

The workflow includes smart filtering to avoid messaging internal team members and call center contacts, and has special handling to exclude specific test phone numbers.

Workflow Diagram

graph TD
    A[Schedule Trigger] --> B[Get New Users]
    B --> C{Channel Type?}
    C -->|WhatsApp| D[Loop WhatsApp Users]
    C -->|SMS| E[Loop SMS Users]

    D --> F[Check Recent Chat Log]
    F --> G{Has Recent Activity?}
    G -->|Yes| H[Send WhatsApp Nudge]
    G -->|No| I[Send SMS Fallback]
    H --> J[Log to Chat History]
    I --> K[Log to Chat History]

    E --> L[Set SMS Message]
    L --> M[Send SMS]
    M --> N[Log to Chat History]

    O[Schedule Trigger 2] --> P[Get Inactive Users]
    P --> Q{Channel Type?}
    Q -->|WhatsApp| R[Loop WhatsApp Users]
    Q -->|SMS| S[Loop SMS Users]

    R --> T[Check Recent Activity]
    T --> U{Recent Interaction?}
    U -->|Yes| V[Send WhatsApp Re-engagement]
    U -->|No| W[Send SMS Re-engagement]
    V --> X[Log Message]
    W --> Y[Log Message]

    S --> Z[Set Re-engagement Message]
    Z --> AA[Send SMS]
    AA --> BB[Log Message]

Trigger

• Schedule Trigger: Runs daily at 7:00 PM (19:00) - currently disabled
• Manual Trigger: Available for testing and manual execution

Nodes Used

Node Type	Purpose
Schedule Trigger	Automated daily execution at 7 PM
Manual Trigger	Manual workflow testing
Postgres	Database queries for user data and chat history
If (Conditional)	Route logic based on channel type and activity
Split in Batches	Process users in manageable batches
Twilio	Send WhatsApp messages
HTTP Request	Send SMS via Africa's Talking API
Set (Edit Fields)	Format message content
Sticky Note	Documentation and visual organization

External Services & Credentials Required

Twilio (WhatsApp) - Credential: twilioApi (ID: KIdaZWKXNQtH7wvH) - Used for sending WhatsApp messages - Requires Account SID, Auth Token, and WhatsApp number

Africa's Talking (SMS) - API Key embedded in HTTP requests - Username: toll_free_sms_ke - Sender IDs: 24436, Educate - Used for SMS delivery

PostgreSQL Database - Credential: PostgresOnSupabase (ID: Hw9XWerQ5RNHaVTk) - Tables accessed: - youthEntrepreneursReal (user data) - chatLog (interaction history) - n8n_chat_histories (message logging)

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Hardcoded API keys in HTTP request headers - Database connection via n8n credentials - Phone number filtering (excludes +254745990589, +254712287952)

Data Flow

Input: - User records from youthEntrepreneursReal table - Chat history from chatLog table - Current timestamp for activity calculations

Processing: - Filters users by onboarding status and channel preference - Checks recent activity within 24-hour windows - Personalizes messages with user's first name - Routes messages through appropriate communication channels

Output: - WhatsApp messages via Twilio API - SMS messages via Africa's Talking API - Chat history entries in n8n_chat_histories table - Batch processing status updates

Error Handling

The workflow includes basic error handling through: - alwaysOutputData: true on SQL query nodes to handle empty results - Conditional routing to prevent messaging when no data is found - Phone number filtering to exclude test/internal numbers - Batch processing to prevent overwhelming external APIs

No explicit error notification or retry mechanisms are implemented.

Known Limitations

• Contains hardcoded API keys that should be moved to secure credential storage
• Limited to 200 users per execution due to database query limits
• No retry mechanism for failed message deliveries
• Schedule trigger is currently disabled
• Some message logging queries have potential JSON formatting issues
• No rate limiting for external API calls

Related Workflows

No related workflows are explicitly referenced in the current implementation.

Setup Instructions

1. Import the Workflow

   • Copy the workflow JSON into n8n
   • The workflow will be imported as "onboardingNudge"

2. Configure Database Credentials

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

3. Configure Twilio Credentials

   • Create Twilio API credential with ID "KIdaZWKXNQtH7wvH"
   • Include Account SID, Auth Token, and WhatsApp-enabled phone number

4. Update Africa's Talking Configuration

   • Replace the hardcoded API key in HTTP request nodes with a secure credential
   • Verify the username and sender IDs match your account settings

5. Customize Phone Number Filters

   • Update the excluded phone numbers in conditional nodes
   • Modify the test phone number checks as needed

6. Enable Schedule Trigger

   • Activate the schedule trigger if automated daily execution is desired
   • Adjust the trigger time (currently set to 7 PM) as needed

7. Test the Workflow

   • Use the manual trigger to test with a small user subset
   • Verify message delivery and database logging
   • Check that conditional routing works correctly

8. Monitor and Maintain

   • Review chat history logs for successful message delivery
   • Monitor external service usage and costs
   • Update message templates as needed for user engagement