README.md (10714B)
1 # WhatsApp Logger (Self-Hosted) 2 3 A privacy-focused, self-hosted WhatsApp archiving tool. It captures messages (including deleted ones) via a linked device connection and stores them in your own Firebase Firestore database. 4 5 >[!TIP] 6 > Now you can see the server logs in the frontend by going to `Settings` -> `System Diagnostics` -> Toggle `Live server logs`. Also you can visit `https://your-app.onrender.com/logs` after login to see the logs. 7 8 ## Upgrade Notes (v4.2.x) 9 10 If you're updating from an older version, here's everything that changed across the v4.2.x line in one place: 11 12 * **v4.2.1 — Security fix:** Removed the public Firebase Web SDK config from the frontend. The frontend now only talks to your Render backend, never Firestore directly. Update your Firestore rules to deny all direct client access as shown in [Step 1](#step-1-firebase-setup-the-database). 13 * **v4.2.2 — Real-time sync now covers every chat, not just the one you have open:** Previously, new messages only arrived for a chat you already had open — anything happening in other chats sat on the server until you clicked into them. Now a single sync connection streams updates for *all* chats at once, so incoming messages show up across every contact the moment they arrive, the way WhatsApp itself behaves when your phone comes back online. 14 * **v4.2.2 — Full resync with real progress:** `Settings` -> refresh icon -> `Hard Reset` now pulls your entire message history chat-by-chat instead of one giant download, so the progress bar reflects actual messages fetched instead of a rough guess. Use this if you ever open a chat that shows nothing locally even though the server has history for it (e.g. after clearing site data or on a new device/browser). 15 * **UI refresh:** Reworked to three selectable themes — Catppuccin Latte (light), Catppuccin Mocha (dark), and a true-black AMOLED theme — replacing the old dark-mode toggle and the multiple chat-background picker. Find it under `Settings` -> `Appearance` -> `Theme`. 16 17 > [!IMPORTANT] 18 > Using this logger is completely safe and will not get your WhatsApp account banned. Here is why: 19 > 20 > * **100% Passive (Read-Only):** WhatsApp bans accounts for *sending* spam, bulk messages, or unauthorized automated replies. This logger does not send messages; it acts strictly as a passive listener, which does not trigger WhatsApp's anti-spam algorithms. 21 > * **Standard Linked Device:** The tool connects to WhatsApp using the official Multi-Device WebSocket protocol. To WhatsApp's servers, this connection looks exactly like you logging into standard WhatsApp Web on a secondary browser. 22 > * **No User Reports:** The number one cause of bans is other users reporting an account. Since this logger works silently in the background and does not interact with anyone, there is zero risk of being reported. 23 24 ### Check <a href="https://docs.amit.is-a.dev/whatsapp-logger/">guide</a> for detailed installation process. 25 26 ### Important notes: 27 * It is recommended to download the **web app (PWA)** after the publication of the webpage for better security and native experience. 28 * It is recommended to use **PIN** or **Biometric authentication** inside the web app. Find the authentication options in Settings. 29 30 ## Features 31 32 * **Anti-Delete**: Logs messages instantly, preserving them even if the sender deletes them. 33 * **Privacy First**: You host the backend and database. No third-party servers access your data. 34 * **Secure Access**: Frontend is protected by a password validated against your backend. 35 * **Media Support**: Captures text messages (Images/Media support depends on Baileys implementation, primarily text-focused). 36 * **Search & Filter**: Search by content or filter by date. 37 * **Export**: Export chat logs to `.txt` files. 38 * **Offline Ready**: Uses IndexedDB caching so you can read your logs even without an internet connection. 39 40 --- 41 42 ## Prerequisites 43 44 1. A **GitHub** Account. 45 2. A **Render** Account (Free tier works). 46 3. A **Firebase** Account (Free Spark plan works). 47 4. A **WhatsApp** account on your phone. 48 5. An **UptimeRobot** Account (Free). 49 50 --- 51 52 ## Step 1: Firebase Setup (The Database) 53 54 1. Go to the [Firebase Console](https://console.firebase.google.com/) and create a new project. 55 2. **Create Database**: 56 * Navigate to **Firestore Database** in the sidebar. 57 * Click **Create Database**. 58 * Select a location (e.g., `nam5` or `eur3`). 59 * Start in **Production Mode**. 60 3. **Set Security Rules**: 61 * Go to the **Rules** tab in Firestore. 62 * Replace the rules with the following. As of v4.2.1, the frontend never talks to Firestore directly — only your Render backend does, via the Admin SDK, which bypasses these rules entirely regardless of what they say. So there's no reason to allow any direct client access: 63 ```javascript 64 rules_version = '2'; 65 service cloud.firestore { 66 match /databases/{database}/documents { 67 match /{document=**} { 68 // Deny all direct client access. The Admin SDK (your Render backend) 69 // bypasses these rules entirely, so this only blocks browsers/apps 70 // that try to read or write Firestore directly with a client SDK. 71 allow read, write: if false; 72 } 73 } 74 } 75 ``` 76 4. **Get Backend Credentials (Service Account)**: 77 * Go to **Project Settings** (Gear icon) -> **Service accounts**. 78 * Click **Generate new private key**. 79 * This will download a `.json` file. **Keep this safe.** You will need its content for Render. 80 81 That's everything you need from Firebase — the frontend doesn't need any Firebase configuration at all. 82 83 --- 84 85 ## Step 2: Deploy Backend (The Listener) 86 87 1. **Fork this Repository** to your own GitHub account. 88 2. Log in to [Render](https://render.com/). 89 3. Click **New +** -> **Web Service**. 90 4. Connect your forked repository. 91 5. **Runtime**: Select **Docker**. 92 6. **Environment Variables** (Critical Step): 93 Add the following variables under "Advanced": 94 * `FIREBASE_SERVICE_ACCOUNT`: Paste the **entire content** of the JSON file you downloaded in Step 1. 95 * `AUTH_USER`: Set a username (e.g., `admin`). 96 * `AUTH_PASS`: Set a strong password. This creates the lock for your logger. 97 7. Click **Create Web Service**. 98 8. Wait for the deployment to finish. Render will give you a URL like `https://your-app.onrender.com`. 99 100 ### Excluding specific chats from logging 101 102 If there are chats you don't want logged at all — a bot, a broadcast/status JID, a business account — edit `EXCLUDED_JIDS` in `src/config.js` on your fork before deploying: 103 104 ```javascript 105 // --- CONFIGURATION --- 106 const PORT = process.env.PORT || 3000; 107 const AUTH_USER = process.env.AUTH_USER; 108 const AUTH_PASS = process.env.AUTH_PASS; 109 const MAX_LOGS = 500; 110 const MAX_CONNECTIONS_PER_TOKEN = 15; 111 const VERSION = '4.x.x'; 112 const EXCLUDED_JIDS = new Set(['']); 113 114 module.exports = { 115 PORT, 116 AUTH_USER, 117 AUTH_PASS, 118 MAX_LOGS, 119 MAX_CONNECTIONS_PER_TOKEN, 120 VERSION, 121 EXCLUDED_JIDS 122 }; 123 ``` 124 125 `EXCLUDED_JIDS` is a set of full JIDs (the `...@s.whatsapp.net` / `...@g.us` / `...@lid` identifiers, not just a phone number) that are skipped entirely — they won't be cached, streamed, or included in exports. It ships empty by default. You can find a chat's exact JID from the live server logs (`Settings` -> `System Diagnostics`) the first time it logs a message, then add it here, e.g. `new Set(['917278779512@s.whatsapp.net', '201554426618024@lid'])`, and redeploy. 126 127 --- 128 129 ## Step 3: Connect WhatsApp 130 131 1. Open your Render URL (`https://your-app.onrender.com`) in a browser. 132 2. You will be prompted for a login. Use the `AUTH_USER` and `AUTH_PASS` you set in Render. 133 3. You will see a **QR Code**. 134 4. Open **WhatsApp** on your phone: 135 * iOS: Settings -> Linked Devices 136 * Android: Three dots -> Linked Devices 137 5. Tap **Link a Device** and scan the QR code. 138 6. The page should refresh and say **"System Operational"**. Your backend is now listening! 139 140 --- 141 142 ## Step 4: Setup Frontend (The Viewer) 143 144 1. Download the `index.html` file from this repository. 145 2. Open `index.html` in a text editor (Notepad, VS Code, etc.). 146 3. Locate the Configuration section near the top of the `<script>` block. 147 4. **Fill in the details**: 148 * `RENDER_BACKEND_URL`: Your Render URL (e.g., `https://your-app.onrender.com` - **No trailing slash**). 149 150 **It should look like this before you edit it:** 151 ```javascript 152 const RENDER_BACKEND_URL = ""; 153 ``` 154 155 That's the only setting needed. As of v4.2.1, the frontend authenticates against your Render backend (`/api/verify`) and gets a session token back, used for every chat/message request over Server-Sent Events. Firebase credentials only ever live on the backend, set in Step 2. 156 157 5. **Deploy the Frontend**: 158 * You can host this single file anywhere: 159 * **Firebase Hosting** (Recommended): `firebase init` -> Hosting -> Select `public` directory -> Put `index.html` there -> `firebase deploy`. 160 * **GitHub Pages**: Enable Pages in your repo settings. 161 * **Netlify/Vercel**: Drag and drop the folder containing `index.html`. 162 163 --- 164 165 ## Step 5: Usage 166 167 1. Navigate to your hosted frontend URL. 168 2. You will see a Login Screen. 169 3. Enter the same `AUTH_USER` and `AUTH_PASS` you configured on Render. 170 4. Once unlocked, your chats will load from Firebase. 171 * **Sidebar**: Shows chat list sorted by newest activity. 172 * **Search**: Filter contacts by name or phone number. 173 * **Export**: Download chat history as a `.txt` file. 174 175 --- 176 177 ## Step 6: Keep it Alive (UptimeRobot) 178 179 Render's free tier spins down after inactivity. To keep your logger running 24/7: 180 181 1. Create a free account on [UptimeRobot](https://uptimerobot.com/). 182 2. Click **Add New Monitor**. 183 3. **Monitor Type**: HTTP(s). 184 4. **Friendly Name**: WhatsApp Logger. 185 5. **URL (or IP)**: `https://your-app.onrender.com/ping` (Make sure to add `/ping` at the end). 186 6. **Monitoring Interval**: 5 minutes. 187 7. Click **Create Monitor**. 188 189 --- 190 191 ## Troubleshooting 192 193 * **"No chats found"**: Send a message to the linked WhatsApp account to trigger the first log. 194 * **"Incorrect Credentials"**: Ensure your Render backend is running and you are using the exact Username/Password defined in Render Environment Variables. 195 * **Proof/Phone Numbers**: If a chat shows a long ID (e.g., `1155...@lid`), wait a few minutes. The backend automatically syncs contacts and updates the record with the real phone number. 196 197 ## Disclaimer 198 199 This tool is for personal archiving purposes. Using it to log conversations without consent may violate privacy laws in your jurisdiction. The author is not responsible for misuse.