Profit Path — Nudge Dispatcher (Cron)¶

This automated workflow sends timely WhatsApp nudges to youth entrepreneurs participating in the Profit Path program, helping them stay engaged with their assigned micro-actions throughout the day. It runs every 30 minutes to check for scheduled follow-ups and delivers personalized messages in Swahili to encourage action completion and check-ins.

Purpose¶

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

Based on the workflow implementation, this system appears to support a youth entrepreneurship coaching program by: - Sending automated reminders for daily business actions - Providing timely check-ins at strategic points (morning, afternoon, evening) - Maintaining engagement through personalized WhatsApp communication - Tracking follow-up completion to prevent duplicate messages

How It Works¶

Scheduled Check: Every 30 minutes, the workflow queries the database for overdue nudges that haven't been sent yet
Filter Active Cases: Only processes nudges for youth entrepreneurs with active follow-up status
Process Each Nudge: For each due nudge, the system:
- Builds a personalized message based on the nudge type and assigned micro-action
- Determines the appropriate sending method (template vs. direct message)
- Updates the youth's conversation status to active
Send Message: Delivers the nudge via WhatsApp using either:
- Twilio Content Templates (for morning prompts outside 24-hour session window)
- Direct WhatsApp messages (for afternoon and evening check-ins)
Mark Complete: Updates the database to prevent duplicate sends and continues to the next nudge

Workflow Diagram¶

graph TD
    A[Cron Every 30m] --> B[Find Due Nudges]
    B --> C{Has Due Nudges?}
    C -->|Yes| D[Loop Over Nudges]
    C -->|No| E[End]
    D --> F[Build Nudge Message]
    F --> G[Activate This Debtor]
    G --> H{Use Template?}
    H -->|Yes| I[Send Template]
    H -->|No| J[Send WhatsApp Nudge]
    I --> K[Mark Followup Fired]
    J --> K
    K --> D
    D -->|All Done| E

Trigger¶

Schedule Trigger: Runs automatically every 30 minutes (*/30 * * * * cron expression)

Nodes Used¶

Node Type	Node Name	Purpose
Schedule Trigger	Cron Every 30m	Triggers workflow every 30 minutes
PostgreSQL	Find Due Nudges	Queries database for overdue nudges
If	Has Due Nudges?	Checks if any nudges need to be sent
Split in Batches	Loop Over Nudges	Processes each nudge individually
Code	Build Nudge Message	Creates personalized messages based on nudge type
PostgreSQL	Activate This Debtor	Updates youth's conversation status
If	Use Template?	Determines message sending method
HTTP Request	Send Template	Sends Twilio Content Template messages
Twilio	Send WhatsApp Nudge	Sends direct WhatsApp messages
PostgreSQL	Mark Followup Fired	Prevents duplicate sends

External Services & Credentials Required¶

Twilio WhatsApp¶

Service: Twilio WhatsApp Business API
Credential: twilioApi (Twilio WhatsApp kdp)
Used for: Sending direct WhatsApp messages during active session windows

Twilio HTTP API¶

Service: Twilio REST API
Credential: httpBasicAuth (Basic authentication)
Used for: Sending Content Template messages for cold outreach

PostgreSQL Database¶

Service: PostgreSQL database
Credential: postgres (sifaV4Dev)
Used for: Querying nudge schedules and updating follow-up status

Environment Variables¶

No explicit environment variables are used. Configuration is handled through: - Database connection settings in PostgreSQL credentials - Twilio account settings in API credentials - Template SID placeholder (HX_REPLACE_AFTER_TWILIO_APPROVAL) needs manual update

Data Flow¶

Input¶

Database Query Results: Youth entrepreneur records with scheduled nudges including:
- Phone numbers
- First names
- Assigned micro-actions
- Schedule signals (morning_action_prompt, today_1630_eat, today_evening_check)
- Follow-up timing information

Output¶

WhatsApp Messages: Personalized nudges sent to youth entrepreneurs
Database Updates: Follow-up status changes and completion tracking

Message Types¶

Morning Action Prompt: Uses Twilio Content Template (cold outreach)
Afternoon Check (4:30 PM): Direct message encouraging action completion
Evening Check: Direct message asking for progress update

Error Handling¶

The workflow includes basic error handling through: - Conditional Checks: Verifies nudges exist before processing - Batch Processing: Handles multiple nudges individually to prevent single failures from stopping the entire batch - Database Constraints: Relies on database-level validation for data integrity

No explicit error nodes or retry mechanisms are implemented.

Known Limitations¶

Template SID Placeholder: Morning prompts require manual update of the Twilio Content Template SID after approval
Rate Limiting: No built-in rate limiting for WhatsApp message sending
Error Recovery: Limited error handling and no automatic retry mechanisms
Batch Size: Limited to 50 nudges per execution cycle
Language: Messages are hardcoded in Swahili with no localization support

No related workflows are specified in the current context.

Setup Instructions¶

Import Workflow: Import the JSON workflow into your n8n instance
Configure Database Credential:
- Create PostgreSQL credential named sifaV4Dev
- Configure connection to your Profit Path database
Configure Twilio Credentials:
- Create Twilio API credential named Twilio WhatsApp kdp
- Create HTTP Basic Auth credential for Twilio REST API access
Update Template Configuration:
- Replace HX_REPLACE_AFTER_TWILIO_APPROVAL with your approved Twilio Content Template SID
- Ensure template variables match the expected format (firstName, microAction)
Verify Database Schema:
- Ensure tables exist: v4_profitpathHistory, v4_profitpathFollowup, v4_youthEntrepreneurs
- Verify required columns and data types match the queries
Test Execution:
- Run workflow manually to verify database connections
- Test with a small dataset before enabling the cron trigger
Activate Workflow: Enable the workflow to start automatic execution every 30 minutes