V4 - OrganicAIInterpreter

This workflow serves as an intelligent conversation interpreter for SIFA's organic onboarding flow, using AI to understand and respond to youth who message the platform organically (not through pre-registration). It analyzes user messages at each stage of the onboarding journey and decides whether to advance to the next step or retain the user at their current stage for clarification.

Purpose

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

This workflow appears to be part of SIFA (a business coaching service by Educate! Kenya) that handles organic lead qualification. When youth reach out spontaneously via WhatsApp, this interpreter guides them through a structured onboarding process, collecting key information like referral source, business details, location, and communication preferences. The AI ensures conversations stay on track while maintaining a warm, respectful tone and protecting against spam or injection attempts.

How It Works

1. Receives Input: The workflow is triggered by another workflow with user message details including phone number, current onboarding step, and the user's message
2. Fetches Context: Retrieves the last 5 conversation messages from the database to understand the conversation history
3. Builds AI Prompt: Creates a comprehensive system prompt that includes the user's identity as SIFA, the current onboarding stage, conversation history, and specific interpretation rules for that stage
4. AI Interpretation: Uses an AI agent with GPT-5.2 to analyze the user's message and determine the appropriate response and next action
5. Parses Decision: Extracts the AI's decision (advance or retain), next step, and normalized value from the response
6. Logs Interaction: Records the interpretation and decision in the chat history database
7. Returns Result: Provides the final decision, next step, normalized value, and user-facing reply

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[fetchRecentHistory]
    B --> C[buildInterpreterPrompt]
    C --> D[AI Agent]
    E[OpenRouter Chat Model] --> D
    D --> F[parseDecision]
    F --> G[logInterpretation]
    G --> H[returnFinal]

Trigger

Execute Workflow Trigger: This workflow is called by other workflows and expects the following inputs: - phoneNumber: The user's phone number - currentStep: Current stage in the onboarding flow (e.g., "awaiting_1.2") - expectedShape: Expected response format (unused in current implementation) - userMessage: The user's actual message text - firstName: User's first name for personalization

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input parameters from calling workflow
Postgres	fetchRecentHistory	Retrieves last 5 conversation messages for context
Code	buildInterpreterPrompt	Constructs detailed AI system prompt with stage-specific rules
AI Agent	AI Agent	Processes user message and generates response with decision tokens
OpenRouter Chat Model	OpenRouter Chat Model	Provides GPT-5.2 language model for AI agent
Code	parseDecision	Extracts decision, next step, and value from AI response
Postgres	logInterpretation	Records the interaction in chat history database
Set	returnFinal	Formats final output for calling workflow

External Services & Credentials Required

• PostgreSQL Database: Stores conversation history and user data
  • Credential: sifaV4Dev
  • Tables: v4_organic_chat_history
• OpenRouter API: Provides access to GPT-5.2 language model
  • Credential: sifa_dev_env
  • Model: openai/gpt-5.2

Environment Variables

No explicit environment variables are referenced in this workflow. Configuration is handled through n8n credentials.

Data Flow

Input: - Phone number (string) - Current onboarding step (string) - User message (string, sanitized and truncated to 600 chars) - First name (string) - Expected shape (string, unused)

Output: - decision: "advance" or "retain" - nextStep: Next onboarding stage (if advancing) - normalizedValue: Standardized user response value - replyToUser: Clean message to send back to user

Error Handling

The workflow includes several protective measures: - Anti-injection Protection: Filters out control tokens and system commands from user messages - Input Sanitization: Removes system tags and limits message length - Graceful Degradation: Handles unknown onboarding steps with generic responses - Database Error Tolerance: Uses COALESCE to handle empty conversation history

Known Limitations

Based on the implementation: - English-only responses (Swahili explicitly disabled for organic prospects) - Maximum 3 WhatsApp lines per response - Limited to 600 characters of user input - Requires specific token format for decision parsing - No explicit error recovery for AI service failures

Related Workflows

This workflow is designed to be called by other workflows in the SIFA V4 system, likely including: - Main organic onboarding orchestrator - WhatsApp message handlers - Lead qualification workflows

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Database Credential:
   • Create PostgreSQL credential named sifaV4Dev
   • Ensure access to v4_organic_chat_history table
3. Configure OpenRouter Credential:
   • Create OpenRouter API credential named sifa_dev_env
   • Ensure access to GPT-5.2 model
4. Database Schema: Ensure the following table exists:

   CREATE TABLE v4_organic_chat_history (
     "phoneNumber" VARCHAR,
     "currentStep" VARCHAR,
     "role" VARCHAR,
     "content" TEXT,
     "interpretedAs" VARCHAR,
     "decision" VARCHAR,
     "createdAt" TIMESTAMP DEFAULT NOW()
   );
   

5. Test Integration: Verify the workflow can be called by other workflows with the expected input parameters
6. Activate Workflow: Enable the workflow to accept execution requests