Skip to content

Trainer Prod

An AI-powered Telegram bot that delivers structured entrepreneurship education to youth through interactive lessons, assessments, and personalized feedback with both text and voice support.

Purpose

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

This workflow creates an intelligent tutoring system that guides young learners through entrepreneurship concepts in a structured, module-based format. The system adapts to individual learning pace, provides immediate feedback on assessments, and maintains conversation history to track progress over time.

How It Works

  1. Message Reception: The workflow triggers when a user sends a message (text or voice) to the Telegram bot
  2. Typing Indicator: Bot immediately shows "typing" status to acknowledge the message
  3. Voice Processing: If the message is a voice note, it downloads the audio file and transcribes it using OpenAI's speech-to-text
  4. User Lookup: Checks if the user exists in the database to determine if this is a new learner
  5. AI Processing: The message is processed by an AI agent (GPT-4) that maintains conversation context and determines the appropriate learning stage
  6. Response Generation: AI generates structured JSON responses indicating the message content, learning stage, and whether voice output is preferred
  7. Stage Routing: Based on the learning stage, the workflow routes to different response types:
    • Course selection and greetings
    • Lesson content delivery
    • Interactive prompts for questions
    • Multiple choice questions with A/B/C/D buttons
    • True/False questions
    • Assessment feedback and scoring
    • Pass/fail notifications with next steps
  8. Message Delivery: Responses are sent via a sub-workflow that handles both text and voice output
  9. Memory Storage: All interactions are saved to maintain learning progress and conversation history

Mermaid 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[Model Input]
    H --> I[Get Current User]
    I --> J{New User?}
    J -->|Yes| K[Default Start Course - DISABLED]
    J -->|No| L[AI Agent]
    K --> M[Initialize User - DISABLED]
    M --> N[List Courses - DISABLED]
    L --> O[Edit Fields]
    O --> P[Switch by Stage]
    P -->|GREETING| Q[Telegram with Course Selection]
    P -->|CONTENT_DELIVERY| R[Send via Sub-workflow]
    P -->|INTERACTION_PROMPT| S[Send via Sub-workflow]
    P -->|ASSESSMENT_MCQ| T[Telegram with A/B/C/D buttons]
    P -->|ASSESSMENT_TF| U[Telegram with True/False buttons]
    P -->|ASSESSMENT_EVAL| V[Send via Sub-workflow]
    P -->|PASS| W[Pass Message with Next Steps]
    P -->|FAIL| X[Failure Message with Retry Options]
    R --> Y[Telegram with Question Prompt]

    L -.->|Memory| Z[Postgres Chat Memory]
    L -.->|LLM| AA[OpenAI Chat Model]

Trigger

Telegram Trigger: Activates when users send any message (text or voice) to the configured Telegram bot. The trigger captures the full message object including user information, chat details, and message content.

Nodes Used

Node Type Purpose
Telegram Trigger Receives incoming messages from Telegram users
Telegram Sends responses with custom keyboards and formatting
AI Agent Processes user input and determines appropriate learning responses
OpenAI Chat Model Provides the language model (GPT-4) for the AI agent
OpenAI (Audio) Transcribes voice messages to text
Postgres Chat Memory Maintains conversation history and learning progress
Postgres Queries user data and learning state
Switch Routes workflow based on AI-determined learning stages
If Conditional logic for voice message detection and user status
Set Data transformation and field mapping
Execute Workflow Calls sub-workflow for message delivery with voice support
Sticky Note Documentation and workflow annotations

External Services & Credentials Required

  • Telegram Bot API: Bot token for receiving and sending messages
  • OpenAI API: For GPT-4 chat completions and audio transcription
  • PostgreSQL Database: For user data, progress tracking, and conversation memory
  • Sub-workflow: "AI Trainer: Telegram Message Send" (handles voice synthesis)

Environment Variables

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

Data Flow

Input: - Telegram message object containing user info, chat ID, and message content (text or voice) - User's learning progress and conversation history from database

Output: - Structured educational responses via Telegram - Custom keyboards for multiple choice questions and navigation - Voice responses for lesson content (via sub-workflow) - Updated conversation memory and learning progress in database

Data Structure: The AI agent outputs structured JSON with: - message: Response text content - chat_stage: Learning flow stage (GREETING_START, CONTENT_DELIVERY, ASSESSMENT_MCQ, etc.) - is_voice: Boolean indicating if voice output is preferred

Error Handling

The workflow includes basic error handling through conditional logic: - Voice message processing falls back to text if transcription fails - User lookup handles both new and existing users - Switch node includes fallback routing for unmatched learning stages - Disabled nodes suggest incomplete new user onboarding flow

Known Limitations

  • New user onboarding flow is disabled/incomplete
  • Assessment generation is noted as needing human review process
  • No explicit error handling for API failures
  • Limited to single-user conversations (no group chat support)
  • Course selection and progress tracking appears to be in development
  • AI Trainer: Telegram Message Send: Sub-workflow that handles message delivery with voice synthesis capabilities

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Credentials:
    • Set up Telegram Bot API credentials (get bot token from @BotFather)
    • Configure OpenAI API credentials with GPT-4 access
    • Set up PostgreSQL database connection
  3. Database Setup:
    • Create learning_user table for user tracking
    • Ensure chat memory tables exist for conversation history
  4. Sub-workflow: Import and configure the "AI Trainer: Telegram Message Send" workflow
  5. Telegram Webhook: Activate the workflow to register the webhook with Telegram
  6. Testing: Send a message to your bot to verify the complete flow
  7. Enable New User Flow: Complete the disabled nodes for user onboarding if needed

Note: Some nodes are currently disabled, indicating this workflow may be in development. Review and enable the new user onboarding flow as needed for your use case.