V4 - MiddayPeerTipHandler - Warenga

This workflow handles midday engagement responses from youth entrepreneurs in the SIFA coaching program. It processes user replies to midday check-ins, provides contextual coaching responses using AI, and awards engagement points to encourage continued participation.

Purpose

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

Based on the workflow structure, this appears to serve youth entrepreneurs participating in a coaching program by: - Processing their midday engagement responses - Providing personalized coaching based on their business context and current micro-actions - Detecting emotional distress and routing to appropriate support - Awarding points to gamify engagement and maintain motivation

How It Works

1. Receive Input: The workflow is triggered by another workflow with a phone number, user query, and communication channel
2. Fetch Context: Retrieves comprehensive user data including profile information, current micro-actions, available peer tips, recent profit data, and credit status
3. Process Reply: Analyzes the user's response and checks for emotional distress keywords in multiple languages (Swahili and English)
4. Route Response: If emotional distress is detected, routes to specialized emotional support; otherwise continues with standard coaching flow
5. Generate Coaching: Calls an AI coaching agent with midday-specific prompts and user context to generate personalized responses
6. Merge Output: Combines AI-generated response with fallback messaging, prioritizing AI when available
7. Award Points: Grants 5 engagement points for midday participation to encourage continued engagement
8. Return Result: Delivers the final response with appropriate formatting and options

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Get Midday Context]
    B --> C[Process Reply]
    C --> D{Emotional?}
    D -->|Yes| E[Call EmotionalSupportHandler]
    D -->|No| F[Call CoachingAgent]
    E --> I[Return Result]
    F --> G[Merge Output]
    G --> H[Award 5pts Midday]
    H --> I

Trigger

Execute Workflow Trigger: This workflow is called by other workflows in the system, expecting three input parameters: - phoneNumber: User's phone number for identification - query: The user's response text - channel: Communication channel (SMS, WhatsApp, etc.)

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input from calling workflows
Postgres	Get Midday Context	Fetches user profile, micro-actions, tips, and business data
Code	Process Reply	Analyzes response, detects emotions, prepares coaching context
If	Emotional?	Routes based on emotional distress detection
Execute Workflow	Call EmotionalSupportHandler	Handles distressed users with specialized support
Execute Workflow	Call CoachingAgent	Generates AI-powered coaching responses
Code	Merge Output	Combines AI and fallback responses intelligently
Execute Workflow	Award 5pts Midday	Grants engagement points for participation
Code	Return Result	Formats final output for delivery

External Services & Credentials Required

• PostgreSQL Database: sifaV4Dev credential for accessing user data, tips, profit tracking, and credit information
• EmotionalSupportHandler Workflow: ID RbLs1LNSKF4BY9fi for crisis intervention
• CoachingAgent Workflow: ID Bz0GPL2vYbDw8ygf for AI-powered coaching responses
• Points System Workflow: ID JmJObsTea34h5bjX for awarding engagement points

Environment Variables

No explicit environment variables are used in this workflow. Configuration is handled through: - Database credentials stored in n8n credential system - Workflow IDs hardcoded in Execute Workflow nodes - Emotional keywords defined in the Process Reply code node

Data Flow

Input:

{
  "phoneNumber": "string",
  "query": "string", 
  "channel": "string"
}

Output:

{
  "output": "string (response message)",
  "outputType": "string (plain/buttons/etc)",
  "outputOptions": "array (for interactive responses)"
}

Internal Data: - User profile with business type, SIFA level, and current micro-actions - Available peer tips filtered by business type - Recent profit tracking data - Credit module status and locked amounts - Emotional distress indicators and routing decisions

Error Handling

The workflow includes several error handling mechanisms: - Database Query Failures: Falls back to default values if user data cannot be retrieved - JSON Parsing Errors: Uses try-catch blocks when parsing complex database fields - AI Service Failures: Merge Output node falls back to deterministic messages if CoachingAgent fails - Missing Data: Default values provided for all user profile fields - Workflow Call Failures: Return Result node handles cases where either emotional support or coaching paths fail

Known Limitations

Based on the workflow structure: - Emotional keyword detection is limited to predefined terms in Swahili and English - AI coaching responses depend on external service availability - Points are awarded regardless of response quality or engagement depth - No validation of phone number format or user existence before processing

Related Workflows

• EmotionalSupportHandler (RbLs1LNSKF4BY9fi): Provides crisis intervention and emotional support
• CoachingAgent (Bz0GPL2vYbDw8ygf): AI-powered coaching response generation
• Points System (JmJObsTea34h5bjX): Manages user engagement scoring and rewards

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Database: Set up PostgreSQL credential named sifaV4Dev with access to:
   • v4_youthEntrepreneurs table
   • v4_microaction_history table
   • v4_peertips table
   • v4_dailyProfitTracking table
   • v4_creditTracking table
3. Deploy Dependencies: Ensure these workflows are deployed and active:
   • EmotionalSupportHandler (ID: RbLs1LNSKF4BY9fi)
   • CoachingAgent (ID: Bz0GPL2vYbDw8ygf)
   • Points System (ID: JmJObsTea34h5bjX)
4. Test Integration: Verify the workflow can be called by other workflows with proper input format
5. Monitor Performance: Check that AI coaching responses are generated successfully and fallbacks work when needed
6. Customize Keywords: Update emotional distress keywords in the Process Reply node for your target languages and context