AI Agent MESSAGE Branch

This workflow implements an AI-powered entrepreneurship coaching system that processes WhatsApp messages from coaches to provide structured guidance to young entrepreneurs. The system routes different types of commands (START, STATUS, DONE, MESSAGE) and manages coaching sessions through a 15-stage pedagogical model, handling everything from youth profile creation to bottleneck diagnosis and micro-action recommendations.

Purpose

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

Based on the workflow implementation, this system serves: - Coaches who need to manage entrepreneurship coaching sessions via WhatsApp - Young entrepreneurs receiving structured guidance through a pedagogical framework - Program coordinators overseeing coaching programs and youth development

The workflow ensures coaches can initiate sessions, check youth status, close sessions, and engage in AI-powered coaching conversations that follow a specific 15-stage entrepreneurial development model.

How It Works

1. Message Reception: Receives WhatsApp messages via Twilio webhook from coaches
2. Coach Validation: Verifies the sender is a registered and 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 to appropriate handlers based on command type:
   • START: Creates new youth profiles and coaching sessions
   • STATUS: Provides youth progress reports and bottleneck history
   • DONE: Closes active coaching sessions
   • MESSAGE: Engages AI coaching agent for conversation
5. Session Management: Handles session creation, validation, and closure with proper database updates
6. AI Coaching: For MESSAGE commands, the AI agent provides structured coaching using a 15-stage pedagogical model
7. Response Delivery: Sends appropriate WhatsApp responses back to coaches via Twilio

Workflow Diagram

graph TD
    A[WhatsApp Message Received] --> 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[AI Command Classification]
    H --> I[Route by Command]

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

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

    I -->|DONE| BB[Lookup Active Session]
    BB --> CC{Session Exists?}
    CC -->|No| DD[Send No Session Message]
    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[Load Session Context]
    JJ --> KK[AI Agent Processing]
    KK --> LL[Send AI Response]

Trigger

Webhook Trigger: POST endpoint at /coach-message that receives WhatsApp messages from Twilio. The webhook expects Twilio's standard message format including sender phone number, recipient, and message body.

Nodes Used

Node Type	Purpose
Webhook	Receives incoming WhatsApp messages from Twilio
Code	Cleans phone numbers and normalizes formats
Postgres	Database operations for coaches, youth profiles, sessions, and bottlenecks
If	Conditional logic for routing and validation
Switch	Command routing based on message type
AI Agent	Provides structured entrepreneurship coaching
LLM Chain	Classifies message commands using AI
Vector Store	Retrieves pedagogical model information
Chat Memory	Maintains conversation context
Twilio	Sends WhatsApp responses
Workflow Tools	Calls sub-workflows for profile creation and bottleneck updates
Respond to Webhook	Returns HTTP responses to Twilio

External Services & Credentials Required

Required Credentials

• Postgres Database: For storing coach, youth, session, and bottleneck data
• Twilio API: For WhatsApp message sending and receiving
• OpenRouter API: For AI language model access
• OpenAI API: For text embeddings in vector store

External Services

• Twilio WhatsApp Business API: Message handling
• PostgreSQL Database: Data persistence
• OpenRouter: AI model access (Anthropic Claude, Google Gemini)
• OpenAI: Embeddings for knowledge retrieval

Environment Variables

The workflow requires database connection details and API credentials to be configured in n8n's credential management system. No specific environment variables are exposed in the workflow configuration.

Data Flow

Input

• WhatsApp messages via Twilio webhook containing:
  • Sender phone number (coach)
  • Message body (command or conversation)
  • Twilio metadata

Processing

• Coach validation and authorization
• Command classification and routing
• Session management and state tracking
• AI-powered coaching conversations
• Database updates for profiles, sessions, and progress

Output

• WhatsApp responses sent back to coaches
• Database records updated with session data
• Bottleneck diagnoses and micro-action recommendations
• Session status and youth progress reports

Error Handling

The workflow includes several error handling paths:

• Unregistered Coach: Sends message directing to program coordinator
• Inactive Coach: Notifies coach of account status
• Youth Not Found: Informs coach when STATUS command references unknown youth
• No Active Session: Prevents MESSAGE commands without valid sessions
• Session Conflicts: Automatically closes old sessions when starting new ones

All error paths include appropriate WhatsApp responses and webhook acknowledgments to prevent message delivery failures.

Known Limitations

Based on the workflow implementation: - Limited to WhatsApp communication channel only - Requires manual coach registration in database - Single active session per coach limitation - Phone number normalization assumes Uganda format (+256) as default - AI responses limited to 100 words for WhatsApp compatibility

Related Workflows

The workflow calls several sub-workflows: - updatebottleneckanddiagnoses: Records bottleneck diagnoses and micro-actions - youthProfileCreationTool: Creates new youth profiles with collected data - Youth Stage: Updates youth progression stages in the pedagogical model

Setup Instructions

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

2. Configure Credentials:

   • Set up Postgres database connection
   • Configure Twilio API credentials
   • Add OpenRouter API key
   • Add OpenAI API key for embeddings

3. Database Setup: Ensure tables exist for:

   • coaches (phone_number, status, etc.)
   • youth_profiles (phone_number, name, location, business_type, current_stage)
   • coaching_sessions (coach_id, youth_id, status, mode, etc.)
   • bottleneck_diagnoses (session_id, youth_id, bottleneck_name, etc.)
   • messages (session_id, message content for chat memory)

4. Twilio Configuration:

   • Set webhook URL to your n8n instance: https://your-n8n.com/webhook/coach-message
   • Configure WhatsApp Business API

5. Upload Pedagogical Model: Use the form trigger to upload the 15-stage entrepreneurship model documents to the vector store

6. Test Setup:

   • Register test coaches in database
   • Send test messages to verify routing
   • Validate AI responses and database updates

7. Activate Workflow: Enable the workflow to start processing messages