How to Export Telegram Chat History: Desktop, JSON and the API

The short answer

Telegram Desktop is the only official client with a built-in export tool. It outputs your chats into HTML or JSON files. First-time exports trigger a mandatory security delay before the download begins. Individual chat exports finish faster through the chat options menu. If your account holds large group histories or needs automated runs, you must write a script against the Telegram MTProto API. The standard Bot API cannot read your historical messages.

Export everything from Telegram Desktop

The desktop app on macOS, Windows, and Linux contains the full export engine. The web client and mobile apps on iOS and Android do not have this feature.

Download Telegram Desktop from desktop.telegram.org. Sign in with your phone number and complete the two-step verification code.

1. Open the left sidebar menu and click Settings.
2. Click Advanced.
3. Scroll down the Advanced page and click Export Telegram data.
4. Select the message types to include. Check Personal chats, Bot chats, Private groups, Only my channels, Public groups, and Public channels depending on your needs.
5. Check the media types you want to save. Your options include Photos, Video files, Voice messages, Video messages, Stickers, Animated GIFs, and generic Files.
6. Adjust the size limit slider for downloaded media. The slider sets a maximum size for one file, and the top of its range depends on your client version, so read what it says before you commit. Media above the value you pick gets skipped. The message text referencing it still lands in the export, which is how you end up with a transcript full of attachments that are not there.
7. Choose your export format at the bottom of the window. You can pick Human-readable HTML or Machine-readable JSON.
8. Set the date range to limit how far back the export goes. Leave it open to export the entire history.
9. Choose an output folder on your local drive.
10. Click Export.

Telegram Desktop Export Folder/
├── css/
├── js/
├── images/
├── video_files/
├── voice_messages/
├── chats/
│   ├── chat_01/
│   │   └── messages.html (or result.json)
│   └── chat_02/
└── export_results.html

The output folder contains your selected assets along with an index file. If you selected HTML, opening export_results.html in a web browser shows your chat list with full styling, avatars, and embedded media players. If you selected JSON, Telegram creates a single result.json file inside the root folder containing the structured data for all selected chats.

Export one chat

Exporting your entire account takes significant time. You can export a single conversation if you only need records from one client or group.

1. Open the specific direct message, group, or channel in Telegram Desktop.
2. Click the three vertical dots in the top right corner of the chat window.
3. Select Export chat history.
4. Choose the media formats, size limits, and date range for this specific chat.
5. Choose between HTML and JSON format.
6. Click Export.

Single chat exports run immediately. They do not trigger the account-wide security delay that Telegram applies to full account dumps.

The 24 hour wait

Telegram applies a security block when you request a full account export for the first time on a new desktop session.

The application displays a modal stating that the export was requested from a new device. Telegram sends a service notification to your active mobile app sessions. The notification warns that data has been requested and that the export stays locked for 24 hours, which gives you time to terminate a session you do not recognise.

You cannot bypass this security delay through Telegram Desktop settings or support tickets. If you need historical records for an urgent legal or operational deadline, request the export 24 hours before you plan to download the files. Keep the desktop client installed and logged in while the timer runs. Once the countdown expires, reopen the Export Telegram data menu and trigger the export again to start the download.

HTML or JSON

Select both formats across two separate runs if your storage allows it. The HTML build provides an interface for humans who need context, while the JSON export allows programmatic ingestion into analytics databases or search indices.

What the JSON actually contains

The JSON export structures your conversations under a root object. It contains metadata about your account, followed by an array of chat objects.

{
  "name": "Exported Data",
  "about": "Telegram personal data export",
  "chats": {
    "list": [
      {
        "name": "Diamond Operations Desk",
        "type": "private_group",
        "id": 1492049102,
        "messages": [
          {
            "id": 10420,
            "type": "message",
            "date": "2024-03-12T14:22:01",
            "date_unixtime": "1710253321",
            "from": "Alexandre V.",
            "from_id": "user8912401",
            "text": "Confirmed parcel arrival in Antwerp."
          },
          {
            "id": 10421,
            "type": "message",
            "date": "2024-03-12T14:23:45",
            "date_unixtime": "1710253425",
            "from": "Marc H.",
            "from_id": "user4410924",
            "text": [
              "See tracking manifest at ",
              {
                "type": "link",
                "text": "https://vault.example.com/manifest/9941"
              },
              " for details."
            ]
          }
        ]
      }
    ]
  }
}

The message body handling causes issues for standard parsing scripts. When a message contains plain text, the text field is a standard string. When a message contains links, mentions, bold formatting, code blocks, or emojis, Telegram converts the text field into an array of mixed elements. Plain text becomes a string element inside the array, while formatted text becomes an object with a type and a text attribute. Every message also carries a text_entities array, which is always a list of objects. Reading from that field instead of text saves you the type check.

Scripts expecting every text property to be a raw string will crash on formatted messages. Your ingestion code must inspect the type of the text field before writing to a database.

Groups, supergroups and channels

Small groups operate differently from supergroups. Basic groups hold up to 200 people. When a group passes that limit or when an admin enables advanced permissions, Telegram upgrades the group into a supergroup with a capacity of up to 200,000 members.

Supergroups load history from the server in pages. Exporting a supergroup with five years of trading chatter requires downloading hundreds of thousands of individual message payloads. The desktop client slows down while processing these backlogs because the server throttles pagination calls.

Telegram channels allow unlimited subscribers and present the same volume considerations. If you export a public channel with a large media archive, expect the process to take several hours over a standard broadband connection.

Secret chats never appear in any export. Telegram creates secret chats with end-to-end encryption tied to specific hardware devices using the MTProto protocol. Secret chat messages do not live on Telegram cloud servers. The desktop client does not support secret chats, so they cannot be included in desktop export jobs.

Exporting through the API

When you need automated exports, continuous backups, or bulk data extraction without manual clicks, use the Telegram MTProto API.

The standard Telegram Bot API will not work for historical extraction. Bots created via BotFather only receive messages sent after the bot joined the group. Bots cannot query arbitrary chat history prior to their join date.

To extract complete history, create an MTProto user client:

1. Log into my.telegram.org using your phone number.
2. Go to API development tools.
3. Fill out the application form to generate an api_id and api_hash.
4. Install an MTProto client library in Python, such as Telethon or Pyrogram.

The following Python script uses Telethon to walk backward through a chat history and handle rate limit blocks:

import asyncio
import json
from telethon import TelegramClient
from telethon.errors import FloodWaitError
from telethon.tl.types import Message

api_id = 1234567
api_hash = 'your_api_hash_here'
chat_target = 'diamond_trading_group'

client = TelegramClient('export_session', api_id, api_hash)

async def dump_history():
    await client.start()
    chat = await client.get_input_entity(chat_target)
    records = []
    
    try:
        async for message in client.iter_messages(chat, limit=None):
            if isinstance(message, Message) and message.text:
                records.append({
                    "id": message.id,
                    "date": message.date.isoformat(),
                    "sender_id": message.sender_id,
                    "text": message.text
                })
    except FloodWaitError as err:
        print(f"Hit rate limit. Sleeping for {err.seconds} seconds.")
        await asyncio.sleep(err.seconds)
    
    with open("chat_dump.json", "w", encoding="utf-8") as f:
        json.dump(records, f, indent=2, ensure_ascii=False)

if __name__ == "__main__":
    with client:
        client.loop.run_until_complete(dump_history())

This script connects to Telegram as your personal user account. It iterates through every message in the specified chat and appends the raw text and sender IDs to a local list before writing to disk.

Rate limits in practice

Telegram protects its server infrastructure using dynamic rate limits known as flood limits. The API does not publish fixed request-per-second numbers. Limits vary based on server load, account age, the volume of data fetched, and the endpoint in use.

When you exceed the allowed request rate, the API raises a FloodWaitError containing an integer value. This number tells you the exact number of seconds you must pause before sending another request. For minor overages, the wait time ranges between 5 and 60 seconds. For aggressive bulk scraping across multiple large supergroups, Telegram will return wait times reaching several hours or even days.

If your script ignores these errors and continues hammering the endpoint, Telegram will deactivate your active session or ban your phone number from the platform. Always catch flood exceptions in your network layer and pass the returned wait value directly into your sleep timer before resuming pagination.

You can learn more about managing chat exports on other communication platforms in our guide to Discord server exports.

Keeping the archive instead of exporting it

Manual file exports leave your historical data scattered across zip archives and unindexed local drives. Once you export a folder from Telegram Desktop, that data is static. It does not update when clients edit terms, send follow-up documents, or delete key messages in active group threads.

Connecting your accounts to CommunicationOS maintains an indexed, real-time record of all your operational messaging channels. Messages stay permanently searchable alongside your records from WhatsApp, Signal, Discord, and email. You can run automated data exports whenever legal teams require offline files, without waiting through security lockouts or managing custom API scripts. Review our pricing plans to set up permanent indexing for your organisation.