V4 - MenuHandler - Warenga¶

This workflow provides an interactive menu system for the SIFA coaching program, allowing users to access their micro-actions, check their points balance and streak, or resume coaching conversations. It handles menu navigation, displays personalized information, and manages redemption options while logging all interactions for context preservation.

Purpose¶

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

How It Works¶

Menu Detection: The workflow analyzes incoming user messages to determine if they're requesting the menu (keywords like "menu", "manu", "orodha") or responding to menu options
Route Classification: Based on the user's input and current menu state, it routes to one of five paths: show main menu, display actions, show points, resume coaching, or handle redemption attempts
Data Retrieval: For actions and points views, it queries the database to get the user's current micro-actions, points balance, SIFA level, and streak information
Response Formatting: Each path formats appropriate responses with interactive elements, status indicators, and personalized messaging in Swahili
State Management: The workflow updates the user's nudge step to track menu navigation state and clears it when returning to coaching
History Logging: All menu interactions are logged to the chat history table for context preservation in future conversations

Workflow Diagram¶

graph TD
    A[When Executed by Another Workflow] --> B[Detect Menu Option]
    B --> C[Menu Route]
    C --> D[Show Menu]
    C --> E[Get Actions]
    C --> F[Get Points & Streak]
    C --> G[Resume Coaching]
    C --> H[Redeem Coming Soon]
    E --> I[Format Actions]
    F --> J[Format Points]
    D --> K[Return Result]
    I --> K
    J --> K
    G --> K
    H --> K
    K --> L[Build History Log]
    L --> M[Write History]
    M --> N[Need Step Update?]
    N --> O[Set Nudge Step]
    N --> P[Final Output]
    O --> P

Trigger¶

Execute Workflow Trigger: Called by other workflows with user input parameters including phone number, query text, channel, user profile information, and current menu state.

Nodes Used¶

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflows
Code	Detect Menu Option	Analyzes user input to determine menu routing logic
Switch	Menu Route	Routes execution to appropriate menu handling path
Code	Show Menu	Generates main menu with three interactive options
Postgres	Get Actions	Retrieves user's micro-actions from database with status
Code	Format Actions	Formats action list with emojis and status tags
Postgres	Get Points & Streak	Retrieves user's points, level, and streak data
Code	Format Points	Formats points display with redemption options
Code	Resume Coaching	Generates coaching resumption message
Code	Redeem (Coming Soon)	Handles redemption attempts with placeholder message
Code	Return Result	Consolidates outputs from all menu paths
Code	Build History Log	Constructs SQL for logging menu interactions
Postgres	Write History	Logs interactions to chat history table
If	Need Step Update?	Checks if nudge step needs updating
Postgres	Set Nudge Step	Updates user's menu navigation state
Code	Final Output	Formats final response for return to caller

External Services & Credentials Required¶

PostgreSQL Database: sifaV4Dev credential required for:
- Reading micro-action history from v4_microaction_history
- Reading user data from v4_youthEntrepreneurs
- Reading streak data from v4_streaks
- Writing to chat history in n8n_chat_histories
- Updating nudge step state

Environment Variables¶

No environment variables are directly referenced in this workflow. All configuration is handled through database credentials and input parameters.

Data Flow¶

Input Parameters: - phoneNumber: User's phone number for database lookups - query: User's message text for menu option detection - channel: Communication channel (WhatsApp, SMS, etc.) - firstName: User's first name for personalization - sifaLevel: User's current SIFA level (Kifaru, Chui, Ndovu, Simba) - currentMicroAction: User's active micro-action text - currentMicroActionType: Type of current micro-action (credit/growth) - businessOwned: User's business type for personalization - lastNudgeStep: Current menu navigation state

Output: - output: Formatted message text for user display - outputType: Response format (plain, interactive, interactive_list) - outputOptions: Array of interactive button options (if applicable)

Error Handling¶

Database Connection: The Write History node is configured with continueOnFail: true to prevent menu failures if history logging fails
Missing Data: Code nodes include fallback values for missing user data (default names, business types, etc.)
Route Fallback: Unrecognized inputs default to showing the main menu

Known Limitations¶

Redemption functionality is not yet implemented - shows "coming soon" messages
Limited to 3 recent actions in the actions view
Points redemption integration with Safaricom is pending
Menu state tracking relies on database updates which could fail silently

This workflow is called by other routing workflows in the SIFA system and integrates with the broader coaching conversation flow through the chat history logging mechanism.

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Database Credential:
- Create a PostgreSQL credential named sifaV4Dev
- Configure connection to your SIFA database
- Ensure access to tables: v4_microaction_history, v4_youthEntrepreneurs, v4_streaks, n8n_chat_histories
Database Schema: Ensure required tables exist with expected columns:
- User table with points, level, nudge step tracking
- Micro-action history with status and outcome tracking
- Streak tracking with weekly calculations
- Chat history table for conversation logging
Test Integration: Verify the workflow can be called from your main routing workflow with proper input parameters
Activate Workflow: Enable the workflow for production use