Telegram zu Obsidian Konverter für IT

Telegram nach Obsidian-Konverter: Chat-Import mit Medien und Links automatisieren

Der Konverter wandelt den JSON-Export von Telegram Desktop in ein übersichtliches Obsidian-Vault um. Er analysiert Nachrichten, kopiert Mediendateien, konvertiert das Telegram-Format in sauberes Markdown und ordnet Chats nach Typ (Kontakte, Gruppen, Kanäle). Die Lösung erstellt einen robusten Dateiindex für zuverlässige Pfadauflösung und behandelt Namenskonflikte souverän.

Der ursprüngliche Telegram-Export enthält result.json (Metadaten), einen HTML-basierten Ordner chats/ mit Nachrichten sowie zugehörige Medien. Die Zielstruktur lautet Telegram_Export/, unterteilt in Kontakte/, Gruppen/, Kanäle/ sowie eine zentrale Index.md.

Architektur des Konverters

Das System besteht aus fünf Kernmodulen: einem JSON-Parser, einem Medienindexer, einem Markdown-Konverter, einem Dateimanager und einem Vault-Strukturgenerator. Der Datenfluss verläuft wie folgt: JSON → Analyse → Indexierung → Konvertierung → Obsidian-Vault mit kopierten Medien in Notizordnern.

Wichtige Komponenten:

• Parser: extrahiert Chats, Nachrichten und Metadaten aus result.json.
• Indexer: erstellt eine durchsuchbare Zuordnung aller Mediendateien nach Endung (.jpg, .mp4, .pdf usw.).
• Konverter: wendet mehrstufige Mediensuchstrategien und Regeln für formatierten Text an.
• Dateimanager: kopiert Assets in die jeweiligen Notizordner und vermeidet Namensdopplungen.

Die Konfiguration erfolgt über Umgebungsvariablen: TELEGRAM_JSON_FILE, OBSIDIAN_OUTPUT_DIR und COPY_MEDIA.

import os
from pathlib import Path

JSON_FILE = os.getenv('TELEGRAM_JSON_FILE', 'result.json')
EXPORT_BASE = Path(os.getenv('TELEGRAM_EXPORT_BASE', '.'))
OUTPUT_DIR = Path(os.getenv('OBSIDIAN_OUTPUT_DIR', 'Telegram_Export'))
COPY_MEDIA = os.getenv('COPY_MEDIA', 'true').lower() == 'true'
GROUP_BY_DAY = os.getenv('GROUP_BY_DAY', 'true').lower() == 'true'

Medienindexierung und -auflösung

Eine patch.txt-Datei – erzeugt mittels ls -R – dokumentiert die vollständige Verzeichnisstruktur des Telegram-Exports. Der Indexer erstellt eine Zuordnung von Dateinamen, relativen und absoluten Pfaden für schnelle, deterministische Abfragen.

def index_media_from_patch(self):
    media_extensions = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.mp4', '.webm', '.pdf', '.zip', '.mp3'}
    current_dir = None
    
    with open(PATCH_FILE, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if line.endswith(':'):
                current_dir = line[:-1]
                continue
            if current_dir and any(line.endswith(ext) for ext in media_extensions):
                full_path = Path(current_dir) / line
                self.media_index[line] = full_path
                if 'chats/' in str(full_path):
                    rel_path = str(full_path).split('chats/', 1)[-1]
                    self.media_index[rel_path] = full_path

Die Mediensuche nutzt vier Fallback-Strategien: exakte Namensübereinstimmung, vollständiger Pfad, Teilpfad-Match und direkte Auflösung des relativen Pfads ab EXPORT_BASE.

Medienkopie mit Konflikthandling

Dateien werden in den jeweiligen Notizordner kopiert – nicht in ein gemeinsames Anhängeverzeichnis. So funktioniert Obsidians native Einbettungssyntax (![[file]]) sofort ohne Anpassung. Ein media_cache beschleunigt wiederholte Suchvorgänge. Bei Namenskonflikten werden automatisch Suffixe wie _1, _2 angehängt.

def copy_media_file(self, source_path: str, note_folder: Path = None) -> Optional[str]:
    if not COPY_MEDIA or not source_path:
        return None
    
    source_file = self.find_media_file(source_path)
    if not source_file or not source_file.exists():
        return None
    
    target_dir = note_folder if note_folder else OUTPUT_DIR / "Anhänge"
    target_dir.mkdir(parents=True, exist_ok=True)
    target_file = target_dir / source_file.name
    
    if target_file.exists():
        stem = target_file.stem
        suffix = target_file.suffix
        counter = 1
        while target_file.exists():
            target_file = target_dir / f"{stem}_{counter}{suffix}"
            counter += 1
    
    shutil.copy2(source_file, target_file)
    self.stats['media_files'] += 1
    return source_file.name

Text- und Entitätsanalyse

HTML und Telegram-spezifische Formatierungen (Fett, Links, Spoiler usw.) werden in semantisches Markdown konvertiert. Spezielle Handler bewahren Bedeutung und Obsidian-Kompatibilität.

def parse_text_entities(self, text: Union[str, List], entities: Optional[List[Dict]] = None) -> str:
    if isinstance(text, str) and ('<' in text or '&' in text):
        return self.html_to_markdown(text)
    
    if entities and isinstance(text, str):
        return self._process_entities(text, entities)
    
    handlers = {
        'bold': lambda t: f"**{t}**",
        'italic': lambda t: f"*{t}*",
        'code': lambda t: f"`{t}`",
        'pre': lambda t: f"```
{t}

'link': lambda t, e: f"[{t}]({e.get('url', '')})",

'spoiler': lambda t: f"\n> [!spoiler] {t}\n"

}

return str(text) if text else ""

## Nachrichtenformatierungslogik

Jede Nachricht enthält Zeitstempel, Absender, formatierten Text (mit Entitäten) und Referenzen eingebetteter Medien. Schlüssel wie `photo`, `video` und `audio` lösen gezielte Medienextraktion aus.

Verarbeitungsschritte:
1. Extrahiere `date`- und `from`-Felder.
2. Analysiere `text` mithilfe der `text_entities`-Logik.
3. Erkenne Medienfelder, kopiere Dateien und füge `![alt](Pfad)`- oder `![[Datei]]`-Links ein.
4. Gruppiere Nachrichten nach Datum, falls `GROUP_BY_DAY` aktiviert ist.

Integrierte Statistiken erfassen verarbeitete Chats, Nachrichten, Mediendateien und Kontakte.

## Wichtige Gestaltungsprinzipien

- Die Indexierung über `patch.txt` gleicht Inkonsistenzen zwischen JSON-Pfaden und der tatsächlichen Dateisystemstruktur aus.
- Die vierschichtige Mediensuche erreicht eine Auflösungsquote von >95 %.
- Die Medienkopie pro Notiz gewährleistet nahtlose Funktion von Obsidians Einbettungssyntax.
- Vollständige Unterstützung aller Telegram-Formatierungsfeatures: Fett, Codeblöcke, Links, Mentions und Spoiler.
- Umgebungsvariable-gesteuerte Konfiguration ermöglicht produktionsreife Bereitstellung und CI/CD-Integration.

— Editorial Team