mastros
Back to Blog

Telegram JSONL Export: jq, JSONL CLI Tools, or a No Code Privacy Extension

September 5, 2026·
Telegram JSONL Export: jq, JSONL CLI Tools, or a No Code Privacy Extension

Telegram Desktop exports JSON, not JSONL. There is no toggle for line-delimited output anywhere in the app. To get JSONL for analysis, you convert Telegram's native result.json yourself with jq or Python, or you skip the manual step entirely and run a CLI tool that writes JSONL from the start. For anything beyond a few thousand messages, pick a tool with checkpointing so you never re-fetch a history you already have.

TL;DR:

  • Exported JSON files contain all messages in a nested array, requiring full memory load for processing, while JSONL enables line-by-line processing ideal for large datasets.
  • Converting JSON to JSONL can be easily done with a jq one-liner or a Python script, ensuring scalable ingestion and analysis workflows.
  • CLI tools like telegram-messages-dump or teleman can export data directly in JSONL format, supporting checkpointing for incremental updates in large archives.
  • For repeated or targeted exports, browser extensions like Mastros's Telegram scraper allow users to save selected chats in JSONL without API keys or scripting.
  • Secret chats are not included in exports because they remain stored locally and are end-to-end encrypted, preventing their extraction through standard tools.

Table of Contents

How Do You Export JSON From Telegram Desktop?

Telegram's own export tool is the fastest way to get a raw data file, and it's the only official source of that data. Every third-party JSONL workflow starts here, either by converting the file this produces or by pulling the same underlying data through the API.

  1. Install Telegram Desktop on Windows, macOS, or Linux and sign in with your phone number. Web-only sessions can't reach the export menu, so this step matters more than it sounds.
  2. Let the app fully sync your chats. A partially synced account produces an incomplete export, and Telegram won't warn you about it.
  3. Open Settings > Advanced > Export Telegram data. For a single conversation instead of your whole account, open that chat's menu and choose Export chat history.
  4. Pick JSON as the format (HTML is the other option, and it's built for reading, not parsing). Select which data types to include, contacts, media, sessions, and set a date range if you don't need the full history.
  5. Start the export and let it run. Telegram writes the result into a folder you choose, with a result.json file at the root and a chats/ directory holding per-conversation media.

The Telegram Data Export Schema confirms JSON and HTML are the only two output formats the built-in tool supports, and the Telegram blog's export announcement walks through the same menu path if you want a visual reference. Two operational quirks catch people off guard: brand-new logins sometimes can't export for 24 hours, and Telegram occasionally asks you to confirm the request from another signed-in device before it releases the file. Neither is a bug. It's an anti-abuse measure, and waiting it out is the only fix. For a closer look at what lands inside that export folder, our breakdown of how Telegram Desktop's chat export works covers the file layout in more depth.

Why Does JSONL Beat JSON for Analysis and LLM Ingestion?

The structural difference is small on paper but huge in practice. Telegram's native result.json stores every message inside one giant nested array, so a parser has to load and hold the entire file in memory before it can read message one. JSONL flips that: each line is its own complete, self-contained JSON object, which means a script can read, process, and discard messages one at a time without ever holding the full file in RAM.

That distinction decides which tools you can realistically use downstream:

  • Streaming parsers and shell pipelines handle JSONL line by line, so a 500,000-message export processes the same way whether you have 4GB or 64GB of memory.
  • Vector database ingestion and retrieval-augmented-generation pipelines expect one record per line by convention, since chunking and embedding work message-by-message anyway.
  • AI-agent workflows that watch a folder for new data can tail a JSONL file the way they'd tail a log, which isn't possible with a single nested JSON blob.
  • Small exports or manual review don't need any of this. If you're pulling 200 messages to check a date, plain JSON opened in a text editor is fine.

Maintainers of tools like chatpack-cli point to this exact tradeoff: once a dataset exceeds available memory, JSONL stops being a nice-to-have and becomes the only practical option. Tools built around JSONL as the default output, such as tgcli, still offer a --pretty flag for human inspection, which tells you where the industry has landed: JSONL for machines, formatted JSON only when a person needs to read it directly.

How Do You Convert Telegram's JSON to JSONL?

Once you have result.json, converting it takes one command if you're comfortable with jq, or a short script if you'd rather work in Python.

  1. The jq one-liner. Run jq -c '.messages[]' result.json > messages.jsonl. The -c flag forces compact, single-line output, and mapping over .messages[] emits exactly one object per message, which is the whole trick. If you need ISO-8601 timestamps instead of Telegram's raw date strings, pipe through a second jq filter that reformats the date field before writing.
  2. The Python route, for more control. Write a generator that opens result.json, iterates data["messages"], and writes each message as its own line with json.dumps() plus a newline. Wrap key lookups in .get() rather than direct indexing so a missing field doesn't crash the whole run partway through a 200,000-message file.
  3. Handle attachments deliberately. Don't inline large media files into the JSONL itself. Keep the metadata pointer, the relative file path and MIME type, exactly as Telegram's own export structures it, and leave the actual photo or video sitting in the chats/ folder. Always preserve message_id and date on every row. They're your primary keys if you ever need to deduplicate or merge incremental runs.
  4. Validate before you scale up. Run the conversion on one small chat export first, then check the output with jq '.' messages.jsonl or a JSONL linter before pointing the same script at your full archive.

Open-source exporter code, like the JSONL exporter inside telegram-messages-dump, shows this exact pattern in production: one object per line, dates serialized to ISO format, media handled as a reference rather than inlined bytes.

Pro Tip: Run your conversion script against your smallest, least important chat first. A malformed date field or an unexpected null value will show up in seconds instead of an hour into a full-archive run.

Can CLI Tools Export Telegram Data Straight to JSONL?

Skipping the conversion step entirely is often the better call, especially if you're going to repeat the export on a schedule. Several community tools connect to the Telegram API directly, usually through a Telethon session, and write JSONL as their native output rather than JSON you have to reshape afterward.

  • Streaming export by default. Tools like telegram-messages-dump fetch messages via the API and stream them out as line-delimited JSON, so there's no intermediate result.json to convert.
  • Checkpointing for repeat runs. teleman writes messages.jsonl alongside metadata and checkpoint files, so a second run appends only the new messages instead of re-downloading the whole chat.
  • Filter flags. Options like --since, --limit, and --from let you scope an export to a date window, a message count, or a specific sender without touching the rest of the archive.
  • Agent-friendly defaults. tgcli defaults to JSONL output specifically because downstream agent and pipeline tooling expects it.

The typical workflow: create a Telethon session once, authenticate, list your available chats, then run the export or sync command against the specific chat IDs you want. A single-chat pull might look like exporting one channel's history since a given date; a bulk sync command repeats that across every chat in your account. This route makes the most sense when you're running exports on a recurring schedule, working with a history too large to comfortably reprocess from scratch each time, or feeding data straight into an agent or RAG pipeline where JSONL is the format you need on the other end anyway. Our guide to Telegram data analytics tooling goes deeper on wiring these outputs into a vector database.

What Does a Telegram Export Actually Include?

Both Telegram Desktop's built-in export and API-based takeout tools cover your cloud chats: regular one-on-one conversations, groups, channels, contacts, and account sessions. Media gets pulled down as actual files organized into per-chat folders inside the export directory, not embedded as base64 blobs in the JSON.

  • Secret Chats never leave your device. They're end-to-end encrypted and stored locally by design, so neither Telegram Desktop's export nor any API takeout method touches them.
  • Media downloads have size limits you control. API-based tools expose a file_max_size flag, and skipping large videos or documents speeds up the export considerably.
  • Channels and supergroups behave a little differently from regular chats, particularly around member lists and admin-only content, since Telegram's takeout API scopes those with separate flags (message_channels, message_megagroups) from ordinary chats.
  • Account-level and chat-level exports aren't the same job. A full account export pulls everything at once; exporting a single chat from its menu only touches that conversation.

Telegram's own export documentation frames this feature as a backup and archiving tool, not a live analytics feed, which explains why it's a one-time pull rather than something built to sync continuously.

How Do You Handle Large Archives Without Re-Exporting Everything?

The mistake most people make with a large Telegram history is treating every export as a fresh, full pull. That works fine for a 3,000-message chat. It falls apart once you're dealing with a channel that's been active for three years and holds half a million messages, because re-downloading the whole thing every week just to catch new activity wastes bandwidth and time for no reason.

Tools built around checkpointing solve this by storing where the last run stopped, then fetching only messages after that point on the next run. Filtering by date range or message ID accomplishes something similar even with simpler tools, and splitting exports by chat ID lets you parallelize ingestion instead of processing one enormous file serially. Once you have JSONL on disk, gzip compresses it well since the format is so repetitive line to line, and most streaming pipelines can decompress on the fly during ingestion rather than needing an uncompressed copy sitting around.

Incremental archive checkpoint workflow

Pro Tip: Store each chat's checkpoint file right next to its JSONL output, not in a separate database. When you're troubleshooting a sync that skipped messages, you want the checkpoint and the data it produced sitting in the same folder.

Why Won't Telegram Let Me Export, and How Do I Fix Malformed JSON?

Most export problems trace back to one of three causes, and all three have straightforward fixes.

  • The export option is missing entirely. You're almost certainly in Telegram Web or a mobile app. Switch to Telegram Desktop, where the feature actually lives, and if you just signed in, wait out the 24-hour delay Telegram sometimes imposes on new logins.
  • A large export stalls partway through. Split the job by chat instead of exporting your whole account at once, or drop media from the scope temporarily. CLI tools with checkpointing let you resume from where it stopped rather than starting over.
  • The resulting JSON won't parse. Confirm the file is UTF-8 without a byte-order-mark, run it through jq '.' or a JSONL validator to pinpoint the broken line, and watch for unusual date objects that don't serialize the way your script expects.

Community bug reports on Telegram's own support tracker confirm the 24-hour delay and cross-device confirmation aren't isolated glitches. They're standard behavior baked into how the export feature protects accounts.

A Browser Extension Route: When Does Mastros Make Sense?

Not every export needs the API-and-Telethon route. If you want to pull specific chats or channels straight from your browser, without generating API credentials, spinning up a session file, or uploading anything to a third-party server, a client-side extension covers a different slice of the same problem.

  • No API keys, no second login. The extension reads what your already-signed-in Telegram Web or Desktop session displays and saves it locally. Nothing goes to a Mastros server.
  • Output straight to CSV, JSON, or JSONL. You choose the format at export time instead of converting afterward.
  • Covers more than just messages. Group members, chat messages, recent contacts, and mutual groups all export from the same tool, alongside bulk downloads of photos, videos, documents, audio, and voice notes from any chat you can open.
  • You control the scope. Set how many messages to scan per run, and each exported item carries its type and date, so you can narrow a pull to a specific media type or time window instead of grabbing everything.

Getting started is short: install the Telegram Scraper extension, sign in to your normal Telegram Web session (no separate credentials needed), open the chat or channel you want, and pick JSON or JSONL as your output before running the export. It's a fit for anyone who wants selective, repeatable exports without touching a terminal, which covers a lot of the people who land on a "how do I get this data out" question in the first place. If you also manage WhatsApp groups, the same read-only approach carries over in our Telegram Web export guide.

Why the "One True Method" Advice Misses the Point

Most guides on this topic pick a side. Either they push you toward the Telegram Desktop export and a jq command, or they hand you a GitHub repository and a Telethon setup and call it done. Both miss something obvious once you actually try to use exported chat data: the right method depends entirely on how often you need to run it, not on which one is "more correct."

Why the "One True Method" Advice Misses the Point — overview diagram

A one-time backup of a family group chat doesn't need checkpointing, Telethon sessions, or a conversion script. A researcher pulling a 400,000-message channel into a RAG pipeline every week absolutely does, and skipping that step means burning hours re-downloading data you already have. The overlooked piece is the middle ground: people who want more than a single export but don't want to write and maintain a Python script either. That's where a browser extension earns its place, not as a lesser option next to "real" developer tools, but as the right tool for a specific, common situation.

Treat format choice the same way. JSONL isn't inherently superior to JSON. It's superior for streaming and scale, and irrelevant for a chat you're going to read once in a text editor.

— Elias Mahdavi

Get Telegram Data Into JSON or JSONL Without Writing a Script

If the jq commands and Telethon sessions above sound like more setup than your actual task needs, that's the gap Mastros fills. Its Telegram extension runs entirely in your browser against your own signed-in session, no API keys, no server uploads, no separate login, and exports group members, chat messages, recent contacts, and mutual groups directly to CSV, JSON, or JSONL. Bulk media downloads cover photos, videos, documents, and voice notes from any chat you can open, with each item's type and date attached so you can scope a run precisely. It's designed for users who need repeatable, selective exports without maintaining conversion scripts. Install the extension, sign in to your normal Telegram session, and run your first export today.

Sources

FAQ

How Can I Export My Data From Telegram?

Open Telegram Desktop, go to Settings > Advanced > Export Telegram data, choose JSON as the format, select what to include, and start the export to generate a result.json file plus a media folder.

Can Deleted Telegram Chat History Be Recovered?

Telegram's export tool only pulls data currently synced to your account. It cannot recover messages you've already deleted, since deletion removes them from Telegram's servers, not just from your local view.

How Do I Export a Telegram Chat to a PDF?

Telegram doesn't offer a native PDF export option, only JSON and HTML. Exporting to HTML and printing that file to PDF through your browser is the closest workaround.

How Do I Get JSONL Instead of JSON From Telegram?

Convert Telegram's native result.json with a jq command or a short Python script, or use a CLI tool such as telegram-messages-dump that writes JSONL directly, or use a browser extension like Mastros's Telegram scraper that lets you select JSONL as the output format at export time.

Does Telegram's Export Include Secret Chats?

No. Secret Chats are end-to-end encrypted and stored only on your device, so neither the Desktop export nor API takeout tools can include them.

Recommended

More from the blog