n8n-teacher-bot

KO | EN

gitlite — search

#python #hacktoberfest #ai #llm #rust #deep-learning #windows #cli #awesome-list #vue #security #ios #openai #open-source

n8n-teacher-bot

(★ 3)

Multi-mode n8n Telegram bot: AI teacher for n8n learning + WorkflowYab semantic RAG search. Built entirely in n8n with MCP tools, email OTP auth, PostgreSQL memory.

n8n-teacher-bot 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# n8n Telegram Teacher + WorkflowYab Bot

[![n8n](https://img.shields.io/badge/n8n-1.0+-EA4AAA.svg)](https://n8n.io)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/Amirezamky9/n8n-teacher-bot/main/LICENSE)
[![Telegram](https://img.shields.io/badge/Telegram-Bot-26A5E4.svg)](https://core.telegram.org/bots/api)
[![AI](https://img.shields.io/badge/AI-OpenAI%20%7C%20Gemini%20%7C%20Groq-FF6F00.svg)](https://raw.githubusercontent.com/Amirezamky9/n8n-teacher-bot/main/)

> **A multi-mode Telegram bot for n8n learning, workflow discovery, and debugging.**  
> Built entirely in n8n with AI agents, MCP tools, email-based authentication, and PostgreSQL memory.

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [How It Works](#how-it-works)
- [Prerequisites](#prerequisites)
- [Import & Setup](#import--setup)
  - [1. Import the workflow](#1-import-the-workflow)
  - [2. Configure credentials](#2-configure-credentials)
  - [3. Database tables](#3-database-tables)
  - [4. Environment variables](#4-environment-variables)
- [User Flow](#user-flow)
  - [Registration & OTP Verification](#registration--otp-verification)
  - [Main Menu](#main-menu)
  - [Teacher Mode](#teacher-mode)
  - [WorkflowYab Mode](#workflowyab-mode)
  - [Debug Mode](#debug-mode)
- [Technical Details](#technical-details)
  - [Node Inventory](#node-inventory)
  - [Authentication System](#authentication-system)
  - [AI Agent Configuration](#ai-agent-configuration)
  - [MCP Tools](#mcp-tools)
  - [Rate Limiting](#rate-limiting)
  - [Data Flow Diagrams](#data-flow-diagrams)
- [Database Schema](#database-schema)
- [Customisation](#customisation)
- [Contributing](#contributing)
- [License](#license)

---

## Overview

This is a **complete Telegram bot** built as an n8n workflow that provides three distinct services through a single bot interface:

1. **🧑‍🏫 n8n Teacher** — an AI agent that teaches users how to build n8n workflows in Persian (Farsi). It uses MCP (Model Context Protocol) tools to search n8n nodes, look up documentation, find templates, and validate node configurations — all while guiding the user with step-by-step explanations.

2. **🔍 WorkflowYab** — a semantic RAG-based workflow search engine. Users describe what they need, and an AI supervisor reasons about the intent, searches a PostgreSQL vector database of existing workflows, and returns matching results with descriptions and downloadable JSON files.

3. **🐛 Debug Mode** — placeholder for future debugging tools.

The bot supports email-based **access control** with OTP verification, weekly usage limits, and a persistent user state machine stored in n8n Data Tables.

---

## Features

| Feature | Description |
|---|---|
| **Email + OTP Registration** | Users register with their name and email; a one-time password is sent via Gmail. |
| **Whitelist Access Control** | Only pre-approved users (stored in a Data Table) can access the bot. |
| **Persistent User State** | User status (`teacher`, `workflowyab`, `unregistered`) is tracked via Data Table rows, enabling multi-step conversations. |
| **PostgreSQL Chat Memory** | Each user has a dedicated session memory stored in PostgreSQL for conversational continuity. |
| **Multi-Model AI Agents** | The Supervisor agent uses Grok 4.1 Fast (via OpenRouter) + Gemini fallback; The Teacher agent uses Grok 4 Fast + Gemini fallback; the WorkflowYab parser uses GPT-4o Mini. |
| **MCP Tool Integration** | MCP client tools connect to a remote n8n MCP server for searching nodes, templates, docs, and validating configurations. |
| **Structured AI Outputs** | The Supervisor agent returns validated JSON via a Structured Output Parser matching a fixed schema with `top_workflows` and `text` fields. |
| **Workflow File Export** | Matched workflows are exported as downloadable JSON files sent directly in Telegram. |
| **Weekly Usage Cap** | Each user has a weekly counter tracked by `limit` column, enforced by n8n Date-Time operations. |
| **Error Handling** | Two-level error handling: "error" output routes for critical failures + a dedicated `Send error message` node notifying the developer via Telegram. |
| **Back Navigation** | Users can return to the main menu at any time with the `/back` command. |

---

## Architecture

```
┌──────────────────────────────────────────────────────────────────────────┐
│                          Telegram Bot (n8n)                              │
│                                                                          │
│  ┌───────────────────┐    ┌────────────────────────────────────────────┐ │
│  │  Telegram Trigger  │───▶│            Message Classifier             │ │
│  │  (message + cbq)   │    │  (Set node: type, email, otp, callback)   │ │
│  └───────────────────┘    └───────────────────┬────────────────────────┘ │
│                                                │                        │
│                     ┌──────────────────────────▼──────────────────┐     │
│                     │         User Check (Data Table)             │     │
│                     │  Does the user exist in the whitelist?      │     │
│                     └──────┬───────────────────────┬──────────────┘     │
│                            │ NO                    │ YES                │
│                     ┌──────▼──────┐       ┌────────▼────────┐          │
│                     │ Registration │       │   State Router   │          │
│                     │ (Name+Email  │       │  (Switch3)       │          │
│                     │  → OTP)     │       │  teacher/        │          │
│                     └─────────────┘       │  workflowyab/    │          │
│                                            │  callback        │          │
│                                            └──┬────┬────┬────┘          │
│                        ┌───────────────────────┘    │    │              │
│               ┌────────▼────────┐     ┌──────────────▼───▼──────┐      │
│               │  Teacher Agent  │     │  Supervisor Agent        │      │
│               │  (n8n tutor)    │     │  (WorkflowYab)          │      │
│               │  MCP Tools:     │     │  Tools: Think +         │      │
│               │  search_node    │     │  Subworkflow (RAG)      │      │
│               │  documentation  │     │  Models: Grok/Gemini    │      │
│               │  templates      │     │  Output: JSON Parser    │      │
│               │  validate_node  │     └──────────────┬──────────┘      │
│               │  Think          │                    │                  │
│               └────────┬────────┘           ┌────────▼──────────┐     │
│                        │                    │ Split → DB Query  │     │
│               ┌────────▼────────┐           │ → Set → File →    │     │
│               │  Telegram Reply  │           │   Telegram Send   │     │
│               └─────────────────┘           └───────────────────┘     │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## How It Works

### 1. Message Classification
Every incoming message (text or callback query) passes through a **Set node** called `Classify Message` which uses JavaScript expressions to determine:

- **`message_type`**: `EMPTY`, `OTP` (6-digit code), `EMAIL_VALID`, `EMAIL_INVALID`, or `TEXT`
- **`extracted_email`**: Regex-extracted email from text
- **`extracted_name`**: Name portion before the email
- **`otp_code`**: The 6-digit code if present
- **`callback_data`**: For inline keyboard callbacks (`teacher`, `workflow_yab`, `debug`)

### 2. User Lookup & Routing
The classified message flows to `Get row(s)` — a Data Table lookup on the `n8n_users` table. Three possible outcomes:

- **User not found** → Registration flow (name + email → OTP verification)
- **User found, no active status** → Main menu (inline keyboard with 3 modes)
- **User found, has active status** → Routed via `Switch3` to the correct agent based on the user's `status` field

### 3. Registration Flow
1. First-time user sends their name + email → `Classify Message` extracts and validates
2. `Get email` Data Table checks if the email/name exists in the whitelist
3. `Switch2` validates: exists with matching email, name mismatch, email mismatch, etc.
4. If all matches → `Code (Make OTP)` generates a 6-digit code + expiry timestamp
5. `Get email1` Data Table stores the OTP and expiry
6. `Send code` (Gmail) sends the OTP email
7. User responds with the 6-digit code → `If3` validates code + expiry → user is registered

### 4. Teacher Agent
When a user selects **Teacher Mode**:

1. `If6` checks the weekly usage limit (`limit` column, 7-day window)
2. Within limit → "من رفتم تو فکر 🧠" typing message → Teacher agent fires
3. The **Teacher Agent** (Grok 4 Fast via OpenRouter, with Gemini fallback) has access to 5 MCP tools:
 - `search_node` — Search n8n nodes by name/type
 - `tools_documentation` — Get detailed documentation for a node
 - `search_templates` — Find n8n workflow templates
 - `get_node` — Inspect node configuration details
 - `validate_node` — Validate a proposed node configuration
 - `Think1` — Internal reasoning tool for step-by-step planning
4. Responses are in Persian Farsi with HTML formatting (Telegram-compatible ``, ``, `<code>` tags)
5. After each response, the AI message is cleaned up via a Postgres UPDATE query (removes tool-calling noise from chat history)

### 5. WorkflowYab Agent
When a user selects **WorkflowYab Mode**:

1. Same usage-limit check
2. The **Supervisor Agent** (Grok 4.1 Fast with Gemini fallback) uses:
   - `Think` tool — Returns JSON with intent, search_query_en, collections_ranked
   - `workflowyab` tool — Calls a **subworkflow** (`rag_workflow_tools`) that performs RAG search in PostgreSQL embeddings
3. The Structured Output Parser forces the agent to output: `{ top_workflows: [...], text: "..." }`
4. Results flow through:
   - `If1`: Empty results → inform user; Has results → continue
   - `Split Out`: Splits each workflow item
   - `Select rows from a table1`: Queries full workflow metadata from `n8n_workflow_vector`
   - `mean_workflow`: Extracts the `workflowjson` field
   - `Convert to File` → `send file`: Sends each workflow as a downloadable `.json` file in Telegram with caption info
5. `Update row(s)2` records the current timestamp as the user's last usage for rate limiting

---

## Prerequisites

- **n8n instance** (self-hosted or cloud, v1.0+)
- **PostgreSQL database** with `pgvector` extension (for RAG search)
- **Telegram Bot Token** from [@BotFather](https://t.me/BotFather)
- **Gmail account** with App Password for sending OTP emails
- **OpenAI API key** (for GPT-4o Mini)
- **OpenRouter API key** (for Grok models)
- **Google Gemini API key** (for fallback models)
- **MCP Server** running at `http://<your-server>:3000/mcp` (for n8n tool integration)

---

## Import & Setup

### 1. Import the workflow

1. Download [`workflow.json`](./workflow.json) from this repository.
2. In your n8n instance, go to **Workflows → Import from File**.
3. Select the downloaded file.

### 2. Configure credentials

You need to create these credential entries in n8n:

| Credential | Type | Used By |
|---|---|---|
| Telegram Bot | `Telegram API` | All Telegram nodes |
| Gmail OTP | `Gmail OAuth2` | `Send code` node |
| OpenAI | `OpenAI API` | `OpenAI Chat Model2` |
| OpenRouter | `OpenRouter API` | Both OpenRouter models |
| Google Gemini | `Google PaLM API` | Both Gemini models |
| PostgreSQL (rag_table) | `Postgres` | Memory, SQL nodes |
| MCP Bearer | `HTTP Bearer Auth` | All MCP client tools |

### 3. Database tables

The workflow expects the following tables:

#### `n8n_users` (Data Table)
| Column | Type | Description |
|---|---|---|
| `fullname` | string | Full name of the user |
| `email` | string | Email address (unique) |
| `userid` | string | Telegram user ID (set after registration) |
| `status` | string | Current mode: `teacher`, `workflowyab`, `debug`, or empty |
| `otp` | string | Current OTP code |
| `otp_expires_at` | dateTime | OTP expiry timestamp |
| `massage_num` | number | Message counter |
| `limit` | dateTime | Weekly usage cap timestamp |

#### `n8n_workflow_vector` (Data Table)
| Column | Type | Description |
|---|---|---|
| `id` | string | Unique workflow identifier |
| `name` | string | Workflow name |
| `description` | string | Short description |
| `categories` | string | Category tags |
| `metadata` | jsonb | Full metadata including `workflowjson`, `nodeCount` |

#### `n8n_chat_histories_n8n_users` (Postgres table, auto-created by Memory node)
Stores conversation history for the Teacher agent.

#### `n8n_chat_histories_natenagent_n8n_users` (Postgres table, auto-created by Memory node)
Stores conversation history for the Supervisor (WorkflowYab) agent.

### 4. Environment variables

No `.env` file is needed — credentials are managed through n8n's credential system.

---

## User Flow

### Registration & OTP Verification

```
User: "امیررضا مختاری\namir@gmail.com"
Bot: (validates format)
     If INVALID → "فرمت وارد کردن اسمت اشتباه هست..."
     If VALID → checks whitelist
     If NOT IN WHITELIST → "شما جزو لیست نیستی"
     If MATCHES → sends OTP email → "کد 6 رقمی که برات ایمیل اومده را بفرست"
User: "123456"
Bot: If valid + not expired → Welcome! Shows main menu
     If invalid/expired → "کد نادرست یا منقضی شده است"
```

### Main Menu

```
┌─────────────────────────────┐
│  🤖 Bot Name                │
├─────────────────────────────┤
│  🧑‍🏫 معلم خصوصی              │
│  🔍 ورکفلو یاب              │
│  🐛 دیباگ                   │
└─────────────────────────────┘
```

### Teacher Mode

```
User: "چطور یه webhook trigger بزنم؟"
Bot: "🧠" → processing → 
     "عالیه! بیا قدم به قدم جلو بریم...

مرحله ۱: از لیست نودها، <code>Webhook</code> رو انتخاب کن.
 مرحله ۲: توی تنظیماتش، <code>POST</code> رو به عنوان روش انتخاب کن.
 ..."
```

### WorkflowYab Mode

```
User: "یه ورکفلو میخوام که قیمت بیت‌کوین رو هر ساعت بگیره و تو گوگل شیت ذخیره کنه"
Bot: → searches RAG vector DB → returns results:
     "این ورکفلوها رو پیدا کردم:"
     
     📄 crypto_price_tracker.json  ← downloadable
     📄 btc_google_sheets.json     ← downloadable
```

### Debug Mode

```
Bot: "فعلا داریم روش کار میکنیم، منتظر ی ورژن خفن باش!"
```

---

## Technical Details

### Node Inventory

| # | Node Name | Type | Role |
|---|---|---|---|
| 1 | `Telegram Trigger` | TelegramTrigger | Entry point for all messages + callbacks |
| 2 | `Classify Message` | Set | Classifies incoming message type |
| 3 | `Get row(s)` | DataTable | Looks up user in whitelist |
| 4 | `If` | If | Routes unregistered users |
| 5 | `If2` | If | Checks if message is OTP |
| 6 | `Get row(s)1` | DataTable | Validates OTP code |
| 7 | `If3` | If | Checks OTP validity + expiry |
| 8 | `Send Message employee1` | Telegram | Welcome + main menu keyboard |
| 9 | `emial employee1` | Switch | Routes valid/invalid email |
| ... | ... | ... | ... |
| | **Total: 75 nodes** | | |

### Authentication System

The authentication flow uses **chained conditional logic**:

1. **Format validation** — regex in `Classify Message` Set node checks for `@domain` patterns
2. **Domain whitelist** — only `gmail`, `yahoo`, `hotmail`, `outlook`, `icloud`, `proton` domains are accepted
3. **Name + email matching** — `Switch2` matches the user's input against the Data Table whitelist with 5 output branches:
   - User not found → "شما جزو لیست نیستی"
   - Email missing → "ایمیلت موجود نیست ولی اسمت هست"
   - Name mismatch → "اسمت با ایمیل ثبت شده همخوانی ندارد"
   - Email mismatch → "ایمیلی که ما داریم متفاوته"
   - All match → Proceed to OTP
4. **OTP Generation** — 6-digit code via `Code (Make OTP)` node with expiration
5. **Email sending** — Gmail node sends the OTP
6. **OTP Verification** — User's 6-digit code checked against stored value + 10-minute expiry

### AI Agent Configuration

#### Supervisor (WorkflowYab)

| Parameter | Value |
|---|---|
| **Primary Model** | Grok 4.1 Fast (OpenRouter: `x-ai/grok-4.1-fast`) |
| **Fallback Model** | Gemini 1.5 Pro |
| **Memory** | Postgres Chat Memory (table: `n8n_chat_histories_natenagent_n8n_users`) |
| **Output Parser** | Structured Output Parser (validated JSON with `top_workflows` array) |
| **Tools** | `think` (reasoning) + `workflowyab` (subworkflow) |
| **Language** | User-facing Farsi, internal English |

#### Teacher

| Parameter | Value |
|---|---|
| **Primary Model** | Grok 4 Fast (OpenRouter: `x-ai/grok-4-fast`) |
| **Fallback Model** | Gemini 1.5 Pro |
| **Memory** | Postgres Chat Memory (table: `n8n_chat_histories_n8n_users`, window: 4) |
| **Tools** | 5 MCP tools + `Think1` reasoning tool |
| **Language** | Farsi (Persian) with educational tone |
| **Output Format** | HTML with ``, ``, `<code>`, `<pre>`, `<a>` tags only |

### MCP Tools

All MCP tools connect to a remote n8n MCP server endpoint (set your own in the MCP client nodes)

| Tool Name | MCP Method | Description |
|---|---|---|
| `search_node` | `search_nodes` | Search n8n nodes by service name |
| `tools_documentation` | `tools_documentation` | Get node documentation |
| `search_templates` | `search_templates` | Search workflow templates |
| `get_node` | `get_node` | Inspect node configuration |
| `validate_node` | `validate_node` | Validate node parameters |

### Rate Limiting

The weekly usage cap is enforced via:

```javascript
// If6 condition — checks if 7+ days elapsed since last use
$('Get row(s)').item.json.limit.toDateTime().diffToNow('days').abs() > 6
```

- If `limit` is older than 6 days (or null) → access granted
- If `limit` is within 6 days → "به حد استفاده رسیدی دوست عزیز" message

The `limit` column is updated to `$now` after each successful agent interaction.

### Data Flow Diagrams

#### WorkflowYab Search Flow

```
User → Telegram Trigger → Classify Message → Get row(s) → If5 → Switch3 (state=workflowyab)
  → If6 (rate limit check) → Send a text message1 (typing...)
  → Supervisor Agent (Grok + tools)
    → Think (intent classification)
    → workflowyab (subworkflow: RAG search)
    → Structured Output Parser ({top_workflows, text})
  → If1 (empty results check)
    → [Empty] → Send  message to user ("نتیجه‌ای پیدا نشد")
    → [Has results] → Split Out → Select rows from a table1 → mean_workflow
      → Convert to File → send file (Telegram document)
  → Update row(s)2 (rate limit timestamp)
```

---

## Database Schema

### `n8n_users` (n8n Data Table)

This is the **primary user registry**. Managed via n8n Data Table nodes.

```sql
-- Equivalent SQL (n8n Data Tables are abstracted)
Table: n8n_users
Columns:
  fullname       TEXT        -- Full name (from registration)
  email          TEXT        -- Email address
  userid         TEXT        -- Telegram user ID (set on OTP completion)
  status         TEXT        -- Current state: teacher, workflowyab, debug, or NULL
  otp            TEXT        -- Current valid OTP
  otp_expires_at TIMESTAMPTZ -- OTP expiry
  massage_num    INTEGER     -- Message counter
  limit          TIMESTAMPTZ -- Last usage timestamp (rate limiting)
```

### `n8n_workflow_vector` (n8n Data Table)

Stores workflow metadata with embedding vectors for RAG search.

```sql
Table: n8n_workflow_vector
Columns:
  id             TEXT        -- Workflow ID
  name           TEXT        -- Workflow name
  description    TEXT        -- Workflow description
  categories     TEXT        -- Category tags
  metadata       JSONB       -- Full metadata incl. workflowjson, nodeCount
```

### Chat History Tables (Postgres)

Auto-created by n8n's `Postgres Chat Memory` nodes:
- `n8n_chat_histories_n8n_users` — Teacher agent memory
- `n8n_chat_histories_natenagent_n8n_users` — Supervisor agent memory

---

## Customisation

### Adding new whitelist users

Add rows to the `n8n_users` Data Table with `fullname` and `email` fields filled. When the user registers via Telegram, they must provide **exactly matching** name and email.

### Changing AI models

Each agent uses a primary and fallback model. To change:
1. Update the OpenRouter model name in the `OpenRouter Chat Model` / `OpenRouter Chat Model1` nodes
2. Update the `Google Gemini Chat Model` / `Google Gemini Chat Model1` nodes if changing fallback

### Adding new MCP tools

1. Create a new `MCP Client Tool` node pointing to your MCP server
2. Wire it as an `ai_tool` connection to the relevant agent
3. Add the tool's description in the node parameters (the agent uses this to decide when to call it)

### Localisation

The bot currently supports **Persian (Farsi)** for user-facing messages. To add English or another language:
1. Update the system prompts in both AI agent nodes
2. Update all Telegram text fields
3. Update the `Classify Message` regex patterns if email/OTP format differs

---

## Contributing

Contributions are welcome! To contribute:

1. **Export** your modified workflow from n8n (Workflows → Download)
2. **Replace** `workflow.json` in this repository
3. **Update** this README if you changed functionality or added nodes
4. Open a **Pull Request** with a clear description of changes

### Guidelines

- Keep the JSON file as a clean export (no test data, no personal credentials)
- Document all new nodes and connections in the README
- Maintain backward compatibility where possible

---

## License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---

Built with ❤️ using n8n for the n8n community. 
 Questions? Open an issue or start a discussion!

n8n-teacher-bot

n8n-teacher-bot 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

n8n-teacher-bot

n8n-teacher-bot 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README