Trainer MVP¶

An AI-powered educational chatbot that delivers interactive entrepreneurship lessons through Telegram, featuring voice support, structured assessments, and personalized learning paths for young entrepreneurs.

Purpose¶

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

This workflow appears to be designed as an educational training system that delivers structured lessons on entrepreneurship topics (specifically "Leading a Team") through conversational AI. The system guides learners through step-by-step content delivery, interactive assessments, and provides immediate feedback to support skill development in business leadership concepts.

How It Works¶

Message Reception: The workflow listens for incoming Telegram messages from learners
Input Processing: Determines if the message is text or voice, transcribing audio when necessary
AI Processing: An AI agent (Sparky) processes the input using a predefined lesson plan and conversation memory
Response Generation: The AI generates structured responses with specific chat stages and delivery preferences
Message Routing: Based on the response type, messages are routed to appropriate Telegram output nodes
Interactive Elements: Different message types trigger different UI elements (keyboards for MCQ, True/False questions, etc.)
Loop Management: The system manages lesson progression through batched message delivery and wait states
Assessment Handling: Provides feedback on quiz answers and manages pass/fail scenarios

Workflow Diagram¶

graph TD
    A[Telegram Trigger] --> B[Start Typing]
    B --> C{Voice Message?}
    C -->|Yes| D[Download Audio]
    C -->|No| E[Extract Text]
    D --> F[OpenAI Transcribe]
    F --> G[Message Text]
    E --> G
    G --> H[AI Agent with Memory]
    H --> I[Edit Fields]
    I --> J[Split Out Responses]
    J --> K[Edit Fields1]
    K --> L[Loop Over Items]
    L --> M{Chat Stage?}
    M -->|GREETING_START/CONTINUE| N[Telegram with Course Menu]
    M -->|CONTENT_DELIVERY| O[Send Telegram Message]
    M -->|ASSESSMENT_ADMINISTER_MCQ| P[Telegram MCQ]
    M -->|ASSESSMENT_ADMINISTER_TF| Q[Telegram True/False]
    M -->|PERM_TO_CONTINUE| R[Telegram Continue Options]
    M -->|PASS| S[Pass Message]
    M -->|FAIL| T[Failure Message]
    M -->|ASSESSMENT_EVAL| O
    N --> U[Wait]
    O --> U
    P --> U
    Q --> U
    R --> U
    S --> U
    T --> U
    U --> L

Trigger¶

Telegram Trigger: Activates when users send messages (text or voice) to the configured Telegram bot. The trigger listens for all message types and processes them through the educational flow.

Nodes Used¶

Node Type	Purpose
Telegram Trigger	Receives incoming messages from Telegram users
Telegram	Sends various types of responses with custom keyboards
If	Determines if incoming message contains voice data
OpenAI (Transcribe)	Converts voice messages to text
Set	Transforms and prepares data between processing steps
AI Agent	Core conversational AI that follows lesson plans and manages learning flow
OpenAI Chat Model	Provides the language model for the AI agent
Window Buffer Memory	Maintains conversation context for personalized interactions
Switch	Routes responses based on chat stage for appropriate UI handling
Split Out	Separates multiple responses for batch processing
Split In Batches	Manages sequential delivery of multiple messages
Wait	Controls timing between message deliveries
Execute Workflow	Calls external workflow for message sending
Sticky Note	Documentation and workflow annotations

External Services & Credentials Required¶

Telegram Bot API: Requires bot token for sending/receiving messages
OpenAI API: Used for both transcription and chat completion services
PostgreSQL Database: For conversation memory storage (currently disabled)

Environment Variables¶

No explicit environment variables are defined in this workflow. Configuration is handled through n8n credential management for: - Telegram API credentials - OpenAI API credentials
- PostgreSQL database credentials

Data Flow¶

Input: - Telegram messages (text or voice) - User chat IDs for session management - Voice files for transcription

Processing: - Voice-to-text conversion when needed - AI-generated responses following structured lesson plans - Chat stage classification for appropriate UI rendering - Conversation memory for context retention

Output: - Formatted text messages via Telegram - Interactive keyboards (MCQ, True/False, navigation options) - Voice messages for content delivery - Assessment feedback and progression tracking

Error Handling¶

The workflow includes basic error handling through: - Conditional voice processing (falls back to text if no voice detected) - Switch node fallback options for unmatched chat stages - Disabled backup memory systems (PostgreSQL nodes) - Multiple parallel processing paths for redundancy

Known Limitations¶

Based on the workflow structure: - Assessment generation appears to be manual (noted in sticky notes) - Some nodes are disabled, suggesting incomplete implementation - Duplicate workflow sections indicate potential development/testing setup - Limited error recovery mechanisms for API failures

AI Trainer: Telegram Message Send - Referenced as an external workflow for message delivery
Assessment generation workflows (mentioned in sticky notes but not implemented)

Setup Instructions¶

Import Workflow: Import the JSON workflow into your n8n instance
Configure Credentials:
- Set up Telegram Bot API credentials with your bot token
- Configure OpenAI API credentials with appropriate access
- Optionally configure PostgreSQL for persistent memory
Telegram Bot Setup:
- Create a Telegram bot via @BotFather
- Configure webhook URL to point to your n8n Telegram trigger
Test Configuration:
- Send a test message to your bot
- Verify voice message transcription works
- Test the lesson flow and interactive elements
Customize Content:
- Modify the lesson plan JSON in the AI Agent system message
- Adjust response templates and keyboard options
- Configure assessment questions and scoring logic
Deploy:
- Activate the workflow
- Monitor execution logs for any issues
- Scale based on user load requirements