AI Agent MESSAGE Branch

An AI-powered entrepreneurship coaching system that provides personalized guidance to young entrepreneurs through WhatsApp. The workflow processes incoming messages from coaches, routes them to appropriate handlers, and delivers AI-generated coaching responses based on a structured 15-stage pedagogical model.

Purpose

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

This workflow serves as the core messaging engine for an entrepreneurship coaching program. It enables coaches to interact with young entrepreneurs through WhatsApp, providing structured guidance through a 15-stage business development journey. The system manages coaching sessions, tracks youth progress through different entrepreneurial stages, and delivers personalized AI coaching based on identified bottlenecks and micro-actions.

How It Works

1. Message Reception: Receives WhatsApp messages via webhook from coaches
2. Phone Number Cleaning: Removes WhatsApp prefixes from phone numbers
3. Coach Validation: Verifies the sender is a registered and active coach
4. Command Classification: Uses AI to determine if the message is a command (START, STATUS, DONE) or regular message
5. Command Routing: Routes to appropriate handlers based on command type:
   • START: Initiates new coaching sessions with youth
   • STATUS: Provides youth progress reports
   • DONE: Closes active coaching sessions
   • MESSAGE: Processes regular coaching conversations
6. Session Management: Creates, tracks, and manages coaching sessions
7. AI Coaching: Delivers personalized coaching using a 15-stage pedagogical model with vector-based knowledge retrieval
8. Response Delivery: Sends AI-generated responses back via WhatsApp
9. Data Persistence: Stores conversation history and coaching progress in PostgreSQL

Workflow Diagram

graph TD
    A[Webhook Trigger] --> B[Clean Phone Numbers]
    B --> C[Get Coach Details]
    C --> D{Coach Exists?}
    D -->|No| E[Send Error Message]
    D -->|Yes| F{Coach Active?}
    F -->|No| G[Send Inactive Message]
    F -->|Yes| H[AI Command Classification]
    H --> I[Route by Command]

    I -->|START| J[Check Existing Session]
    J --> K{Session Exists?}
    K -->|Yes| L[Close Old Session]
    K -->|No| M[Lookup Youth Profile]
    L --> M
    M --> N{Youth Exists?}
    N -->|No| O[Create New Youth Profile]
    N -->|Yes| P[Create Coaching Session]
    O --> Q[Create Profile Session]
    Q --> R[Send Welcome Message]
    P --> S[Build Welcome Message]
    S --> T[Send Coaching Message]

    I -->|STATUS| U[Get Youth Profile]
    U --> V{Youth Exists?}
    V -->|No| W[Send Not Found Message]
    V -->|Yes| X[Load Bottleneck History]
    X --> Y[Build Status Response]
    Y --> Z[Send Status Message]

    I -->|DONE| AA[Lookup Active Session]
    AA --> BB{Session Active?}
    BB -->|No| CC[Send No Session Message]
    BB -->|Yes| DD[Close Session]
    DD --> EE[Send Confirmation]

    I -->|MESSAGE| FF[Check Active Session]
    FF --> GG{Session Exists?}
    GG -->|No| HH[Send No Session Error]
    GG -->|Yes| II[Load Session Data]
    II --> JJ[AI Agent Processing]
    JJ --> KK[Send AI Response]

Trigger

Webhook: POST endpoint at /coach-message that receives WhatsApp message data from Twilio with the following structure: - From: Sender's WhatsApp number (with whatsapp: prefix) - To: Recipient's WhatsApp number (with whatsapp: prefix)
- Body: Message content

Nodes Used

Node Type	Purpose
Webhook	Receives incoming WhatsApp messages
Code	Cleans phone numbers and processes data
PostgreSQL	Database operations for coaches, youth profiles, sessions, and messages
If	Conditional logic for routing and validation
Switch	Command-based routing (START/STATUS/DONE/MESSAGE)
AI Agent	Provides personalized coaching using pedagogical model
LLM Chain	Classifies message types and generates responses
Vector Store	Retrieves coaching knowledge from pedagogical model
Chat Memory	Maintains conversation context
Twilio	Sends WhatsApp responses
Workflow Tools	Calls external workflows for profile creation and bottleneck tracking
Respond to Webhook	Returns HTTP responses to webhook calls

External Services & Credentials Required

• PostgreSQL Database: Stores coaches, youth profiles, sessions, bottlenecks, and messages
• Twilio API: WhatsApp messaging service
• OpenAI API: Embeddings for vector search
• OpenRouter API: LLM access for AI agents and classification

Environment Variables

No specific environment variables are documented in the workflow configuration. Credentials are managed through n8n's credential system.

Data Flow

Input: WhatsApp message with From/To phone numbers and message body Processing: - Coach validation and session management - AI-powered command classification and routing - Personalized coaching response generation - Database updates for tracking progress

Output: - WhatsApp response messages - Updated database records for sessions, profiles, and coaching progress - HTTP responses to webhook calls

Error Handling

The workflow includes several error handling paths: - Unregistered Coach: Sends message directing to contact program coordinator - Inactive Coach: Notifies coach account is inactive - No Active Session: Prompts to start a session for MESSAGE commands - Youth Not Found: Handles cases where youth profile doesn't exist for STATUS commands - No Session to Close: Handles DONE commands when no active session exists

Known Limitations

Based on the workflow structure, potential limitations include: - Dependency on external services (Twilio, OpenAI, OpenRouter) - Single coach per session model - WhatsApp-specific message formatting requirements - Manual coach registration and activation process

Related Workflows

The workflow calls several external workflows: - updatebottleneckanddiagnoses: Records coaching bottlenecks and recommended actions - youthProfileCreationTool: Creates new youth profiles with collected information - Youth Stage: Updates youth progression through entrepreneurial stages

Setup Instructions

1. Import Workflow: Import the JSON configuration into n8n
2. Configure Credentials:
   • Set up PostgreSQL database connection
   • Configure Twilio API credentials for WhatsApp
   • Add OpenAI API key for embeddings
   • Set up OpenRouter API for LLM access
3. Database Setup: Ensure required tables exist:
   • coaches (id, phone_number, status)
   • youth_profiles (id, phone_number, name, location, business_type, current_stage)
   • coaching_sessions (id, coach_id, youth_id, status, mode, started_at, ended_at)
   • bottleneck_diagnoses (id, session_id, youth_id, stage, bottleneck_name, confidence)
   • messages (session_id, message)
   • iganga_pedagogical_model (vector storage table)
4. Upload Knowledge Base: Use the form trigger to upload pedagogical model documents
5. Configure Webhook: Set up Twilio webhook to point to the n8n webhook URL
6. Test Integration: Send test messages to verify coach validation and routing
7. Activate Workflow: Enable the workflow for production use