Skip to content

Trainer MVP

An interactive AI-powered entrepreneurship training system that delivers structured lessons through Telegram, featuring voice support, assessments, and progress tracking for young entrepreneurs learning team leadership skills.

Purpose

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

This workflow serves as an educational platform that makes entrepreneurship training accessible to teenagers and young adults through a familiar messaging interface. The system guides learners through the "Leading a Team" module, teaching conflict resolution and win-win solutions through interactive lessons, assessments, and immediate feedback.

How It Works

  1. Message Reception: Users send text or voice messages to the Telegram bot
  2. Voice Processing: Voice messages are automatically transcribed using OpenAI's speech-to-text
  3. AI Processing: The AI agent (Sparky) processes the input and determines the appropriate response based on the current lesson stage
  4. Response Generation: Multiple response messages are generated in JSON format, each tagged with delivery preferences (voice/text) and interaction stage
  5. Message Routing: A switch node routes responses to appropriate Telegram message handlers based on the interaction stage
  6. Assessment Handling: Different question types (MCQ, True/False, open-ended) are presented with custom keyboards
  7. Progress Tracking: The system maintains conversation memory and tracks user progress through lessons
  8. Feedback Loop: After each response, the system waits for user input before continuing to the next lesson step

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]
    H --> I[Edit Fields]
    I --> J[Split Out Responses]
    J --> K[Edit Fields1]
    K --> L[Loop Over Items]
    L --> M{Response Type Switch}
    M -->|GREETING_START/CONTINUE| N[Telegram 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]
    M -->|FAIL| S[Failure Message]
    M -->|PASS| T[Pass Message]
    N --> U[Wait]
    O --> U
    P --> U
    Q --> U
    R --> U
    S --> U
    T --> U
    U --> L

    H -.->|Memory| V[Window Buffer Memory]
    H -.->|LLM| W[OpenAI Chat Model]

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 Sends various types of responses (text, keyboards, voice)
AI Agent Core learning engine that processes user input and generates educational responses
OpenAI Chat Model GPT-4 language model for generating contextual responses
OpenAI (Audio) Transcribes voice messages to text
Window Buffer Memory Maintains conversation context and learning progress
Switch Routes responses based on interaction stage (assessment, content, etc.)
If Determines if incoming message contains voice data
Set Data transformation and field mapping
Split Out Separates multiple response messages for individual processing
Split in Batches Processes multiple responses sequentially
Wait Pauses execution between message bursts
Execute Workflow Calls sub-workflow for message delivery

External Services & Credentials Required

OpenAI API

  • Credential Name: "Waringa"
  • Required For: GPT-4 chat completions and audio transcription
  • Permissions: Chat completions, audio transcription

Telegram Bot API

  • Credential Name: "Waringa"
  • Required For: Receiving and sending messages
  • Setup: Bot token from @BotFather

Sub-Workflow Dependency

  • Workflow: "AI Trainer: Telegram Message Send" (ID: 9Crfdp1UsZ9zL1Ba)
  • Purpose: Handles message delivery with voice synthesis
  • Requirement: Must be published and active

Environment Variables

No explicit environment variables are configured in this workflow. All external service connections are managed through n8n credentials.

Data Flow

Input

  • Text Messages: User responses, lesson selections, assessment answers
  • Voice Messages: Audio files that get transcribed to text
  • User Context: Chat ID for session management

Processing

  • Lesson Content: Structured JSON lesson plans with steps and assessments
  • AI Responses: JSON arrays containing multiple messages with delivery preferences
  • Assessment Logic: Question types, correct answers, and scoring

Output

  • Educational Content: Lesson materials delivered via text or voice
  • Interactive Assessments: MCQ, True/False, and open-ended questions
  • Progress Feedback: Pass/fail notifications and next steps
  • Custom Keyboards: Context-appropriate response options

Error Handling

The workflow includes basic error handling through: - Voice Detection: Graceful fallback to text processing if voice transcription fails - Switch Fallback: Default routing for unrecognized response types - Sub-workflow Dependency: Critical dependency on message delivery workflow

Known Limitations

Based on the workflow structure: - Single Module: Currently only supports "Leading a Team" lesson content - Assessment Generation: Notes indicate need for human review process for assessments - Sub-workflow Dependency: Workflow fails if the message delivery sub-workflow is inactive - Voice Credits: Voice output depends on external service credits (ElevenLabs)

  • AI Trainer: Telegram Message Send (ID: 9Crfdp1UsZ9zL1Ba) - Required sub-workflow for message delivery with voice synthesis

Setup Instructions

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

  2. Configure Credentials:

    • Set up OpenAI API credential named "Waringa"
    • Configure Telegram Bot API credential named "Waringa"

  3. Deploy Sub-workflow:

    • Import and publish "AI Trainer: Telegram Message Send" workflow
    • Ensure it's active and accessible

  4. Configure Telegram Bot:

    • Create bot via @BotFather
    • Set webhook URL to your n8n instance
    • Configure bot commands and description

  5. Test Voice Features:

    • Verify OpenAI audio transcription works
    • Test voice message processing

  6. Customize Content:

    • Modify lesson plans in AI Agent system prompt
    • Adjust assessment questions and scoring logic
    • Update keyboard options for your use case

  7. Monitor Dependencies:

    • Ensure sub-workflow remains published
    • Monitor API credits for OpenAI and voice services
    • Test end-to-end flow regularly

  8. Activate Workflow: Enable the workflow to start receiving Telegram messages