Skip to content

Onboarding Nudge Workflow - Francis

This workflow automatically sends personalized nudge messages to youth entrepreneurs who haven't completed their onboarding process, using both WhatsApp and SMS channels to encourage engagement with the Sifa platform.

Purpose

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

How It Works

  1. User Retrieval: The workflow fetches youth entrepreneurs from the database who have incomplete onboarding status (not "active") and excludes call center and internal team entries
  2. Channel Detection: For each user, it determines whether they prefer WhatsApp or SMS communication
  3. Activity Check: For WhatsApp users, it checks if they've had any chat activity in the last 24 hours
  4. Message Personalization: Creates personalized nudge messages in Swahili, addressing users by their first name
  5. Multi-Channel Delivery: Sends messages via WhatsApp (using Twilio) or SMS (using Africa's Talking API)
  6. Memory Storage: Logs all sent nudges to the chat history database for tracking purposes
  7. Batch Processing: Processes users in batches to avoid overwhelming external services

The workflow includes multiple parallel paths for different user segments and has both production and development sections for testing.

Workflow Diagram

graph TD
    A[Manual Trigger] --> B[Get User Records]
    B --> C{Skip if Already Onboarded}
    C -->|Not Onboarded| D{Channel Check}
    D -->|WhatsApp| E[Loop Over WhatsApp Users]
    D -->|SMS| F[Loop Over SMS Users]

    E --> G[Check Chat Log]
    G --> H{Chat Record Exists?}
    H -->|Yes| I{Less than 24hrs?}
    H -->|No| J[Send WhatsApp Nudge]
    I -->|Yes| J
    I -->|No| K[Send SMS Fallback]

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

    J --> N[Store in Chat History]
    K --> O[Store in Chat History]
    M --> P[Store in Chat History]

    N --> E
    O --> E
    P --> F

Trigger

  • Manual Trigger: Currently activated by clicking "Execute workflow" in the n8n interface
  • Scheduled Trigger: Disabled schedule trigger set for 10:30 AM daily (can be enabled for automated runs)

Nodes Used

Node Type Purpose
Manual Trigger Starts the workflow manually for testing
Schedule Trigger Automated daily execution (currently disabled)
Postgres Database queries for user records and chat history
If Conditional logic for channel routing and activity checks
Split in Batches Processes users in manageable batches
Set Creates and formats message content
Twilio Sends WhatsApp messages
HTTP Request Sends SMS via Africa's Talking API
Sticky Note Documentation and workflow organization

External Services & Credentials Required

Twilio (WhatsApp)

  • Credential: twilioApi (ID: KIdaZWKXNQtH7wvH)
  • Purpose: WhatsApp message delivery
  • Phone Numbers: +254203892316, +254203893816, +254203893815

Africa's Talking (SMS)

  • API Key: Required for SMS delivery
  • Username: toll_free_sms_ke
  • Sender IDs: 24436, Educate
  • Purpose: SMS message delivery

PostgreSQL Database

  • Credential: PostgresOnSupabase (ID: Hw9XWerQ5RNHaVTk)
  • Purpose: User data and chat history storage

Environment Variables

No explicit environment variables are used. Configuration is handled through: - Hard-coded API keys in HTTP request headers - Database connection via n8n credentials - Phone numbers and sender IDs embedded in node configurations

Data Flow

Input

  • User records from youthEntrepreneursReal table with:
    • Phone numbers
    • First names
    • Onboarding status
    • Communication channel preference
    • Exclusion filters (call center, internal team)

Processing

  • Chat activity analysis from chatLog table
  • Message personalization with user names
  • Channel-specific routing logic
  • 24-hour activity window checks

Output

  • WhatsApp messages via Twilio API
  • SMS messages via Africa's Talking API
  • Chat history entries in n8n_chat_histories table
  • Batch processing completion status

Error Handling

  • Continue on Error: Several nodes (Twilio WhatsApp, database inserts) are configured to continue execution even if individual operations fail
  • Always Output Data: SQL query nodes are set to always return data, even when no records are found
  • Graceful Degradation: WhatsApp failures can fall back to SMS delivery

Known Limitations

  • Hard-coded API keys present security risks
  • No retry mechanism for failed message deliveries
  • Limited error logging and monitoring
  • Manual trigger dependency for current operation
  • Multiple similar code paths suggest potential for consolidation

No related workflows specified in the current context.

Setup Instructions

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

  2. Configure Credentials:

    • Set up PostgreSQL connection to Supabase
    • Configure Twilio API credentials for WhatsApp
    • Ensure Africa's Talking API key is properly set

  3. Database Requirements:

    • youthEntrepreneursReal table with required columns
    • chatLog table for activity tracking
    • n8n_chat_histories table for message logging

  4. Phone Number Setup:

    • Verify Twilio WhatsApp sandbox or production numbers
    • Configure Africa's Talking sender IDs

  5. Testing:

    • Use manual trigger for initial testing
    • Verify message delivery on both channels
    • Check database logging functionality

  6. Production Deployment:

    • Enable the schedule trigger for automated daily runs
    • Monitor execution logs for errors
    • Set up proper API key management
    • Consider implementing retry logic for failed deliveries