📁 Filogram

Why pay for cloud storage? Store files directly in Telegram with a clean REST API. Zero cost, zero hassle.

📦 Tech Stack

• Node.js + Express.js – API server
• MongoDB + Mongoose – Store file metadata
• Multer – Handle multipart file uploads (memory storage)
• Axios – Call Telegram Bot API
• dotenv – Environment variable management

🚀 Getting Started

Option A — Use as an npm Package (Recommended)

1. Install globally:

npm install -g filogram

2. Create a .env file anywhere on your machine:

PORT=3000
MONGO_URI=mongodb://localhost:27017/my-files
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

3. Run from the same folder as your .env:

filogram

You should see:

✅ Connected to MongoDB
🚀 Server running on http://localhost:3000

Option B — Run Locally (Development)

1. Prerequisites

• Node.js v18+
• MongoDB running locally or a MongoDB Atlas URI
• A Telegram bot token (create one via @BotFather)
• Your Telegram Chat ID (send a message to your bot, then visit https://api.telegram.org/bot<TOKEN>/getUpdates)

2. Clone & Install

cd filogram
npm install

3. Configure Environment

Copy .env.example to .env and fill in your values:

cp .env.example .env

PORT=3000
MONGO_URI=mongodb://localhost:27017/filogram
TELEGRAM_BOT_TOKEN=your_real_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

4. Run the Server

npm run dev   # development
npm start     # production

Server starts at: http://localhost:3000

📡 API Endpoints

1. POST /api/upload – Upload a file

| Field | Value | |---|---| | Method | POST | | URL | http://localhost:3000/api/upload | | Body type | form-data | | Key | file (type: File) | | Allowed types | PDF, JPG, PNG | | Max size | 50 MB |

Response:

{
  "success": true,
  "id": "65f1a2b3c4d5e6f7a8b9c0d1",
  "name": "file.pdf"
}

2. GET /api/file/:id – Get file download URL

| Field | Value | |---|---| | Method | GET | | URL | http://localhost:3000/api/file/65f1a2b3c4d5e6f7a8b9c0d1 |

Replace 65f1a2b3c4d5e6f7a8b9c0d1 with the id returned from the upload endpoint.

Response:

{
  "success": true,
  "id": "65f1a2b3c4d5e6f7a8b9c0d1",
  "name": "file.pdf",
  "url": "https://api.telegram.org/file/bot<TOKEN>/documents/file_123.pdf",
  "createdAt": "2024-03-23T10:00:00.000Z"
}

⚠️ Telegram file URLs expire after ~1 hour. Always call this endpoint to get a fresh URL.

3. GET /api/files – List all uploaded files

| Field | Value | |---|---| | Method | GET | | URL | http://localhost:3000/api/files |

Response:

{
  "success": true,
  "count": 2,
  "files": [
    {
      "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
      "originalName": "file.pdf",
      "telegramFileId": "BQACAgIAA...",
      "createdAt": "2024-03-23T10:00:00.000Z"
    }
  ]
}

📁 Project Structure

filogram/
├── controllers/
│   └── fileController.js
├── models/
│   └── File.js
├── routes/
│   └── fileRoutes.js
├── services/
│   └── telegramService.js
├── utils/
│   └── fileFilter.js
├── app.js
├── server.js
├── .env.example
└── package.json

❌ Error Responses

All errors return JSON in this shape:

{
  "success": false,
  "error": "Description of the error"
}

| Scenario | Status | |---|---| | No file provided | 400 | | Invalid file type | 400 | | File too large (>50MB) | 400 | | File ID not found in DB | 404 | | Telegram / server error | 500 |