AI Agent MESSAGE Branch copy

This workflow processes WhatsApp messages from coaches in an entrepreneurship coaching program, routing different command types (START, STATUS, DONE, MESSAGE) to appropriate handlers and facilitating AI-powered coaching conversations with youth participants through a structured 15-stage pedagogical model.

Purpose

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

How It Works

1. Message Reception: Receives WhatsApp messages via Twilio webhook and cleans phone number formatting
2. Coach Validation: Verifies the sender is a registered, active coach in the system
3. Command Classification: Uses AI to determine if the message is a command (START, STATUS, DONE) or a regular MESSAGE
4. Command Routing: Routes different command types to specialized handlers:
   • START: Creates new coaching sessions and youth profiles
   • STATUS: Provides status reports on youth progress and bottlenecks
   • DONE: Closes active coaching sessions
   • MESSAGE: Processes regular coaching conversations through AI agent
5. Session Management: Manages active coaching sessions, handles session transitions, and maintains conversation history
6. AI Coaching: For MESSAGE commands, engages an AI agent trained on a 15-stage entrepreneurship pedagogical model to provide structured coaching
7. Response Delivery: Sends appropriate WhatsApp responses back to coaches via Twilio

Workflow Diagram

graph TD
    A[Postman Endpoint] --> B[Clean Phone Number]
    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[Basic LLM Chain]
    H --> I[Route by Command]

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

    I -->|STATUS| V[Get Youth Profile]
    V --> W{Youth Exists?}
    W -->|No| X[Send Error]
    W -->|Yes| Y[Load Bottlenecks]
    Y --> Z[Build Status Response]
    Z --> AA[Send Status]

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

    I -->|MESSAGE| GG[Check Active Session]
    GG --> HH{Session Exists?}
    HH -->|No| II[Send No Session Error]
    HH -->|Yes| JJ[Set Session ID]
    JJ --> KK[AI Agent]
    KK --> LL[Send AI Response]

Trigger

Webhook Trigger: Postman Endpoint that receives HTTP POST requests from Twilio when WhatsApp messages are sent to the coaching number.

Nodes Used

Node Type	Purpose
Webhook	Receives incoming WhatsApp messages from Twilio
Code	Cleans phone number formatting and data processing
Postgres	Database operations for coaches, youth profiles, sessions, and messages
If	Conditional logic for routing and validation
Switch	Routes messages based on command type classification
Twilio	Sends WhatsApp responses back to coaches
AI Agent	Provides structured entrepreneurship coaching using pedagogical model
LLM Chain	Classifies incoming messages as commands or regular messages
Vector Store	Stores and retrieves pedagogical model knowledge
Memory	Maintains conversation history for coaching sessions
Set	Prepares data for downstream nodes
Form Trigger	Allows file uploads for knowledge base management

External Services & Credentials Required

• Twilio: For WhatsApp messaging
  • Account SID and Auth Token
  • WhatsApp-enabled phone number
• PostgreSQL: Database for storing all application data
  • Connection credentials (host, port, database, username, password)
• OpenRouter: AI model access
  • API key for language model services
• OpenAI: Embeddings for vector storage
  • API key for embedding generation

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 webhook payload containing: - Message body text - Sender phone number (coach) - Recipient number - Message metadata

Processing: - Coach validation and session management - Command classification and routing - AI-powered coaching conversations - Database updates for sessions, profiles, and messages

Output: WhatsApp response messages containing: - Coaching guidance and questions - Status reports - Session confirmations - Error messages

Error Handling

The workflow includes several error handling paths: - Invalid or inactive coaches receive error messages - Missing youth profiles trigger creation flows - Non-existent sessions prevent message processing - Database connection issues are handled with alwaysOutputData flags - Fallback responses for unrecognized commands

Known Limitations

No specific limitations are documented in the provided context.

Related Workflows

The workflow references several sub-workflows: - updatebottleneckanddiagnoses - Records coaching bottleneck diagnoses - youthProfileCreationTool - Creates new youth profiles - Youth Stage - Updates youth progression stages

Setup Instructions

1. Import Workflow: Import the JSON configuration into your n8n instance
2. Configure Credentials:
   • Set up Twilio credentials with WhatsApp-enabled number
   • Configure PostgreSQL database connection
   • Add OpenRouter API credentials
   • Add OpenAI API credentials for embeddings
3. Database Setup: Ensure PostgreSQL tables exist for:
   • coaches - Coach information and status
   • youth_profiles - Youth participant data
   • coaching_sessions - Active and completed sessions
   • bottleneck_diagnoses - Coaching progress tracking
   • messages - Conversation history
   • iganga_pedagogical_model - Vector storage for coaching knowledge
4. Knowledge Base: Upload pedagogical model documents via the form trigger to populate the vector store
5. Webhook Configuration: Configure Twilio webhook URL to point to the workflow's webhook endpoint
6. Test: Send test WhatsApp messages to verify coach validation and command routing
7. Deploy: Activate the workflow for production use