mastros

Get Telegram's result.json: Export to JSON and Analyze with jq, pandas

September 6, 2026·
Get Telegram's result.json: Export to JSON and Analyze with jq, pandas

The fastest way to export Telegram to JSON is Telegram Desktop's built-in tool: go to Settings → Advanced → Export Telegram data, choose JSON as the format, and click Export. The output lands in a folder on your computer as result.json, alongside a chats/ directory holding any media you included. No account access, no third-party app, no waiting for Telegram to email you a link.

TL;DR:

  • Exporting full Telegram data as JSON includes personal info, chat lists, and messages, but private messages in public channels are limited to your own contributions.
  • Media files are stored separately in folders, with JSON referencing relative paths; message IDs can exceed safe integer limits in JavaScript if not handled properly.
  • Automation using MTProto-based tools like Telethon enables incremental, scalable exports across many chats, but requires coding knowledge and API setup.
  • Offline analysis tools such as jq and pandas simplify extraction and transformation of exported data into readable formats like CSV or Excel, suitable for detailed examination.
  • Full account exports can take from minutes to over an hour depending on media volume, and partial exports or single chats are faster and smaller, ideal for targeted backups.

Table of Contents

How to Export Telegram Data From Telegram Desktop (Full Account)

If you want everything, this is the route. It pulls your personal information, contact list, and chat history into one structured archive, following the layout Telegram documents in its Chat Export Tool announcement.

Here's the process, start to finish:

  1. Install or update Telegram Desktop. The export feature only lives in the official Desktop client, not the mobile apps or Telegram Web. If you already have Desktop installed, check for updates first. Older builds sometimes hide or break the export menu entirely.
  2. Sign in with the account whose data you want to pull.
  3. Open Settings → Advanced, and scroll down to Export Telegram data.
  4. Pick your categories. You'll see checkboxes for personal chats, group chats, channels, contacts, and account info. Uncheck anything you don't need to keep the archive smaller.
  5. Set the format to JSON. Telegram defaults to a human-readable HTML export, so this step matters. If you're planning to run any analysis, JSON is the format that will actually cooperate with scripts later.
  6. Choose a date range and media options. You can limit the export by time period and decide whether to include photos, videos, voice notes, and documents, or skip media to save space.
  7. Pick your export folder. Choose a local drive, not a network share or a synced cloud folder mid-sync, since Telegram writes many small files rapidly during export and network latency can corrupt or stall the process.
  8. Click Export and wait. Small accounts (a few thousand messages, no media) finish in under a minute. Full accounts with years of media across dozens of chats can take anywhere from several minutes to over an hour.

Telegram names the output folder something like Telegram Desktop/DataExport_01_02_2026, and inside it you'll find result.json at the top level, with a chats/ subfolder underneath.

If the export interrupts or your disk runs low on space, just re-run it. Telegram doesn't merge partial exports, so you'll want to clear out the incomplete folder first.

Pro Tip: Run the export overnight if you're pulling years of media. A multi-gigabyte archive with thousands of photos and voice notes can tie up your disk for a while, and there's no reason to babysit it.

Exporting a Single Chat or Channel Instead of Your Whole Account

Sometimes a full export is overkill. If you just need one conversation, whether it's a work group, a channel you admin, or a chat you want backed up before deleting it, Telegram lets you export it directly from the conversation itself.

  • Open the chat, tap the ⋯ menu in the top right, and select Export chat history.
  • Choose your format. HTML is the default for quick reading, but you can select JSON (or both) if you plan to process the data later.
  • Set the same options as the full export: date range, media types, and whether to include service messages like pinned notices or member changes.
  • Telegram saves the result as result.json inside its own folder, separate from any full-account export you've run.

Single-chat exports finish faster and produce a smaller file, which makes them the better call when you're archiving one community before it goes quiet, or pulling a specific conversation for a report instead of your entire message history.

What's Actually Inside result.json?

The official Telegram Data Export Schema lays out exactly how the archive is structured, and it's worth understanding before you start writing scripts against it.

At the top level, result.json contains:

  • personal_information: your account's name, phone number, and username, present only in full-account exports.
  • chats.list[]: an array of chat objects, each with an id, name, and type (personal_chat, private_group, private_supergroup, public_channel, and so on).
  • messages[]: nested inside each chat, this is the core of the archive, with id, date (ISO 8601 format), from, from_id, text, and, where relevant, a photo or file field pointing to a relative media path.

Media never gets embedded as base64 or binary data inside the JSON. Instead, every photo, video, or voice note is saved as an actual file inside chats/chat_name/photos or a similar subfolder, and the JSON just stores the relative path string.

One detail that trips up developers building importers: Telegram's id fields for messages and users can exceed the safe integer range in JavaScript (anything past 2^53). Parse them as strings or use a 64-bit-safe numeric type in whatever language you're working in, or you'll get silent rounding errors on large accounts. Dates follow the ISO 8601 standard, which makes them straightforward to parse into any timezone-aware date library.

How Do You Analyze the Exported JSON File?

Once you have result.json, the real question becomes what to do with it. Two tools cover almost every use case: jq for quick command-line filtering, and Python's pandas for anything resembling actual analysis.

For fast, no-setup queries, jq handles the basics in one line each:

  1. Count total messages in a chat: pipe result.json through jq '.messages | length'.
  2. Filter by sender: use jq '.messages[] | select(.from == "Name")' to pull every message from one person.
  3. Extract just text and dates: jq '.messages[] | {date, text}' strips out everything else for a lightweight readable log.

For anything beyond quick lookups, load the file into pandas. The general workflow: read result.json with Python's built-in json module, then run pd.json_normalize() on the messages array to flatten it into a data frame. From there, convert the date column to a proper datetime type, and you can group by sender, plot message frequency over time, or filter by keyword just like any other tabular dataset. A walkthrough using this exact approach shows how quickly a raw export turns into a usable chart.

If you're dealing with hundreds of thousands of messages, consider converting to JSONL instead of working with Telegram's pretty-printed JSON directly. Each line becomes one self-contained message object, which lets streaming tools and log processors read the file incrementally instead of loading the whole structure into memory. Our guide on converting exports to JSONL walks through the conversion step by step. Tools built on Telegram's MTProto layer, like Telethon-based scripts or the community project telegramFetcher, output JSONL natively and support incremental syncing, so you only pull new messages on each run instead of the full history every time.

Pro Tip: If you're only after message counts or a quick sender breakdown, skip pandas entirely. A one-line jq command does the job in seconds without spinning up a Python environment.

What Are the Export Limits and Privacy Risks?

Telegram's export tool is generous, but it has real boundaries you should know before you rely on it for anything important.

  • Public channels and groups only export messages sent by your own account. If you're archiving a channel you don't own, Desktop export won't hand you the full message history from other members, only your contributions to it, according to the official schema documentation. Private one-on-one chats and groups you're fully part of export in full.
  • Media paths are relative, not absolute. If you move the export folder or rename it, the JSON references still work, but only if the folder structure underneath stays intact.
  • Very large files can hit size ceilings depending on your Telegram plan and local storage, so multi-gigabyte video archives may need to be split across multiple export runs by date range.
  • Deleted messages generally don't reappear in a fresh export. If a message was removed before you ran the export, it won't be in result.json. Export regularly if message history matters to you.

Because the archive holds phone numbers, private conversations, and possibly sensitive documents, treat it like any other personal data backup: store it on an encrypted drive, avoid syncing it to a shared cloud folder by default, and delete old exports once you've pulled what you need.

How Do You Fix Common Telegram Export Errors?

Most export failures trace back to one of a handful of causes, and they're usually quick to fix.

  1. Export option missing from Settings entirely? Update Telegram Desktop to the latest version. Older builds occasionally hide this feature behind a version gate.
  2. Export stalls or fails partway through? Check your disk space first, then confirm you picked a local folder rather than a network drive or a cloud-sync folder that's actively uploading. Both scenarios cause write conflicts mid-export.
  3. Some media files missing from the folder? Re-run the export. Telegram sometimes skips files that were temporarily unavailable on its servers during the first pass.
  4. History too large to export in one go? Narrow the date range and run it in chunks, or switch to a single-chat export instead of pulling your whole account at once.

For persistent issues, our step-by-step troubleshooting guide covers fixes for the errors that don't resolve with a simple retry.

Can You Use Telegram's Bot API or CLI Tools to Export JSON?

Telegram's Bot API isn't built for exporting your own chat history. Bots can only see messages sent directly to them or in groups where they're a member, so a bot can't pull your full private message archive the way Desktop's export tool can. If your goal is exporting personal or group chat history, the Desktop export or the MTProto-based tools below are the right path, not the Bot API.

What actually works for programmatic export is Telegram's MTProto takeout API. This is the same protocol layer Desktop itself uses under the hood, and it's documented in the official takeout API reference. The flow looks like this:

  1. Call account.initTakeoutSession to open a takeout session tied to your account, specifying which data categories you want (messages, media, contacts).
  2. The server processes your request and makes the data available through standard message-fetching calls, now flagged as part of a takeout session.
  3. Media files are pulled separately using upload.getFile, since the takeout session gives you access but doesn't bundle media inline.
  4. Call account.finishTakeoutSession once you've retrieved everything, closing out the session cleanly.

This isn't something you type into a terminal casually. It requires registering an app with Telegram's API, handling authentication tokens, and writing code against the MTProto library in Python (Telethon is the most common choice) or another supported language. Community tools built on this layer, like the tg-export project, transform raw takeout output into cleaner, ingestion-ready JSON. This route makes sense for developers building automated pipelines, not for someone who just wants a backup of their own chats.

Converting Telegram JSON to CSV or Excel for Analysis

Telegram's JSON export is great for scripts, but plenty of people just want a spreadsheet. Getting there takes a few extra steps, and the right tool depends on how much data you're moving.

For a one-time conversion, Python's pandas library is the simplest bridge. Load result.json, flatten the messages array with pd.json_normalize(), and export straight to CSV with .to_csv() or to Excel with .to_excel(). That single conversion step turns a nested JSON structure into rows and columns any spreadsheet program can open.

If you'd rather skip scripting entirely, jq can output CSV directly with its @csv filter, piping selected fields like date, sender, and message text into a flat file in one command. This works well for smaller chats where you only need a handful of columns and don't want to install a Python environment.

For non-technical use, some online JSON-to-CSV converters accept a file upload and return a spreadsheet in seconds, though you should be cautious uploading anything containing phone numbers or private messages to a third-party web tool you don't control. Anything with sensitive personal data is better handled locally.

One thing to watch for regardless of method: Telegram's message text field sometimes contains nested formatting entities (bold, links, mentions) as separate array structures rather than plain strings. A naive conversion can leave you with [object Object] in a cell instead of readable text, so flatten those entity arrays into plain text before exporting if readability matters more than preserving formatting metadata.

Automating Exports Across Multiple Chats or Large Datasets

Manually re-running Desktop's export tool for a dozen channels gets old fast, and it's not built for scale. If you're managing exports across many chats regularly, automation is worth setting up.

The most common approach uses Telethon, a Python library built on Telegram's MTProto layer, to script exports programmatically. A basic pattern loops through a list of chat IDs, calls the message-fetching functions for each, and writes results to individual JSON or JSONL files, letting you schedule the whole batch to run overnight or on a cron job. This is the same underlying protocol the takeout API uses, just wrapped in a friendlier scripting interface.

Command-line tools like telegramFetcher build on this pattern natively, supporting incremental sync so each run only pulls new messages since the last export instead of redownloading full history every time. That distinction matters a lot once you're tracking dozens of channels: incremental sync turns a process that takes hours into one that takes seconds after the first run.

For teams that need reproducible, byte-stable archives without repeated logins, offline transform pipelines like tdl feeding into tg-export produce consistent JSON output from a single authenticated pull, which is useful when you need the same export to look identical every time you regenerate it.

If your batch needs are narrower, say, pulling member lists and recent messages from a handful of groups without writing any code, a browser-based export extension handles that without the setup overhead of a scripting environment.

Desktop Export vs. Browser-First Tools: A Practitioner's View

Desktop's export tool is the right call when you want a complete, official archive: every message, every contact, every media file, structured exactly the way Telegram's own schema defines it. But for selective work, pulling one channel's members, a date range of messages, or just the media from a single conversation, a browser-first tool that runs locally and never uploads your data gets you there faster, with less cleanup afterward.

— Elias Mahdavi

A Faster Way to Pull Just What You Need

Desktop's export tool is thorough, but it exports categories, not selections. If you manage a Telegram community and just need the member list, recent contacts, or a bulk download of shared media from one specific chat, Mastros gets you there without touching a JSON schema at all.

The Telegram extension runs entirely inside your browser, reading what your own signed-in session already shows, and saves group members, chat messages, recent contacts, and mutual groups straight to CSV, JSON, or JSONL. It also bulk-downloads photos, videos, documents, and voice notes from any chat you can open, with no uploads, no API keys, and no second login. Users such as growth teams, researchers, and community managers use it for fast, selective pulls instead of full-account dumps. Try the available plans to see export limits firsthand, and check the Telegram media downloader page for the full feature breakdown.

Official Docs and Advanced Tools Worth Bookmarking

For deeper reference: Telegram's export announcement, the import-export schema, the takeout API, and our own guide to how Desktop export works.

Sources

FAQ

How Do I Export Data From Telegram?

Use Telegram Desktop's Settings → Advanced → Export Telegram data menu, choose JSON as the format, and select which chats, media, and date ranges to include.

Can Deleted Telegram Chat History Be Recovered?

Not through the standard export tool. If a message was deleted before you ran the export, it generally won't appear in result.json, so exporting regularly is the best safeguard.

How Can I Request My Data From Telegram?

Telegram doesn't require a formal data request process like some platforms. Instead, you export your own data directly through Desktop's built-in export feature, which produces the archive locally on your device.

Can I Export a Telegram Chat as a PDF?

Telegram's native export offers HTML and JSON, not PDF directly. Export as HTML first, then use your browser's built-in "Print to PDF" function to convert the resulting file.

What's the Difference Between JSON and JSONL for Telegram Exports?

Telegram's native export produces one pretty-printed JSON file with a nested structure, while JSONL stores each message as its own line, which streaming tools and large pipelines handle more efficiently.

Recommended

More Telegram guides