Skip to content

Nudge Message Development

This workflow sends daily engagement messages to youth entrepreneurs through their preferred communication channel (WhatsApp or SMS), encouraging them to track their daily sales and interact with the SIFA coaching system.

Purpose

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

Based on the workflow implementation, this appears to be a user engagement system that: - Sends daily nudge messages to active youth entrepreneurs - Routes messages through WhatsApp or SMS based on user preference - Encourages users to report their daily sales figures - Maintains conversation history for tracking engagement - Prevents message spam by checking recent activity before sending

How It Works

  1. User Retrieval: Fetches all active youth entrepreneurs from the database who have valid phone numbers
  2. Channel Detection: Determines whether each user prefers WhatsApp or SMS communication
  3. WhatsApp Route: For WhatsApp users, checks if they've been contacted in the last 24 hours to avoid spam
  4. Message Personalization: Creates personalized nudge messages using the user's first name
  5. Message Delivery: Sends messages via the appropriate channel (Twilio for WhatsApp, Africa's Talking for SMS)
  6. History Logging: Records all sent messages in the chat history database for tracking

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[getUserRecord]
    B --> C[Remove Duplicates]
    C --> D[If - Channel Check]

    D -->|WhatsApp| E[Loop Over Items]
    D -->|SMS| F[Loop Over Items1]

    E --> G[Execute a SQL query]
    G --> H[checkIfWeFindAChatlogRecord]
    H -->|Record Found| I[ifLessThen24hrsPassed]
    H -->|No Record| J[setNudgeMessage1]

    I -->|< 24hrs| K[Send WhatsApp response via Twilio1]
    I -->|> 24hrs| J

    K --> L[getUserRecord3]
    J --> M[Send SMS via Africa's Talking2]
    M --> N[getUserRecord5]

    L --> E
    N --> E

    F --> O[setNudgeMessage]
    O --> P[Send SMS via Africa's Talking]
    P --> Q[getUserRecord4]
    Q --> F

Trigger

  • Type: Execute Workflow Trigger
  • Input: Accepts a phoneNumber parameter (though the workflow fetches all active users regardless)
  • Activation: Must be called by another workflow or manually executed

Nodes Used

Node Type Node Name Purpose
Execute Workflow Trigger When Executed by Another Workflow Entry point for the workflow
Postgres getUserRecord Fetches active youth entrepreneurs from database
Remove Duplicates Remove Duplicates Ensures no duplicate phone numbers
If If Routes users based on communication channel preference
Split in Batches Loop Over Items / Loop Over Items1 Processes users one by one
Postgres Execute a SQL query Checks recent WhatsApp chat history
If checkIfWeFindAChatlogRecord Determines if user has chat history
If ifLessThen24hrsPassed Prevents spam by checking last contact time
Set setNudgeMessage / setNudgeMessage1 Creates personalized message content
Twilio Send WhatsApp response via Twilio1 Sends WhatsApp messages
HTTP Request Send SMS via Africa's Talking / Send SMS via Africa's Talking2 Sends SMS messages
Postgres getUserRecord3 / getUserRecord4 / getUserRecord5 Logs messages to chat history

External Services & Credentials Required

Africa's Talking SMS API

  • Credential Name: Not stored in credential manager (API key hardcoded)
  • Required: API key for SMS sending
  • Username: toll_free_sms_ke
  • Sender ID: 24436 (for sales tracking), Educate (for WhatsApp promotion)

Twilio WhatsApp API

  • Credential Name: twilioApi (KIdaZWKXNQtH7wvH)
  • Required: Account SID and Auth Token
  • From Number: +254203892316

PostgreSQL Database

  • Credential Name: PostgresOnSupabase (Hw9XWerQ5RNHaVTk)
  • Required: Database connection details for Supabase
  • Tables Used:
    • youthEntrepreneursReal (user data)
    • chatLog (WhatsApp chat history)
    • n8n_chat_histories (message logging)

Environment Variables

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

Data Flow

Input

  • Optional phoneNumber parameter (currently unused)

Processing

  • Retrieves user records with phone numbers and active status
  • Filters by communication channel preference
  • Checks recent activity for WhatsApp users
  • Generates personalized messages

Output

  • SMS messages sent via Africa's Talking API
  • WhatsApp messages sent via Twilio API
  • Message history logged to database
  • API responses from messaging services

Error Handling

The workflow includes basic error handling through: - Always Output Data: SQL query node continues even if no records found - Conditional Logic: If statements handle missing data gracefully - Batch Processing: Split in Batches ensures individual failures don't stop the entire process

No explicit error handling or retry mechanisms are implemented for API failures.

Known Limitations

  • API key is hardcoded in the Africa's Talking HTTP request (security risk)
  • No retry mechanism for failed message deliveries
  • WhatsApp spam prevention only checks one table (chatLog) but logs to another (n8n_chat_histories)
  • No validation of phone number formats before sending
  • Fixed message templates with no A/B testing capability

This workflow is designed to be called by other workflows but no specific related workflows are identified in the current implementation.

Setup Instructions

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

  2. Configure Database Credentials:

    • Set up PostgreSQL credential named "PostgresOnSupabase"
    • Ensure connection to database with required tables

  3. Configure Twilio Credentials:

    • Create Twilio API credential named "twilioApi"
    • Verify WhatsApp sender number (+254203892316) is approved

  4. Update Africa's Talking Configuration:

    • Replace hardcoded API key with secure credential reference
    • Verify username and sender IDs are correct for your account

  5. Database Setup:

    • Ensure youthEntrepreneursReal table exists with required columns
    • Create chatLog and n8n_chat_histories tables if not present
    • Verify user data includes channel field for routing

  6. Test Execution:

    • Run workflow manually to verify all connections work
    • Check message delivery and database logging
    • Validate spam prevention logic for WhatsApp users

  7. Schedule or Trigger:

    • Set up calling workflow or schedule to execute daily
    • Consider time zones for optimal message delivery