V4 - Onboarding AI

This workflow powers an AI-driven onboarding system for young entrepreneurs in Kenya, providing conversational business coaching through WhatsApp. It guides users through a structured journey to understand their business challenges, collect key metrics, and provide personalized micro-actions for growth.

Purpose

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

Based on the workflow implementation, this system appears to serve young entrepreneurs in Kenya through the Educate! Kenya program in Makueni County. The AI coach "SIFA" helps users: - Complete a structured onboarding process to understand their business - Identify their primary challenges (credit recovery, profit improvement, or other issues) - Collect baseline business metrics (sales, costs, operating hours) - Receive personalized coaching and micro-actions - Earn points for engagement that can be redeemed for airtime/data

How It Works

1. Session Context Retrieval: The workflow fetches the user's current onboarding progress and chat history from the database
2. User Record Processing: Extracts user information and contextual data for the AI prompt
3. Dynamic Prompt Building: Creates a comprehensive system prompt based on the user's current onboarding step, including conversation history and step-specific instructions
4. AI Processing: The AI agent processes the user's message using the contextual prompt and generates an appropriate response
5. Response Parsing: Extracts any step advancement signals or data capture commands from the AI response
6. Conditional Updates: If the AI indicated a step change or data capture, updates the user's record in the database
7. Output Formatting: Prepares the final response with appropriate formatting (plain text, interactive buttons, forms)
8. Chat Logging: Records the conversation turn in the chat log for future context
9. Response Delivery: Returns the formatted response to the calling system

Workflow 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
    E --> G[parseAISignal]
    G --> H[checkAdvance]
    H --> I[updateStep]
    H --> J[setOutputField]
    I --> J
    J --> K[logToChat]
    K --> L[returnFinal]

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

Trigger

Execute Workflow Trigger: This workflow is called by other workflows with three required inputs: - phoneNumber: User's phone number identifier - query: The user's message/input - channel: Communication channel (typically "Whatsapp")

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input from calling workflows
PostgreSQL	getSessionContext	Retrieves user context and chat history
Code	getUserRecord	Processes raw context data into user object
Code	buildOnboardingPrompt	Creates dynamic AI prompt based on user's current step
AI Agent	AI Agent	Processes user input and generates contextual responses
OpenRouter Chat Model	OpenRouter Chat Model	Provides AI language model (Gemini 2.5 Flash)
Code	parseAISignal	Extracts step advancement and data capture signals
If	checkAdvance	Determines if database updates are needed
PostgreSQL	updateStep	Updates user progress and captured data
Set	setOutputField	Formats output data structure
PostgreSQL	logToChat	Records conversation in chat log
Set	returnFinal	Prepares final response object
Webhook	Webhook Debug	Debug endpoint for testing
Respond to Webhook	Respond Debug	Returns debug response

External Services & Credentials Required

PostgreSQL Database

• Credential: sifaV4Dev
• Purpose: Stores user data, onboarding progress, and chat history
• Required Tables:
  • v4_youthEntrepreneurs (user profiles and progress)
  • v4_chatLog (conversation history)

OpenRouter API

• Credential: sifa_dev_env
• Purpose: Provides access to Google's Gemini 2.5 Flash model
• Model: google/gemini-2.5-flash

Environment Variables

No explicit environment variables are referenced in this workflow. Configuration is handled through: - Database credentials for PostgreSQL connection - OpenRouter API credentials for AI model access

Data Flow

Input

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

Output

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

Internal Data Processing

• User context includes onboarding step, business details, chat history
• AI responses can include step advancement signals: [ADVANCE:step_name]
• Business data capture signals: [SET:field=value] for specific fields
• All signals are stripped from user-visible output

Error Handling

• AI Agent Retry: Configured with 2 retry attempts and 2-second delays
• Empty Response Guard: Prevents blank messages from being sent to users
• Step Validation: Only allows advancement to valid, predefined onboarding steps
• Field Validation: Restricts data capture to allowed business behavior fields
• Fallback Responses: Provides network error messages when AI processing fails

Known Limitations

Based on the implementation: - Redemptions are limited to Safaricom network only (airtime/data) - AI responses are capped at 4 lines for WhatsApp compatibility - Business behavior data collection is limited to 5 specific fields - Step advancement requires exact matches to predefined step names - No support for multiple concurrent onboarding sessions per user

Related Workflows

This workflow is designed to be called by other workflows in the system, likely: - WhatsApp message handling workflows - Main routing/orchestration workflows - Message delivery workflows

Setup Instructions

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

2. Configure PostgreSQL Credentials:

   • Create credential named sifaV4Dev
   • Configure connection to your PostgreSQL database
   • Ensure required tables exist with proper schema

3. Configure OpenRouter Credentials:

   • Create credential named sifa_dev_env
   • Add your OpenRouter API key
   • Verify access to Google Gemini 2.5 Flash model

4. Database Setup:

   • Ensure get_session_context_v4() function exists in PostgreSQL
   • Verify table schemas for v4_youthEntrepreneurs and v4_chatLog
   • Set up proper indexes for phone number lookups

5. Test the Workflow:

   • Use the debug webhook endpoint for testing
   • Verify AI responses are appropriate for different onboarding steps
   • Test step advancement and data capture functionality

6. Integration:

   • Configure calling workflows to pass required input parameters
   • Ensure proper error handling in upstream workflows
   • Set up monitoring for failed executions

7. Activate: Enable the workflow once testing is complete