Onboarding Nudge - Francis

This workflow automatically sends personalized onboarding messages to youth entrepreneurs who haven't completed their initial setup, using both WhatsApp and SMS channels to maximize reach and engagement.

Purpose

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

How It Works

1. User Retrieval: Fetches youth entrepreneurs from the database who have "new" onboarding status and valid phone numbers
2. Channel Detection: Determines if the user prefers WhatsApp or SMS communication
3. Activity Check: For WhatsApp users, checks if they've had any chat activity in the last 24 hours
4. Message Routing: Sends appropriate nudge messages based on user channel and activity:
   • WhatsApp users get direct WhatsApp messages via Twilio
   • Non-WhatsApp users get SMS messages via Africa's Talking
   • Users with no recent activity get re-engagement messages
5. Message Logging: Records all sent messages in the chat history database for tracking
6. Batch Processing: Processes users in batches to avoid overwhelming external services

Mermaid Diagram

graph TD
    A[Manual Trigger] --> B[Get User Records]
    B --> C[Skip If Already Onboarded]
    C --> D{Channel = WhatsApp?}
    D -->|Yes| E[Loop Over WhatsApp Users]
    D -->|No| F[Loop Over SMS Users]

    E --> G[Check Chat Log]
    G --> H{Found Chat Record?}
    H -->|Yes| I{Less than 24hrs passed?}
    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[Log to Chat History]
    K --> O[Log to Chat History]
    M --> P[Log to Chat History]

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

Trigger

• Manual Trigger: Currently activated manually via the n8n interface
• Scheduled Trigger: Disabled schedule trigger set for 10:30 AM daily (can be enabled for automation)

Nodes Used

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

External Services & Credentials Required

Twilio (WhatsApp)

• Credential: twilioApi (Iganga Coach)
• Purpose: Sending WhatsApp messages
• From Number: +254203892316, +254203893816, +254203893815

Africa's Talking (SMS)

• Credential: httpHeaderAuth (AT Header Auth)
• Purpose: Sending SMS messages
• Username: toll_free_sms_ke
• Sender IDs: 24436, Educate

PostgreSQL Database

• Credential: postgres (kdpTables)
• Purpose: User data storage and chat history logging
• Tables: youthEntrepreneursReal, chatLog, n8n_chat_histories

Environment Variables

No explicit environment variables are used in this workflow. All configuration is handled through n8n credentials and node parameters.

Data Flow

Input

• User records from youthEntrepreneursReal table with:
  • Phone numbers
  • First names
  • Onboarding status
  • Communication channel preference

Processing

• Filters users with "new" onboarding status
• Excludes call center and internal team users
• Personalizes messages with user first names
• Tracks message delivery in chat history

Output

• WhatsApp messages sent via Twilio
• SMS messages sent via Africa's Talking
• Chat history records in database
• Batch processing completion status

Error Handling

The workflow includes basic error handling: - Continue on Error: Several Twilio and database nodes 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 - Conditional Checks: Multiple IF nodes validate data existence before processing

Known Limitations

• Currently requires manual execution (scheduled trigger is disabled)
• No retry mechanism for failed message deliveries
• Limited to processing 200 users at a time in some queries
• No delivery confirmation tracking
• Hardcoded message templates in multiple languages (Swahili)

Related Workflows

No related workflows mentioned in the current context.

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Credentials:
   • Set up Twilio API credentials for WhatsApp messaging
   • Configure Africa's Talking HTTP header authentication
   • Set up PostgreSQL database connection
3. Database Setup: Ensure the following tables exist:
   • youthEntrepreneursReal (user data)
   • chatLog (chat history)
   • n8n_chat_histories (message logging)
4. Test Configuration: Run the workflow manually to verify all connections
5. Enable Scheduling: Activate the Schedule Trigger node for automated daily execution
6. Monitor Execution: Check logs and database records to ensure proper message delivery

Required Database Schema

-- Ensure these columns exist in youthEntrepreneursReal
phoneNumber, firstName, onboardingStatus, channel, intr01_uuid

-- Ensure these columns exist in chatLog
userPhone, channel, created_at

-- Ensure this table exists for n8n_chat_histories
session_id, message (jsonb type)