Skip to content

Onboarding Nudge - Francis

This workflow automatically sends personalized nudge messages to youth entrepreneurs to encourage engagement with the Sifa platform. It operates on a scheduled basis, targeting users based on their onboarding status and communication preferences, sending messages via WhatsApp or SMS to guide them through the platform introduction process.

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 by: - Sending automated onboarding nudges to new users - Encouraging platform engagement through personalized messaging - Supporting users who haven't completed their initial interactions - Providing different communication paths based on user preferences (WhatsApp vs SMS)

How It Works

  1. User Retrieval: The workflow queries the database for youth entrepreneurs with specific criteria (new onboarding status, valid phone numbers, excluding call center users)

  2. Channel Detection: For each user, it determines their preferred communication channel (WhatsApp or SMS)

  3. WhatsApp User Path:

    • Checks recent chat history to avoid duplicate messages within 24 hours
    • Sends personalized WhatsApp messages via Twilio
    • Falls back to SMS with WhatsApp invitation link if needed
    • Records all interactions in the chat history

  4. SMS User Path:

    • Sends direct SMS messages via Africa's Talking API
    • Uses personalized greetings with user's first name
    • Records nudge messages in the system memory

  5. Follow-up Processing: The workflow handles users at different stages, sending appropriate messages for those who haven't engaged recently or completed onboarding

  6. Memory Management: All sent messages are logged to the chat history database for tracking and preventing duplicates

Workflow Diagram

graph TD
    A[Schedule Trigger - Daily 7PM] --> B[Get New Users from DB]
    B --> C{Skip if Already Onboarded}
    C -->|Not Onboarded| D{Check Channel Type}

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

    E --> G[Check Recent Chat History]
    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 with WhatsApp Link]

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

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

    N --> Q[Continue Loop]
    O --> Q
    P --> Q

    B --> R[Get Non-Internal Users]
    R --> S{Skip if Already Active}
    S -->|Not Active| T{Check Channel Type}

    T -->|WhatsApp| U[Loop Through WhatsApp Users - Follow-up]
    T -->|SMS| V[Loop Through SMS Users - Follow-up]

    U --> W[Check Recent Activity]
    V --> X[Set Follow-up Message]

    W --> Y[Send Follow-up WhatsApp]
    X --> Z[Send Follow-up SMS]

    Y --> AA[Log Follow-up]
    Z --> BB[Log Follow-up]

Trigger

  • Schedule Trigger: Runs daily at 7:00 PM (19:00)
  • Manual Trigger: Can be executed manually for testing purposes

Nodes Used

Node Type Purpose
Schedule Trigger Initiates workflow daily at 7 PM
Postgres Queries user database and manages chat history
If (Conditional) Routes users based on channel preference and onboarding status
Split in Batches Processes users in batches to avoid overwhelming external APIs
Set (Edit Fields) Prepares personalized message content
Twilio Sends WhatsApp messages
HTTP Request Sends SMS via Africa's Talking API
Sticky Note Provides workflow documentation and section labels

External Services & Credentials Required

Twilio (WhatsApp)

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

Africa's Talking (SMS)

  • API Key: Required for SMS sending
  • Username: toll_free_sms_ke
  • Sender IDs: 24436, Educate
  • Purpose: SMS delivery to users without WhatsApp

PostgreSQL Database

  • Credential Name: "PostgresOnSupabase"
  • Purpose: User data retrieval and chat history management
  • Tables: youthEntrepreneursReal, chatLog, n8n_chat_histories

Environment Variables

No explicit environment variables are defined in this workflow. All configuration is handled through: - Database connection credentials - API keys stored in n8n credential system - Hardcoded phone numbers and sender IDs

Data Flow

Input Data

  • User records from youthEntrepreneursReal table
  • Chat history from chatLog and n8n_chat_histories tables
  • User attributes: phoneNumber, firstName, channel, onboardingStatus

Output Data

  • WhatsApp messages sent via Twilio
  • SMS messages sent via Africa's Talking
  • Chat history records inserted into database
  • Nudge tracking in n8n_chat_histories table

Message Templates

  • Initial Nudge: "Habari [Name]! Leo ni Day 1 ya real tracking. Hebu niambie, Leo uliuza ngapi?"
  • Onboarding Invitation: "Habari [Name], tungetaka kukupitisha kwa jinsi ya kutumia Sifa. Je uko tayari?"
  • Follow-up: "Habari [Name], tumenotice hauku maliza kuongea na Sifa jana usiku..."

Error Handling

The workflow includes several error prevention mechanisms: - Always Output Data: SQL query nodes are configured to continue even with empty results - Conditional Routing: Multiple if/else paths handle different user states - Duplicate Prevention: 24-hour check prevents sending multiple messages to the same user - Batch Processing: Split in Batches nodes prevent overwhelming external APIs

No explicit error handling nodes are present, relying on n8n's built-in error management.

Known Limitations

  • Hardcoded API keys in HTTP request nodes (security concern)
  • Limited to Kenyan phone numbers and Swahili language
  • No retry mechanism for failed API calls
  • Manual exclusion of specific phone numbers (+254745990589)
  • Disabled nodes suggest incomplete cleanup functionality

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 PostgreSQL connection to Supabase with credential name "PostgresOnSupabase"
    • Configure Twilio API credentials as "Twilio WhatsApp kdp"
    • Ensure Africa's Talking API key is properly configured

  3. Database Setup:

    • Ensure youthEntrepreneursReal table exists with required columns
    • Set up chatLog and n8n_chat_histories tables for message tracking

  4. Security Review:

    • Replace hardcoded API keys with credential references
    • Review phone number exclusions and sender IDs

  5. Testing:

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

  6. Activation:

    • Enable the schedule trigger for daily operation
    • Monitor execution logs for any failures

  7. Customization:

    • Modify message templates as needed
    • Adjust scheduling time based on user timezone preferences
    • Update user filtering criteria in database queries