Onboarding Nudge Workflow

This workflow automatically sends personalized nudge messages to youth entrepreneurs who haven't completed their onboarding or haven't engaged with the Sifa platform recently. It intelligently routes messages through WhatsApp or SMS based on user preferences and interaction history, helping to re-engage users and guide them through the onboarding process.

Purpose

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

Based on the workflow implementation, this appears to serve youth entrepreneurs in a coaching or business development program. The workflow helps maintain engagement by: - Sending timely nudges to users who haven't completed onboarding - Re-engaging users who haven't interacted with the platform in the last 24 hours - Providing different messaging strategies based on communication channel preferences - Tracking all interactions for future reference and analysis

How It Works

The workflow operates in two main execution paths:

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

Path 2: Re-engagement Nudges 1. Retrieves users who don't have "active" onboarding status 2. Again separates by communication channel preference 3. For users with chat history: Checks if their last interaction was more than 24 hours ago 4. Sends follow-up messages encouraging continued engagement 5. Logs all interactions for future reference

The workflow personalizes messages using the user's first name and adapts the content based on whether it's an initial onboarding nudge or a re-engagement attempt.

Workflow Diagram

graph TD
    A[Schedule Trigger - 7PM Daily] --> B[Get New Users]
    B --> C{Channel = WhatsApp?}
    C -->|Yes| D[Loop WhatsApp Users]
    C -->|No| E[Loop SMS Users]

    D --> F[Check Last Chat]
    F --> G{Has Chat Record?}
    G -->|Yes| H{Last Chat < 24hrs?}
    G -->|No| I[Send WhatsApp Onboarding]
    H -->|Yes| J[Send WhatsApp Nudge]
    H -->|No| K[Send SMS with WhatsApp Link]

    E --> L[Send SMS Onboarding]

    I --> M[Log to Chat History]
    J --> N[Log to Chat History]
    K --> O[Log to Chat History]
    L --> P[Log to Chat History]

    Q[Manual Trigger] --> R[Get Non-Active Users]
    R --> S{Channel = WhatsApp?}
    S -->|Yes| T[Loop WhatsApp Users]
    S -->|No| U[Loop SMS Users]

    T --> V[Check Last Chat]
    V --> W{Has Chat Record?}
    W -->|Yes| X{Last Chat < 24hrs?}
    W -->|No| Y[Send WhatsApp Re-engagement]
    X -->|Yes| Z[Send WhatsApp Follow-up]
    X -->|No| AA[Send SMS with WhatsApp Link]

    U --> BB[Check Last Chat]
    BB --> CC{Has Chat Record?}
    CC -->|Yes| DD[Send SMS Re-engagement]
    CC -->|No| EE[Send SMS Follow-up]

    Y --> FF[Log to Chat History]
    Z --> GG[Log to Chat History]
    AA --> HH[Log to Chat History]
    DD --> II[Log to Chat History]
    EE --> JJ[Log to Chat History]

Trigger

• Primary: Schedule Trigger set to run daily at 7:00 PM (currently disabled)
• Secondary: Manual trigger for testing and ad-hoc execution
• Alternative: Schedule Trigger1 also set for 7:00 PM (active)

Nodes Used

Node Type	Purpose
Schedule Trigger	Automatically runs the workflow daily at 7 PM
Manual Trigger	Allows manual execution for testing
Postgres	Queries user database and logs chat interactions
If	Routes users based on communication channel and interaction history
Split in Batches	Processes users one by one to avoid rate limits
Set	Prepares personalized message content
Twilio	Sends WhatsApp messages
HTTP Request	Sends SMS messages via Africa's Talking API
Sticky Note	Provides visual organization and documentation

External Services & Credentials Required

Twilio (WhatsApp) - Credential: "Twilio WhatsApp kdp" - Used for sending WhatsApp messages - Requires Twilio account with WhatsApp Business API access

Africa's Talking (SMS) - API Key embedded in HTTP requests - Used for sending SMS messages - Requires Africa's Talking account

PostgreSQL Database - Credential: "PostgresOnSupabase" - Stores user data and chat histories - Requires database connection details

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Hardcoded API keys in HTTP request headers - Database credentials stored in n8n credential system - Phone numbers and sender IDs configured directly in nodes

Data Flow

Input Data: - User records from youthEntrepreneursReal table including: - phoneNumber - firstName - onboardingStatus - channel (WhatsApp/SMS) - intr01_uuid

Processing: - Filters out internal team members and call center users - Checks chat interaction history from chatLog table - Generates personalized messages based on user data

Output Data: - WhatsApp/SMS messages sent to users - Chat history records inserted into n8n_chat_histories table - Message logs for tracking and analytics

Error Handling

The workflow includes basic error handling through: - alwaysOutputData: true on SQL query nodes to handle empty results - Conditional logic to handle users with no chat history - Phone number filtering to exclude specific test numbers - Batch processing to prevent overwhelming external APIs

Known Limitations

• API keys are hardcoded in the workflow (security risk)
• Limited to 200 users per execution due to database query limits
• No retry mechanism for failed message deliveries
• Hardcoded exclusion of specific phone numbers
• No rate limiting beyond batch processing
• Messages are in Swahili, limiting to Swahili-speaking users

Related Workflows

No related workflows are explicitly mentioned in the current implementation.

Setup Instructions

1. Import the Workflow

   • Copy the workflow JSON into n8n
   • The workflow will be imported with all node configurations

2. Configure Database Credentials

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

3. Configure Twilio Credentials

   • Create Twilio credential named "Twilio WhatsApp kdp"
   • Configure with Account SID, Auth Token, and WhatsApp number

4. Configure Africa's Talking

   • Update the API key in HTTP request nodes
   • Verify the username and sender ID configurations

5. Database Schema Requirements

   • Ensure required tables exist with proper column names
   • Set up appropriate indexes for performance

6. Testing

   • Use the manual trigger to test the workflow
   • Verify message delivery and database logging
   • Check that user filtering works correctly

7. Production Deployment

   • Enable the schedule trigger for daily execution
   • Monitor execution logs for errors
   • Set up alerting for failed executions

8. Security Improvements

   • Move API keys to environment variables or secure credential storage
   • Review and update hardcoded phone number exclusions
   • Implement proper error handling and retry logic