Trainer Prod

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

Purpose

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

How It Works

1. Message Reception: The workflow triggers when a user sends a message (text or voice) to the configured Telegram bot
2. Typing Indicator: Immediately shows "typing" status to provide user feedback
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 Management: Checks if the user exists in the database and handles new user onboarding (currently disabled)
5. AI Processing: Sends the user's message to an AI agent (Sparky) that follows a structured learning flow with defined stages
6. Response Routing: Based on the AI's response stage, routes to appropriate Telegram message formats:
   • Standard messages for greetings and content delivery
   • Multiple choice questions with A/B/C/D buttons
   • True/False questions with True/False buttons
   • Assessment feedback and pass/fail notifications
7. Memory Persistence: Maintains conversation context using PostgreSQL chat memory keyed by user chat ID

Mermaid Diagram

graph TD
    A[Telegram Trigger] --> B[Start Typing]
    B --> C{If Voice}
    C -->|Voice Message| D[Download Audio]
    C -->|Text Message| 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 - DISABLED]
    J -->|Existing| L[AI Agent]
    K --> M[Initialize User - DISABLED]
    M --> N[List of Available Courses - DISABLED]
    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 or voice) to the configured Telegram bot. Listens for message updates and captures the full message object including chat ID, user information, and message content.

Nodes Used

Node Type	Purpose
Telegram Trigger	Receives incoming messages from Telegram users
Telegram	Sends various types of responses with custom keyboards
OpenAI (Audio)	Transcribes voice messages to text
OpenAI Chat Model	Provides the language model for the AI agent
AI Agent	Core conversational AI following structured learning flow
Postgres Chat Memory	Maintains conversation history per user
Postgres	Database operations for user management
If/Switch	Conditional routing based on message type and AI response stage
Set	Data transformation and field mapping
Execute Workflow	Calls external workflow for message sending
Sticky Note	Documentation and workflow annotations

External Services & Credentials Required

• Telegram Bot API: For receiving and sending messages
  • Credential: telegramApi (Telegram account 2)
• OpenAI API: For speech transcription and language model
  • Credential: openAiApi (OpenAI Assistants API)
• PostgreSQL Database: For user data and chat memory storage
  • Credential: postgres (Postgres account)

Environment Variables

No explicit environment variables are defined in this workflow. Configuration is handled through n8n credentials and node parameters.

Data Flow

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

Processing: - Voice transcription to text - User lookup and management - AI agent processing with structured JSON responses - Conversation memory storage

Output: - Formatted Telegram messages with appropriate keyboards - Voice messages (when specified by AI agent) - Assessment questions with multiple choice or true/false options - Progress tracking and feedback messages

Error Handling

The workflow includes basic error handling through conditional routing: - Voice message processing falls back to text if transcription fails - User existence checks prevent database errors - Switch node handles unknown AI response stages gracefully - Multiple Telegram response formats accommodate different interaction types

Known Limitations

• New user onboarding flow is currently disabled
• Assessment generation flow mentioned in notes is not implemented
• Some nodes are disabled, indicating incomplete functionality
• Limited to predefined learning stages and question types
• No explicit error recovery mechanisms for API failures

Related Workflows

• Telegram Message Send (ID: HUizQtOIkXsK9GRy): External workflow called for sending formatted messages

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure Credentials:
   • Set up Telegram Bot API credentials
   • Configure OpenAI API access
   • Establish PostgreSQL database connection
3. Database Setup: Ensure PostgreSQL tables exist:
   • learning_user table for user management
   • Chat memory tables (created automatically by Postgres Chat Memory node)
4. Telegram Bot:
   • Create a Telegram bot via BotFather
   • Configure webhook URL to point to your n8n Telegram Trigger
5. Enable Workflow: Activate the workflow to start receiving messages
6. Test: Send a message to your Telegram bot to verify functionality
7. Optional: Enable disabled nodes for full user onboarding if needed

Note: Several nodes are currently disabled. Review and enable them based on your requirements for user management and course selection features.