# Install the WhatsApp Logger extension in Chrome (manual / unpacked)

This guide explains how to install the extension **without the Chrome Web Store** — by loading the project folder as an **unpacked extension** in Chrome or Chromium.

The extension folder is:

`/var/www/html/WebSite/whatsapploggerextension`

(on your server or a copy on your PC — Chrome needs a local folder path it can read).

---

## Before you start

You will need:

1. **Google Chrome** or **Chromium** (recent version; Manifest V3).
2. The **extension folder** on the same machine where Chrome runs (or a synced copy, e.g. via SSH/SFTP).
3. A working **crmapi** with `WhatsAppLogger.php` reachable from that browser.
4. A valid CRM **API key** (from your `ApiKeys` table / admin setup).

Recommended: confirm the API works before installing the extension, for example:

```bash
curl -s -X POST 'http://localhost/WebSite/crmapi/WhatsAppLogger.php' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{"command":"logmessage","message_id":"install_test_001","receiver_phone":"5491110000000","phone_number":"5491199999999","text":"install test","direction":"incoming","chat_type":"individual"}'
```

You should get JSON with `"status":"done"` (or `"duplicate":true` if you run it twice).

---

## Step 1 — Get the extension files

### Option A — Chrome on the same Linux server (desktop)

If you browse the web on the same machine that hosts the files, use the path directly, for example:

`/var/www/html/WebSite/whatsapploggerextension`

### Option B — Chrome on your PC, code on a server

Copy the whole `whatsapploggerextension` folder to your computer, for example:

`C:\Projects\whatsapploggerextension` (Windows)  
`~/Projects/whatsapploggerextension` (Mac/Linux)

The folder must contain at least:

- `manifest.json`
- `content.js`
- `background.js`
- `popup.html`
- `popup.js`
- `icons/` (icon16.png, icon48.png, icon128.png)

---

## Step 2 — Open Chrome Extensions page

1. Open **Google Chrome**.
2. Go to the extensions management page using **one** of these:
   - Address bar: `chrome://extensions`
   - Menu → **Extensions** → **Manage Extensions**
   - Menu → **Extensions** → **Visit Chrome Web Store** is **not** needed.

---

## Step 3 — Enable Developer mode

1. On the **Extensions** page, find **Developer mode** (usually top-right).
2. Turn **Developer mode** **ON**.

You should see new buttons: **Load unpacked**, **Pack extension**, **Update**.

---

## Step 4 — Load the extension

1. Click **Load unpacked**.
2. In the file picker, select the **`whatsapploggerextension`** folder (the folder that contains `manifest.json`, not its parent).
3. Click **Select Folder** (or **Open**).

If successful:

- **WhatsApp CRM Logger** appears in the extensions list.
- Version **2.0.0** (or current `manifest.json` version).
- The extension icon appears in the toolbar (you may need to pin it — see Step 6).

### If loading fails

| Error | What to do |
|-------|------------|
| “Manifest file is missing or unreadable” | You selected the wrong folder; select the one that contains `manifest.json`. |
| “Could not load icon” | Ensure `icons/icon16.png`, `icon48.png`, `icon128.png` exist. |
| Permission / path errors | Copy the folder to a local disk path Chrome can read. |

---

## Step 5 — Configure the extension

1. Click the **WhatsApp CRM Logger** icon in the toolbar (or open it from `chrome://extensions` → **Details** → **Extension options** if no popup).
2. In the popup, fill in:

   | Field | Required | Example |
   |-------|----------|---------|
   | **WhatsAppLogger.php URL** | Yes | `http://localhost/WebSite/crmapi/WhatsAppLogger.php` |
   | **API Key** | Yes | Your `crm_...` key |
   | **Company receiver phone** | Yes | `5491112345678` (country code, digits only) |
   | **Receiver label** | No | `Sales WhatsApp` |

3. Click **Save**.
4. Ensure **Message logging** toggle is **ON** (green/active).

**Receiver phone** is the WhatsApp number logged into WhatsApp Web on this browser — your company line, not the contact’s number. It is sent on every message so the server knows which company account the message belongs to.

---

## Step 6 — Pin the extension (recommended)

1. Click the **puzzle piece** (Extensions) icon in Chrome’s toolbar.
2. Find **WhatsApp CRM Logger**.
3. Click the **pin** icon so it stays visible.

---

## Step 7 — Test with WhatsApp Web

1. Open a **new tab** and go to **https://web.whatsapp.com**.
2. Scan the QR code if not already linked.
3. Open any **individual chat** (groups are logged but do not create CRM Actions).
4. Send or receive a **text message**.
5. Open the extension **popup** again:
   - **Recent Messages** should show the capture.
   - **Sent** count should increase if the API accepted the POST.

### Verify on the server

- **Logger UI:** open `http://localhost/WebSite/whatsapploggerui/WhatsAppLogger.html`, log in with the same API key, check the message list.
- **Actions UI:** if the contact’s phone exists in CRM, a new WhatsApp action should appear; otherwise the log is stored with action sync skipped.

---

## Step 8 — After code changes (reload extension)

When you edit extension files (`content.js`, `background.js`, etc.):

1. Go to `chrome://extensions`.
2. Find **WhatsApp CRM Logger**.
3. Click the **Reload** (circular arrow) button.

Or click **Update** at the top of the extensions page to reload all unpacked extensions.

**Note:** Reloading the extension clears the in-memory dedup in `content.js`; refresh the WhatsApp Web tab if behavior seems stale.

---

## Step 9 — Remote / production server URL

If crmapi is **not** on `localhost`, set the popup URL to your real host, for example:

`https://your-domain.com/crmapi/WhatsAppLogger.php`

Requirements:

- **HTTPS** is strongly recommended for production (Chrome may restrict mixed content).
- The server must allow POST from the browser (CORS headers are already set in crmapi).
- `manifest.json` includes broad host permissions for `https://*/*`; for a fixed domain you can narrow `host_permissions` later.

---

## Troubleshooting

| Problem | Check |
|---------|--------|
| No messages in popup | Logging toggle ON? WhatsApp tab open? Text messages only (media-only skipped). |
| Popup shows **Failed** | API URL, API key, receiver phone saved? Server reachable from browser? |
| CORS / network error | Open DevTools → Network on WhatsApp tab; look for failed POST to `WhatsAppLogger.php`. |
| Extension not running on WhatsApp | Extension enabled on `chrome://extensions`? Reload extension + refresh WhatsApp tab. |
| “API key not configured” | Save settings in popup after install (storage is empty until first save). |
| Service worker inactive | `chrome://extensions` → WhatsApp CRM Logger → **Service worker** link → check console errors. |

### View extension logs

1. `chrome://extensions` → **WhatsApp CRM Logger** → **Details**.
2. **Inspect views: service worker** → Console (for `background.js` errors).
3. On WhatsApp Web tab: **F12** → Console (for `[WA-CRM]` messages from `content.js`).

---

## Uninstall or disable

- **Disable:** `chrome://extensions` → toggle off.
- **Remove:** `chrome://extensions` → **Remove**.
- Saved settings (`apiKey`, `receiverPhone`, etc.) live in Chrome sync/local storage and are removed with the extension.

---

## Security notes

- The API key is stored in **Chrome sync storage** (if sync is enabled) or local extension storage — treat the key like a password.
- Only install unpacked extensions from sources you trust.
- Each user/browser should use an API key scoped to the correct tenant and user permissions.

---

## Related documentation

- [`SYSTEM_OVERVIEW.md`](SYSTEM_OVERVIEW.md) — how extension, API, Logger UI, and Actions interact
- [`SPEC.md`](SPEC.md) — full product specification and field definitions