---

[Try it Now] [简体中文] [日本語]

Easily find and export your Telegram messages with powerful semantic search, supporting all languages and unsegmented sentences.

Make message retrieval fast, accurate, and privacy-friendly — self-host or try online.

💖 Sponsors

✅ What Can It Do

📦 Export & Backup

• Export to PostgreSQL or in-browser database (PGlite)
• Universal export format for easy import to any database
• One-click export to CSV / JSON

🔍 Search Your Chat History

• Keyword search: multi-language support (Chinese, English, etc.)
• Natural language search: find messages like asking a question
• Smart filters: by contact/group, time range, with attachments, etc.

🔄 Sync & Storage

• Incremental sync: sync while using
• Storage options: server (PostgreSQL + pgvector) or browser-only mode (PGlite)
• Resume from breakpoint: auto-continue after failure

🧠 AI Capabilities

• Ask AI about your chats: query current chat or selected range
• AI message summary: auto-extract key points, todos, conclusions
• AI-powered search: natural language queries with pinpointed results
• AI chat: converse with AI based on your chat context
• AI analysis: trends, sentiment, keywords, insights from links & files
• Local model support: local Embedding / inference (no cloud required)

🔗 Media & Links (Planned)

• Deep indexing for links & images: web summaries, image OCR/descriptions
• Attachment content extraction: PDFs, images, audio/video key frames & text

🌐 More Platforms (Planned)

• Multi-client support: Discord, etc.

🌐 Try it Now

We provide an online version where you can experience all features of Telegram Search without self-deployment.

Note

We promise not to collect any user privacy data, you can use it with confidence

Visit: https://search.lingogram.app

🚀 Quick Start (Self-Hosted)

1-Minute Start with Docker

Important

The simplest way to get started — no configuration needed. All features work with sensible defaults.

docker run -d --name telegram-search \
  -p 3333:3333 \
  -v telegram-search-data:/app/data \
  ghcr.io/groupultra/telegram-search:latest

Then open http://localhost:3333 🎉

Advanced Setup (Optional, Environment Variables)

🔧 Environment Variables

[!TIP] All environment variables are optional. Customize only if needed.

Variable	Description
TELEGRAM_API_ID	Telegram app ID from my.telegram.org
TELEGRAM_API_HASH	Telegram app hash
DATABASE_TYPE	postgres or pglite (default: pglite)
DATABASE_URL	PostgreSQL connection string (only when DATABASE_TYPE=postgres)
PROXY_URL	Proxy URL (e.g. socks5://user:pass@host:port)
PORT	Backend HTTP/WebSocket port inside the container (default: 3000)
HOST	Backend listen host inside the container (default: 0.0.0.0)
BACKEND_URL	Nginx upstream URL for /api and /ws (default: http://127.0.0.1:3000)

[!IMPORTANT] AI Embedding & LLM settings are now configured per account inside the app (Settings → API).
Environment variables like EMBEDDING_API_KEY, EMBEDDING_MODEL, etc. are deprecated and will be removed in a future release.

Example with PostgreSQL:

docker run -d --name telegram-search \
  -p 3333:3333 \
  -v telegram-search-data:/app/data \
  -e TELEGRAM_API_ID=611335 \
  -e TELEGRAM_API_HASH=d524b414d21f4d37f08684c1df41ac9c \
  -e DATABASE_TYPE=postgres \
  -e DATABASE_URL=postgresql://<postgres-host>:5432/postgres \
  ghcr.io/groupultra/telegram-search:latest

Proxy formats:

• SOCKS5: socks5://user:pass@host:port
• SOCKS4: socks4://user:pass@host:port
• HTTP: http://user:pass@host:port
• MTProxy: mtproxy://secret@host:port

📖 Full environment variable reference: docs/ENVIRONMENT.md

Start with Docker Compose

1. Clone repository.

2. Run docker compose to start all services including the database:

docker compose up -d

3. Access http://localhost:3333 to open the search interface.

💻 Development Guide

Caution

Development requires Node.js >= 24.11 and pnpm. Make sure you have them installed.

Browser-Only Mode

git clone https://github.com/groupultra/telegram-search.git
cd telegram-search
pnpm install
cp .env.example .env
pnpm run dev

Server Mode (with Backend)

git clone https://github.com/groupultra/telegram-search.git
cd telegram-search
pnpm install

# Copy and adjust environment variables (Telegram keys, DB type/URL, proxy, etc.)
cp .env.example .env
# Optionally override in .env.local (ignored by Git)

# Start PostgreSQL with pgvector (or point DATABASE_URL to your own DB)
docker compose up -d pgvector

# Start backend & frontend (two terminals)
pnpm run server:dev  # Terminal 1: WebSocket server (uses .env/.env.local via dotenvx)
pnpm run web:dev     # Terminal 2: Vue frontend

📖 More development details: CONTRIBUTING.md

🏗️ Architecture

This project is a monorepo with event-driven architecture:

• apps/web: Vue 3 frontend
• apps/server: WebSocket server
• packages/client: Client adapters & stores (Pinia)
• packages/core: Event bus (EventEmitter3), services, database models (Drizzle ORM)
• packages/common: Logger & utilities

Key Technologies:

• Event-driven with CoreContext (EventEmitter3)
• Real-time communication via WebSocket
• PostgreSQL + pgvector OR PGlite (in-browser)
• Message processing pipeline: Embedding, Jieba, Link, Media, User resolvers

📖 Full architecture details, event flow, and diagrams: CONTRIBUTING.md

🚨 Warnings

Warning

We have not issued any virtual currency, please do not be deceived.

Caution

This software can only export your own chat records for search, please do not use it for illegal purposes.

🚀 Activity