V4 - EmotionalSupportHandler - Warenga¶

An AI-powered emotional support system that provides empathetic crisis intervention for young Kenyan entrepreneurs. This workflow detects emotional distress in user messages, applies appropriate safety measures, and delivers culturally-sensitive support responses in Sheng and Swahili.

Purpose¶

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

This workflow serves as a critical safety net for young entrepreneurs (18-35) who may be experiencing emotional distress, mental health crises, or safety threats. It automatically detects severity levels of emotional situations and takes appropriate action, from gentle acknowledgment to emergency alerts and program pauses. The system ensures vulnerable users receive immediate support while protecting them from additional business pressure during difficult times.

How It Works¶

Trigger Reception: The workflow receives user messages along with their profile information from other workflows
System Prompt Building: Creates a comprehensive AI prompt that includes severity guidelines, tool usage instructions, and cultural context
Severity Pre-Check: Analyzes the incoming message for critical keywords to determine emotional distress level
Database Updates: Automatically pauses users and logs events for medium to critical severity situations
AI Agent Processing: The AI agent processes the message using conversation memory and available tools
Tool Execution: Based on the situation, the agent may pause/unpause users or trigger emergency alerts
Response Formatting: Formats the AI's empathetic response for delivery back to the user

The system operates on four severity tiers: - CRITICAL: Safety threats, GBV, suicidal thoughts → Emergency alert + pause - HIGH: Bereavement, family loss → Pause with grief support - MEDIUM: Illness, depression, emotional distress → Pause with health support
- LOW: General frustration, practical issues → Acknowledgment only

Mermaid Diagram¶

graph TD
    A[When Executed by Another Workflow] --> B[Build System Prompt]
    B --> C[Severity Pre-Check]
    C --> D[Apply Pause]
    D --> E[AI Agent]
    E --> F[Format Output]

    G[OpenRouter Chat Model] --> E
    H[Postgres Chat Memory] --> E
    I[pauseUser Tool] --> E
    J[unpauseUser Tool] --> E
    K[triggerCeaAlert Tool] --> E

Trigger¶

Execute Workflow Trigger - Called by other workflows in the system when emotional support is needed.

Required Inputs: - phoneNumber - User's phone number for identification - query - The user's message that may contain emotional distress - channel - Communication channel (typically WhatsApp) - firstName - User's first name for personalization - isCurrentlyPaused - Whether user is already emotionally paused - emotionalPauseReason - Reason for current pause (if applicable)

Nodes Used¶

Node Type	Purpose
Execute Workflow Trigger	Receives inputs from calling workflows
Code (Build System Prompt)	Creates comprehensive AI instructions with severity guidelines
Code (Severity Pre-Check)	Analyzes message for emotional distress keywords
Postgres	Updates user pause status and logs emotional events
AI Agent	Processes messages with empathy and cultural sensitivity
OpenRouter Chat Model	Provides AI language processing via Gemini 3.5 Flash
Postgres Chat Memory	Maintains conversation context (10 messages)
Workflow Tool (pauseUser)	Pauses users from business coaching during distress
Workflow Tool (unpauseUser)	Resumes users when emotionally ready
Workflow Tool (triggerCeaAlert)	Alerts Community Education Ambassadors for crises
Code (Format Output)	Formats final response for delivery
Sticky Note	Documentation and architecture notes

External Services & Credentials Required¶

OpenRouter API (sifa_dev_env) - Used for AI language model access - Requires API key for Gemini 3.5 Flash model

PostgreSQL Database (sifaV4Dev) - Stores conversation memory and user pause states - Manages emotional events and CEA alerts - Requires database connection credentials

Environment Variables¶

No explicit environment variables are defined in this workflow. Configuration is handled through n8n credentials and node parameters.

Data Flow¶

Input:

{
  "phoneNumber": "string",
  "query": "string", 
  "channel": "string",
  "firstName": "string",
  "isCurrentlyPaused": "boolean",
  "emotionalPauseReason": "string"
}

Output:

{
  "output": "string",
  "outputType": "plain",
  "outputOptions": []
}

The output contains an empathetic response in Sheng/Swahili that: - Acknowledges the user's emotional state - Provides appropriate support resources (0800723611 toll-free number) - Uses culturally appropriate language and tone - Never mentions internal tool usage or system actions

Error Handling¶

OpenRouter Model: Configured with retry logic (3 attempts, 1.5s intervals)
Fallback Response: If AI processing fails, returns default support message with crisis hotline
Database Errors: Workflow continues even if pause updates fail, prioritizing user response
Tool Failures: AI agent can still provide emotional support even if tools don't execute

Known Limitations¶

Keyword-based severity detection may miss nuanced emotional expressions
Limited to Sheng/Swahili cultural context
Relies on single toll-free number (0800723611) for crisis support
10-message conversation memory limit may lose important context
No direct integration with professional mental health services

This workflow calls three sub-workflows as tools: - pauseUser (ID: QRZ8XODNwWJyBNqr) - Manages user pause states - unpauseUser (ID: 8UM42XWgJtHSiVpR) - Resumes users from pause - triggerCeaAlert (ID: 18JMmGhWiZKvjhS8) - Sends crisis alerts to Community Education Ambassadors

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Credentials:
- Set up OpenRouter API credentials with access to Gemini 3.5 Flash
- Configure PostgreSQL database connection for conversation memory and user data
Update Tool References: Ensure the three workflow tool nodes point to correct workflow IDs in your environment
Database Setup: Ensure these tables exist:
- v4_youthEntrepreneurs - User profiles and pause states
- v4_ceaalerts - Crisis alert logging
- v4_emotionalevents - Emotional event tracking
- Chat memory tables (created automatically by Postgres Chat Memory node)
Test Integration: Verify the workflow can be called by your main conversation flows
Crisis Support: Confirm the toll-free number (0800723611) is active and appropriate for your region
Activate Workflow: Enable the workflow to start receiving emotional support requests