Telegram Chat Reader

Simple TypeScript CLI that signs in to Telegram with your credentials and exports a chat history to JSON. Telegram API access is handled via GramJS.

Installation

Global CLI

npm install -g @gyach/telegram-export-chat-to-json
tgexp --chat @example_chat

Project-local / NPX

npm install @gyach/telegram-export-chat-to-json --save-dev
npx tgexp --chat @example_chat

Both approaches expose the primary telegram-chat-reader command plus the shorter alias tgexp. When installed locally, run either via npx or add it to your npm scripts.

Configuration

1. Create an application on my.telegram.org to obtain your api_id and api_hash.
2. Create a .env file in the directory where you plan to run the CLI. You can copy the bundled example (e.g., cp node_modules/@gyach/telegram-export-chat-to-json/.env.example .env) or paste the snippet below:

   TELEGRAM_API_ID=123456
   TELEGRAM_API_HASH=yourhash

   Optional variables that reduce interactive prompts:
   • TELEGRAM_SESSION — persisted GramJS StringSession
   • TELEGRAM_PHONE_NUMBER — phone in international format
   • TELEGRAM_PASSWORD — Telegram 2FA password, if enabled

Usage

Run either tgexp or telegram-chat-reader from any directory that contains a configured .env file. The CLI requires at least one argument — the chat identifier (@username, numeric id, or a public link):

tgexp --chat @example_chat

Available flags:

| Flag | Description | |-----------------|---------------------------------------------------------------------------------------------------------------| | --out, -o | Custom export path. If omitted, the tool writes <chat>-YYYY-MM-DD_HH-MM-SS.json to the current directory. | | --limit, -l | Limit on the number of messages to fetch. |

On the first run the script may ask for your phone number, confirmation code, and 2FA password. After successful login it prints a new StringSession; save it into TELEGRAM_SESSION to skip future prompts.

Output

Each export produces a JSON document saved either at the provided --out destination or, by default, in the working directory with a chat-and-date-based filename. The structure looks like this:

{
  "metadata": {
    "chat": "@example_chat",
    "exportedAt": "2024-03-01T12:00:00.000Z",
    "totalMessages": 42
  },
  "messages": [
    {
      "id": 1,
      "date": "2024-02-01T10:00:00.000Z",
      "text": "Hello",
      "fromId": "user:123",
      "peerId": "chat:456",
      "outgoing": true,
      "replyToMessageId": null,
      "mediaType": null,
      "viaBotId": null,
      "fwdFrom": null
    }
  ]
}

Validation

Run a build to ensure TypeScript sources compile:

npm run build

After updating .env, execute a test export (e.g., tgexp --chat <id>) and confirm a JSON file appears in your current directory with the expected chat name and timestamp in its filename.

Local Development

If you are working with the repository sources:

npm install
npm run build
npm start -- --chat @example_chat

npm start relies on ts-node for a faster edit-run loop. The published CLI uses the compiled JavaScript in dist/.