V4 - HelpHandler - Warenga

An AI-powered help desk agent that provides empathetic support to young Kenyan entrepreneurs when they request assistance. The workflow automatically logs issues, provides toll-free support contact information, and manages conversation flow through an intelligent agent system.

Purpose

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

This workflow serves as a dedicated help handler for users who type "HELP" or are routed to support. It provides empathetic assistance in Sheng and Swahili, automatically logs technical issues for follow-up, and ensures users feel heard while maintaining appropriate boundaries around privacy and support escalation.

How It Works

1. Trigger Reception: The workflow receives user input including phone number, query, channel, and user profile information from another workflow
2. System Prompt Building: Creates a comprehensive AI prompt that defines SIFA as a caring support agent with specific instructions for tool usage and conversation flow
3. Help State Setting: Updates the user's status in the database to indicate they're in a help conversation
4. Issue Detection: Analyzes the incoming message to determine if it describes a specific technical issue or problem
5. Automatic Issue Logging: If an issue is detected, automatically logs it to the help requests database before the AI responds
6. AI Agent Response: The AI agent processes the conversation using chat memory, with access to two tools for logging issues and managing conversation flow
7. Output Formatting: Formats the AI response for delivery back to the user

The agent follows a structured approach: show concern, mention toll-free support (0800723611), probe empathetically while respecting privacy, log issues when shared, and gracefully exit conversations when complete.

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Build System Prompt]
    B --> C[Set Help State]
    C --> D[Issue Pre-Check]
    D --> E[Log Issue]
    E --> F[AI Agent]
    F --> G[Format Output]

    H[OpenRouter Chat Model] --> F
    I[Postgres Chat Memory] --> F
    J[logHelpIssue Tool] --> F
    K[changeNudgeStep Tool] --> F

Trigger

Execute Workflow Trigger: Activated by another workflow with the following inputs: - phoneNumber - User's phone number - query - User's message or help request - channel - Communication channel (e.g., whatsapp) - firstName - User's first name - sifaLevel - User's current level in the program - lastNudgeStep - Previous interaction step - isEmotionallyPaused - Emotional state flag - currentMicroAction - Current business action - currentMicroActionType - Type of current action - businessOwned - User's business information

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input from calling workflow
Code	Build System Prompt	Creates AI system prompt with tool instructions
Postgres	Set Help State	Updates user status to 'help' in database
Code	Issue Pre-Check	Analyzes message to detect technical issues
Postgres	Log Issue	Automatically logs detected issues to database
AI Agent	AI Agent	Main conversational AI with tool access
OpenRouter Chat Model	OpenRouter Chat Model	Google Gemini 3.5 Flash language model
Postgres Chat Memory	Postgres Chat Memory	Maintains conversation history (10 messages)
Workflow Tool	logHelpIssue	Tool for logging user-reported issues
Workflow Tool	changeNudgeStep	Tool for managing conversation flow
Code	Format Output	Formats final response for delivery
Sticky Note	Doc	Documentation and workflow notes

External Services & Credentials Required

• OpenRouter API: For AI language model access (Google Gemini 3.5 Flash)
• PostgreSQL Database: For chat memory storage and user data management
• Workflow Dependencies:
  • Issue logging workflow (ID: OCOf0X4cAbpjzESk)
  • Nudge step management workflow (ID: ROszvaG1YttsP88O)

Environment Variables

No explicit environment variables are defined in this workflow. Configuration is handled through: - OpenRouter API credentials (sifa_dev_env) - PostgreSQL database credentials (sifaV4Dev)

Data Flow

Input: - User profile data (phone, name, business info, current state) - User query or help request - Channel information

Processing: - System prompt generation with user context - Automatic issue detection and logging - AI conversation with memory and tool access - Database state updates

Output: - Formatted conversational response - Issue reference numbers (when applicable) - Updated user state in database

Error Handling

• OpenRouter Model: Configured with retry logic (3 attempts, 1.5s intervals)
• Set Help State: Continues execution even if database update fails
• Default Response: Fallback message provided if AI agent fails to respond

Known Limitations

• Maximum response length: 250 words per AI response
• Chat memory limited to 10 messages per session
• Only supports toll-free contact number: 0800723611
• Issue detection relies on keyword matching and message length heuristics

Related Workflows

• Issue Logging Workflow (OCOf0X4cAbpjzESk): Handles detailed issue logging
• Nudge Step Management (ROszvaG1YttsP88O): Manages user conversation flow states

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Credentials:
   • Set up OpenRouter API credentials with access to Google Gemini 3.5 Flash
   • Configure PostgreSQL database connection for user data and chat memory
3. Database Setup: Ensure the following tables exist:
   • v4_youthEntrepreneurs (user profiles and states)
   • v4_helprequests (issue logging)
   • Chat memory tables (created automatically by Postgres Chat Memory node)
4. Workflow Dependencies: Ensure the referenced workflows are available:
   • Issue logging workflow (OCOf0X4cAbpjzESk)
   • Nudge step management workflow (ROszvaG1YttsP88O)
5. Test Configuration: Verify the workflow responds appropriately to test help requests
6. Activate: Enable the workflow for production use

The workflow is designed to be called by other workflows in the system and should not be triggered directly by external sources.