Skip to content

Onboarding Nudge Workflow - Francis

This workflow automatically sends personalized onboarding nudges to youth entrepreneurs who haven't completed their setup process, using both WhatsApp and SMS channels to maximize engagement and guide users through the Sifa platform onboarding.

Purpose

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

Based on the workflow structure, this appears to be designed to re-engage users who have signed up for a youth entrepreneurship program but haven't completed their onboarding. The system sends targeted messages via WhatsApp or SMS to encourage users to continue their setup process, with different messaging strategies based on their communication channel and interaction history.

How It Works

  1. User Selection: The workflow queries the database for youth entrepreneurs with incomplete onboarding status, excluding call center users and internal team members
  2. Channel Detection: For each user, it determines whether they prefer WhatsApp or SMS communication
  3. Interaction History Check: For WhatsApp users, it checks if they've had any recent conversations (within 24 hours)
  4. Message Routing: Based on channel preference and interaction history, users receive different nudge messages:
    • WhatsApp users with recent activity get a gentle follow-up
    • WhatsApp users without recent activity get a re-engagement message
    • SMS users get direct text messages with WhatsApp invitation links
  5. Message Logging: All sent messages are recorded in the chat history database for tracking
  6. Batch Processing: Users are processed in batches to manage system load

Workflow Diagram

graph TD
    A[Manual Trigger] --> B[Get User Records]
    B --> C{Skip if Already Onboarded}
    C -->|Not Onboarded| D{Channel = WhatsApp?}
    C -->|Already Active| Z[End]

    D -->|Yes| E[Loop WhatsApp Users]
    D -->|No| F[Loop SMS Users]

    E --> G[Check Chat History]
    G --> H{Recent Activity?}
    H -->|Yes| I{Activity < 24hrs?}
    H -->|No| J[Send WhatsApp Invite via SMS]

    I -->|Yes| K[Send WhatsApp Follow-up]
    I -->|No| L[Send WhatsApp Re-engagement]

    F --> M[Set SMS Message]
    M --> N[Send SMS via Africa's Talking]

    K --> O[Log to Chat History]
    L --> P[Log to Chat History]
    J --> Q[Log to Chat History]
    N --> R[Log to Chat History]

    O --> E
    P --> E
    Q --> S[Continue SMS Loop]
    R --> F

    S --> T[End]
    E --> T
    F --> T

Trigger

  • Manual Trigger: Currently set to manual execution for testing
  • Scheduled Trigger: Configured but disabled - would run daily at 10:30 AM when enabled

Nodes Used

Node Type Purpose
Manual Trigger Starts the workflow for testing
Schedule Trigger Automated daily execution (disabled)
Postgres Database queries for user records and chat history
If (Conditional) Route users based on channel, onboarding status, 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) Prepare message content with user personalization
Sticky Note Documentation and workflow organization

External Services & Credentials Required

Twilio (WhatsApp)

  • Credential Name: "Twilio WhatsApp kdp"
  • Purpose: Send WhatsApp messages
  • Phone Numbers Used: +254203892316, +254203893816, +254203893815

Africa's Talking (SMS)

  • API Key: Required for SMS sending
  • Username: "toll_free_sms_ke"
  • Sender IDs: "24436", "Educate"
  • Purpose: Send SMS messages to users

PostgreSQL Database

  • Credential Name: "PostgresOnSupabase"
  • Purpose: User data storage and chat history logging
  • Tables Used:
    • youthEntrepreneursReal (user records)
    • chatLog (interaction history)
    • n8n_chat_histories (message logging)

Environment Variables

No explicit environment variables are used. All configuration is handled through: - Node parameters (phone numbers, API endpoints) - Credential storage (API keys, database connections) - Hardcoded values in message templates

Data Flow

Input

  • User records from youthEntrepreneursReal table
  • Filters: Non-null phone numbers, non-active onboarding status, excludes call center and internal team

Processing

  • User channel preference detection
  • Recent activity analysis (24-hour window)
  • Message personalization with user's first name
  • Batch processing for system efficiency

Output

  • WhatsApp messages via Twilio
  • SMS messages via Africa's Talking
  • Chat history entries in database
  • Processing continues until all batches complete

Error Handling

The workflow includes basic error handling: - Continue on Error: Several Twilio and database nodes are configured to continue processing even if individual messages fail - Always Output Data: SQL query nodes ensure the workflow continues even with empty results - Conditional Routing: Multiple fallback paths for different user states and channel preferences

Known Limitations

  • Currently runs in manual mode only (scheduled trigger disabled)
  • Hardcoded phone numbers and sender IDs limit flexibility
  • No retry mechanism for failed message deliveries
  • Limited to Kenyan phone numbers and Africa's Talking SMS service
  • Message templates are hardcoded in Swahili

No related workflows are explicitly mentioned in the current configuration.

Setup Instructions

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

  2. Configure Credentials:

    • Set up Twilio API credentials for WhatsApp messaging
    • Configure Africa's Talking API key and username
    • Establish PostgreSQL connection to Supabase database

  3. Database Setup: Ensure the following tables exist:

    • youthEntrepreneursReal with required columns (phoneNumber, firstName, channel, onboardingStatus, etc.)
    • chatLog for interaction tracking
    • n8n_chat_histories for message logging

  4. Phone Number Configuration: Update the Twilio phone numbers in the WhatsApp nodes to match your registered numbers

  5. Message Customization: Modify the message templates in the "Set" nodes to match your brand voice and language preferences

  6. Testing: Run the workflow manually first to verify all connections and message delivery

  7. Scheduling: Once tested, enable the Schedule Trigger node and set your preferred execution time

  8. Monitoring: Set up monitoring for failed executions and message delivery rates