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 creates an intelligent training system that guides students through entrepreneurship education modules via Telegram. The system delivers the "Leading a Team" curriculum through an AI agent named "Sparky" who provides interactive lessons, assessments, and feedback in a conversational format. Students can interact using text or voice messages, and the system adapts its responses based on their progress through structured lesson plans.

How It Works¶

Message Reception: A student sends a text or voice message to the Telegram bot
Input Processing: The system detects if the message is voice or text, transcribing voice messages using OpenAI's speech-to-text
AI Processing: The message is sent to an AI agent (Sparky) that follows a structured lesson plan for "Leading a Team" education
Response Generation: The AI generates structured responses with specific chat stages (content delivery, assessments, evaluations)
Message Routing: Based on the response type, the system routes to appropriate Telegram message formats (text, voice, multiple choice, true/false)
Sequential Delivery: Multiple messages from a single AI response are sent in sequence with timing delays
Loop Continuation: The system waits for the next student input and continues the educational flow

Workflow Diagram¶

graph TD
    A[Telegram Trigger] --> B[Start Typing Indicator]
    B --> C{Voice Message?}
    C -->|Yes| D[Download Audio]
    C -->|No| E[Extract Text]
    D --> F[OpenAI Transcription]
    F --> G[Format Text]
    E --> G
    G --> H[AI Agent - Sparky]
    I[OpenAI Chat Model] --> H
    J[Window Buffer Memory] --> H
    H --> K[Parse JSON Response]
    K --> L[Split Messages]
    L --> M[Loop Through Messages]
    M --> N{Message Type?}
    N -->|Greeting/Content| O[Send via Message Service]
    N -->|MCQ Assessment| P[Send Multiple Choice]
    N -->|True/False| Q[Send True/False]
    N -->|Pass/Fail| R[Send Result Message]
    O --> S[Wait Node]
    P --> S
    Q --> S
    R --> S
    S --> M

Trigger¶

Telegram Trigger: Activates when users send messages to the configured Telegram bot. Supports both text and voice messages.

Nodes Used¶

Node Type	Purpose
Telegram Trigger	Receives incoming messages from Telegram users
Telegram (Send)	Sends various message types back to users with custom keyboards
If Node	Determines if incoming message is voice or text
OpenAI (Transcription)	Converts voice messages to text
AI Agent	Core educational logic using Sparky persona with structured lesson plans
OpenAI Chat Model	Provides GPT-4 language model for AI agent
Window Buffer Memory	Maintains conversation context for each user session
Set Nodes	Data transformation and field mapping
Switch Node	Routes messages based on chat stage (content, assessment, evaluation)
Split Out	Separates multiple messages from single AI response
Split in Batches	Processes multiple messages sequentially
Wait Node	Adds delays between message deliveries
Execute Workflow	Calls external message sending workflow for voice/text routing

External Services & Credentials Required¶

Telegram Bot API: Bot token for receiving and sending messages
OpenAI API: API key for GPT-4 chat model and speech transcription services
PostgreSQL Database: For storing conversation memory (currently disabled)

Environment Variables¶

No explicit environment variables are defined in this workflow. All configurations are handled through n8n credential management.

Data Flow¶

Input: - Telegram messages (text or voice) - User chat ID for session management - Voice files (when applicable)

Processing: - Voice transcription to text - AI-generated educational responses with structured JSON format - Message routing based on educational stage

Output: - Formatted Telegram messages with appropriate keyboards - Voice messages (via external workflow) - Assessment questions (multiple choice, true/false) - Progress feedback and lesson content

Error Handling¶

The workflow includes basic error handling through: - Conditional voice detection to prevent transcription errors - Fallback text processing when voice transcription fails - Switch node with fallback outputs for unmatched message types - Disabled nodes suggest previous error handling implementations

Known Limitations¶

Based on the workflow structure: - Assessment generation appears to be manual (noted in sticky notes) - Some memory components are disabled, potentially limiting conversation continuity - Duplicate workflow sections suggest development/testing artifacts - Voice message processing may have latency issues - Limited error recovery for API failures

AI Trainer: Telegram Message Send (HUizQtOIkXsK9GRy): External workflow for handling voice/text message delivery

Setup Instructions¶

Import Workflow: Import the JSON into your n8n instance
Configure Credentials:
- Set up Telegram Bot API credentials with your bot token
- Configure OpenAI API credentials with appropriate API key
- Set up PostgreSQL credentials if enabling memory features
Telegram Bot Setup:
- Create a Telegram bot via @BotFather
- Configure webhook URL to point to your n8n Telegram trigger
- Test basic message reception
AI Configuration:
- Verify OpenAI model access (GPT-4)
- Test voice transcription functionality
- Customize the lesson plan JSON in the AI Agent system message
Testing:
- Send test messages to verify text processing
- Test voice message transcription
- Verify assessment delivery and response handling
Deployment:
- Activate the workflow
- Monitor execution logs for errors
- Enable memory components if persistent conversations are needed
Customization:
- Modify lesson plans in the AI Agent system prompt
- Adjust message timing in Wait nodes
- Customize Telegram keyboard layouts for different assessment types