Send Nudge Messages

This workflow automatically 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 part of a youth entrepreneurship coaching program that helps young business owners track their daily sales and profits. The system sends personalized nudge messages to encourage regular engagement and business monitoring.

How It Works

1. User Retrieval: Fetches all active youth entrepreneurs from the database who have valid phone numbers
2. Deduplication: Removes any duplicate phone numbers to prevent multiple messages
3. Channel Routing: Determines whether each user prefers WhatsApp or SMS communication
4. WhatsApp Flow: For WhatsApp users, checks if they've been contacted in the last 24 hours to avoid spam
5. Message Personalization: Creates personalized messages using the user's first name
6. Message Delivery: Sends messages via the appropriate channel (Twilio for WhatsApp, Africa's Talking for SMS)
7. Chat History Logging: Records all sent messages in the database for tracking purposes
8. Batch Processing: Processes users in batches to handle large volumes efficiently

Workflow Diagram

graph TD
    A[Start] --> B[Get User Records]
    B --> C[Remove Duplicates]
    C --> D[Channel Check]

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

    E --> G[Check Last Chat Log]
    G --> H[Record Exists?]
    H -->|Yes| I[24hrs Passed?]
    H -->|No| J[Set WhatsApp Message]
    I -->|Yes| K[Send WhatsApp via Twilio]
    I -->|No| J
    J --> L[Send SMS via Africa's Talking]
    K --> M[Log WhatsApp Message]

    F --> N[Set SMS Message]
    N --> O[Send SMS via Africa's Talking]
    O --> P[Log SMS Message]

    M --> E
    P --> F
    L --> Q[Log SMS Message]
    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	Purpose
Execute Workflow Trigger	Receives workflow execution requests
Postgres	Queries user database and logs chat history
Remove Duplicates	Prevents duplicate messages to same phone number
If	Routes users based on communication channel preference
Split in Batches	Processes users in manageable batches
Set	Creates personalized message content
HTTP Request	Sends SMS messages via Africa's Talking API
Twilio	Sends WhatsApp messages
Sticky Note	Documentation and visual organization

External Services & Credentials Required

Africa's Talking SMS

• Service: SMS delivery for Kenyan users
• Credentials: API key (currently hardcoded - should be moved to environment variables)
• Username: toll_free_sms_ke
• Sender ID: 24436 (SMS) / Educate (WhatsApp fallback)

Twilio WhatsApp

• Service: WhatsApp message delivery
• Credentials: Twilio API credentials
• From Number: +254203892316

PostgreSQL Database

• Service: User data and chat history storage
• Credentials: Supabase PostgreSQL connection
• Tables Used:
  • youthEntrepreneursReal (user data)
  • chatLog (message history)
  • n8n_chat_histories (workflow message logs)

Environment Variables

Currently, the workflow has hardcoded credentials that should be moved to environment variables: - AFRICAS_TALKING_API_KEY - AFRICAS_TALKING_USERNAME - TWILIO_ACCOUNT_SID - TWILIO_AUTH_TOKEN

Data Flow

Input

• Optional phoneNumber parameter (not currently used in filtering)

Processing

• Retrieves all active users with valid phone numbers
• Filters by communication channel preference
• Applies 24-hour cooldown for WhatsApp users
• Personalizes messages with user's first name

Output

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

Sample Messages

• SMS: "Habari [Name]! Ni time ya kuongea na SIFA. Jibu SMS ya SIFA akusaidie kuona profit yako ya leo! Leo mauzo/sales zako zimekuwa ngapi?"
• WhatsApp: "Habari [Name]! 👋 Tunaendelea na real tracking. Hebu niambie, Leo uliuza ngapi?"

Error Handling

The workflow includes basic error handling through: - Conditional checks for existing chat logs - 24-hour cooldown logic to prevent spam - Batch processing to handle large user volumes - Always output data flag on database queries

No explicit error catching or retry mechanisms are implemented.

Known Limitations

• API credentials are hardcoded instead of using environment variables
• No rate limiting beyond the 24-hour WhatsApp cooldown
• No delivery confirmation tracking
• Limited error handling and retry logic
• Workflow is currently inactive (active: false)

Related Workflows

This workflow appears to be part of a larger SIFA coaching system but no specific related workflows are referenced in the current implementation.

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Database Connection:
   • Set up PostgreSQL credentials for Supabase
   • Ensure tables youthEntrepreneursReal, chatLog, and n8n_chat_histories exist
3. Configure Africa's Talking:
   • Create account and get API key
   • Replace hardcoded API key with credential reference
   • Verify sender ID permissions
4. Configure Twilio:
   • Set up Twilio WhatsApp sandbox or approved number
   • Configure Twilio API credentials
5. Environment Variables:
   • Move all hardcoded credentials to secure credential storage
6. Test Execution:
   • Start with a small test group
   • Verify message delivery on both channels
   • Check database logging functionality
7. Activate Workflow: Set active: true when ready for production use