Trainer Prod¶

An AI-powered educational chatbot that delivers structured entrepreneurship training through Telegram, featuring interactive lessons, voice support, and automated assessments with personalized feedback.

Purpose¶

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

This workflow appears to be designed for delivering educational content through an AI trainer that can conduct structured learning sessions via Telegram. The system supports both text and voice interactions, manages user progress through a database, and provides automated assessments with immediate feedback.

How It Works¶

Message Reception: The workflow starts when a user sends a message (text or voice) to the Telegram bot
Typing Indicator: Immediately shows "typing" status to provide user feedback
Voice Processing: If the message is a voice note, it downloads the audio file and transcribes it using OpenAI's speech-to-text
User Management: Checks if the user exists in the database and initializes new users if needed
AI Processing: Sends the user's message to an AI agent (Sparky) that follows a structured learning flow with defined stages
Response Routing: Based on the AI's response stage, routes to appropriate Telegram message formats:
- Course selection with custom keyboards
- Lesson content delivery (potentially as voice)
- Interactive prompts for questions
- Multiple choice questions with A/B/C/D options
- True/False questions
- Assessment feedback and results
Memory Management: Maintains conversation context using PostgreSQL chat memory
Progress Tracking: Stores user progress and learning state in the database

Mermaid Diagram¶

graph TD
    A[Telegram Trigger] --> B[Start Typing]
    B --> C{If Voice}
    C -->|Voice| D[Download Audio]
    C -->|Text| E[Message text1]
    D --> F[OpenAI2 Transcribe]
    F --> G[Message text]
    G --> H[Model Input]
    E --> H
    H --> I[Get Current User]
    I --> J{If New User}
    J -->|New| K[Default Start Course]
    J -->|Existing| L[AI Agent]
    K --> M[Initialize User]
    M --> N[List of Available Courses]
    L --> O[Edit Fields]
    O --> P[Switch]
    P -->|GREETING_START/CONTINUE| Q[Telegram]
    P -->|CONTENT_DELIVERY| R[Send Telegram Message1]
    P -->|INTERACTION_PROMPT| S[Send Telegram Message]
    P -->|CLARIFICATION| S
    P -->|ASSESSMENT_START| S
    P -->|ASSESSMENT_ADMINISTER| S
    P -->|ASSESSMENT_ADMINISTER_MCQ| T[TelegramMCQ]
    P -->|ASSESSMENT_ADMINISTER_TF| U[TelegramTF]
    P -->|ASSESSMENT_EVAL| S
    P -->|FAIL| V[Failure Message]
    P -->|PASS| W[Pass Message]
    R --> X[Telegram1]
    Y[OpenAI Chat Model] -.->|Language Model| L
    Z[Postgres Chat Memory] -.->|Memory| L

Trigger¶

Telegram Trigger: Activates when users send messages (text, voice, or other updates) to the configured Telegram bot. The trigger captures all message types and user interactions.

Nodes Used¶

Node Type	Purpose
Telegram Trigger	Receives incoming messages from Telegram users
Telegram	Sends messages back to users with custom keyboards
If Voice	Determines if the message contains voice audio
OpenAI (Audio)	Transcribes voice messages to text
AI Agent	Core AI logic following structured learning flow
OpenAI Chat Model	Language model for generating responses
Postgres Chat Memory	Maintains conversation context and history
PostgreSQL	User management and progress tracking
Switch	Routes responses based on AI agent's stage output
Set	Data transformation and field mapping
Execute Workflow	Calls external workflow for message sending

External Services & Credentials Required¶

Telegram Bot API: For receiving and sending messages
- Credential: telegramApi (Bot token from @BotFather)
OpenAI API: For AI responses and voice transcription
- Credential: openAiApi (API key from OpenAI)
PostgreSQL Database: For user data and chat memory
- Credential: postgres (Database connection details)

Environment Variables¶

No specific environment variables are configured in this workflow. All external service connections use n8n's credential system.

Data Flow¶

Input: - Telegram messages (text or voice) - User chat IDs - Voice audio files (when applicable)

Processing: - Voice transcription to text - User lookup and initialization - AI-generated educational content and assessments - Conversation memory management

Output: - Formatted Telegram messages with custom keyboards - Voice responses (when specified by AI) - User progress updates in database - Assessment results and feedback

Error Handling¶

The workflow includes basic error handling through: - Conditional routing for voice vs. text messages - User existence checks before processing - Fallback paths in the Switch node - Some nodes are disabled, suggesting development/testing phases

No explicit error handling nodes are present for API failures or database connection issues.

Known Limitations¶

Based on the workflow structure: - Assessment generation appears to be manual (noted in sticky note about needing human reviewers) - Some database operations are disabled, suggesting incomplete implementation - No explicit error recovery for external service failures - Voice processing depends on OpenAI API availability

Telegram Message Send (ID: HUizQtOIkXsK9GRy): Called via Execute Workflow node for sending formatted messages

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
- Set up PostgreSQL database connection
Database Setup:
- Create required tables: learning_user and chat memory tables
- Ensure proper schema permissions
Telegram Bot Setup:
- Create bot via @BotFather
- Set webhook URL to your n8n instance
Enable Workflow: Activate the workflow to start receiving messages
Test: Send a message to your bot to verify the complete flow
Configure Related Workflows: Ensure the "Telegram Message Send" workflow is also imported and configured

Note: Several nodes are currently disabled and may need to be enabled and properly configured for full functionality.