V4 - Onboarding AI - Review Copy

This workflow powers an AI-driven onboarding system for young entrepreneurs in Kenya, guiding them through a structured conversation to capture business data, identify challenges, and provide personalized coaching recommendations through WhatsApp.

Purpose

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

Based on the workflow implementation, this appears to be part of the SIFA (business coaching) program targeting young entrepreneurs in Makueni County, Kenya. The system conducts onboarding conversations in Swahili, Sheng, and English to:

• Capture personal motivation and business goals
• Collect detailed business operational data
• Identify primary challenges (credit recovery, profit optimization, or other issues)
• Provide tailored micro-actions and coaching recommendations
• Award points that can be redeemed for airtime or data bundles
• Route users to appropriate coaching tracks based on their needs

How It Works

1. Session Context Retrieval: Loads the user's current onboarding progress and chat history from the database
2. User Record Processing: Extracts user information and context for personalized responses
3. Dynamic Prompt Building: Constructs a comprehensive AI prompt based on the user's current onboarding step and conversation history
4. AI Conversation: Processes the user's message through an AI agent that follows structured onboarding stages
5. Response Parsing: Extracts the AI response and checks for step advancement signals
6. Step Management: Updates the user's onboarding progress if advancement is detected
7. Chat Logging: Records the conversation exchange in the database
8. Response Formatting: Prepares the final response with appropriate formatting and interactive options

The onboarding follows a multi-module structure (M1-M5) covering welcome, personal motivation, business data collection, challenge identification, insights delivery, and program completion.

Mermaid Diagram

graph TD
    A[When Executed by Another Workflow] --> B[getSessionContext]
    B --> C[getUserRecord]
    C --> D[buildOnboardingPrompt]
    D --> E[AI Agent]
    F[OpenRouter Chat Model] --> E
    G[Postgres Chat Memory] --> E
    E --> H[parseAISignal]
    H --> I[checkAdvance]
    I --> J[updateStep]
    I --> K[setOutputField]
    J --> K
    K --> L[logToChat]
    L --> M[returnFinal]

    N[Webhook Debug] --> O[Respond Debug]

Trigger

Execute Workflow Trigger: Accepts incoming requests with: - phoneNumber: User's phone number for session identification - query: The user's message text - channel: Communication channel (typically "Whatsapp")

Nodes Used

Node Type	Purpose
Execute Workflow Trigger	Receives incoming requests from parent workflows
Postgres (getSessionContext)	Retrieves user session data and chat history
Code (getUserRecord)	Processes and structures user information
Code (buildOnboardingPrompt)	Builds dynamic AI prompts based on onboarding stage
AI Agent	Processes conversations using structured prompts
OpenRouter Chat Model	Provides GPT-5.2 language model capabilities
Postgres Chat Memory	Manages conversation memory (currently disabled)
Code (parseAISignal)	Extracts responses and advancement signals
If (checkAdvance)	Determines if onboarding step should advance
Postgres (updateStep)	Updates user's onboarding progress
Set (setOutputField)	Formats output data structure
Postgres (logToChat)	Records conversation in chat log
Set (returnFinal)	Prepares final response format
Webhook (Debug)	Development testing endpoint
Respond to Webhook	Returns debug responses

External Services & Credentials Required

Required Credentials:

• PostgreSQL Database (sifaV4Dev): Stores user data, session context, and chat logs
• OpenRouter API (sifa_dev_env): Provides access to GPT-5.2 language model

Database Tables:

• v4_youthEntrepreneurs: User profiles and onboarding progress
• v4_chatLog: Conversation history storage
• Chat memory tables (for Postgres Chat Memory if enabled)

Environment Variables

No explicit environment variables are configured in this workflow. Configuration is handled through: - Database connection credentials - OpenRouter API credentials - Workflow execution context

Data Flow

Input:

{
  "phoneNumber": "+254707060397",
  "query": "user message text",
  "channel": "Whatsapp"
}

Output:

{
  "output": "AI response text",
  "outputType": "plain|interactive",
  "outputOptions": ["button1", "button2"] // if interactive
}

Internal Data Processing:

• User session context and chat history
• Dynamic AI prompts based on onboarding stage
• Step advancement signals ([ADVANCE:step_name])
• Business data collection (sales, costs, credit information)
• Points and rewards tracking

Error Handling

The workflow includes basic error handling through: - Conditional step advancement (prevents invalid state transitions) - Data validation in prompt building - Fallback responses for unclear user inputs - Guardrails for scope limitations (loan requests, welfare concerns)

No explicit error nodes are implemented - errors would propagate to the calling workflow.

Known Limitations

Based on the implementation: - Chat memory is currently disabled (Postgres Chat Memory node) - Limited to specific onboarding flow - not suitable for general conversations - Requires specific database schema and functions - Hardcoded to Kenyan context and languages (Swahili, Sheng, English) - Step advancement is one-way only (no backward navigation)

Related Workflows

This workflow is designed to be called by other workflows that handle: - WhatsApp message routing - User authentication and registration - Message delivery and formatting - Integration with external communication platforms

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance

2. Configure Database Connection:

   • Set up PostgreSQL credentials named sifaV4Dev
   • Ensure required tables exist: v4_youthEntrepreneurs, v4_chatLog
   • Implement the get_session_context_v4() database function

3. Configure AI Service:

   • Set up OpenRouter API credentials named sifa_dev_env
   • Ensure access to GPT-5.2 model

4. Database Schema Requirements:

   -- Ensure these columns exist in v4_youthEntrepreneurs
   ALTER TABLE v4_youthEntrepreneurs ADD COLUMN IF NOT EXISTS currentOnboardingStep TEXT;
   ALTER TABLE v4_youthEntrepreneurs ADD COLUMN IF NOT EXISTS ceaAlertTimestamp TIMESTAMP;
   ALTER TABLE v4_youthEntrepreneurs ADD COLUMN IF NOT EXISTS ceaAlertReason TEXT;
   ALTER TABLE v4_youthEntrepreneurs ADD COLUMN IF NOT EXISTS ceaEngagementStatus TEXT;
   

5. Test the Workflow:

   • Use the debug webhook endpoint for testing
   • Send test messages with various onboarding steps
   • Verify database updates and chat logging

6. Integration:

   • Call this workflow from your main message routing workflow
   • Pass required parameters: phoneNumber, query, channel
   • Handle the returned response format in your delivery system