# Browser Extension

## Overview

The WaDesk Companion is a Chrome browser extension that adds a side panel directly inside WhatsApp Web. It lets you send personalised messages to a list of numbers, import contacts from a CSV, browse your saved templates, and review recent sends — all without leaving the WhatsApp Web tab.

You sign in with your WaDesk account, and the panel works inside WhatsApp Web using the same session you scanned on your phone. It's an alternative, browser-side way to send — it does not need a connected device on the server side.

> Caution: Bulk sending from WhatsApp Web carries the same ban risk as any unofficial automation. Use conservative pacing, keep volumes modest, and only message contacts who expect to hear from you. The built-in random-delay control exists for exactly this reason.

## Installing the Extension

The extension ships as a folder (named `extension`) inside your WaDesk download. To install it in Chrome (or any Chromium browser):

1. Open `chrome://extensions` in your address bar.
2. Turn on Developer mode (top-right toggle).
3. Click Load unpacked and select the `extension` folder.
4. Pin the extension so its icon is visible in the toolbar.

> Important: The extension ships pointed at a demo server with demo branding. Before you use or share it, set your own server address (and optionally swap the logo and brand name) — see Customize for Your Install below.

## Customize for Your Install (domain, logo, branding)

The extension lives in the `extension` folder of your WaDesk download. There's nothing to compile — you just open a couple of plain text files, change a value, and click reload on `chrome://extensions`. Three quick edits below.

### 1. Set your server address (required)

Open the file `extension/content.js` in any text editor. Near the very top you'll see a clearly marked CONFIG block. Replace the demo address with your own WaDesk web address:

    // ===================== CONFIG =====================
    // Set your server URL here
    const WADESK_SERVER_URL = 'https://your-domain.com';
    // ===================== END CONFIG =================

Use the same web address you open WaDesk on, with no slash at the end. This is the only place you set it.

> Use a real `https://` address. The demo value only works on one local network. Browsers block insecure (plain `http://`) connections from a secure page like WhatsApp Web, so an `https://` address is required.

### 2. Replace the logo

The whole extension uses a single image file: `extension/assets/images/logo.png`. Replace that one file with your own — the toolbar icon, the toolbar popup, and the side panel all update at once. Use a square PNG with a transparent background, at least 128×128 pixels, and keep the same filename. The popup shows this logo in white, so a solid single-colour mark looks best.

### 3. Rename the extension (white-label)

The shipped name is "WaSnap". To show your own brand, change the name text in two files with a text editor:

What changes | File to edit
--- | ---
The extension name and store description (shown in Chrome and the toolbar tooltip) | `manifest.json`
The popup title and heading | `popup.html`
The name shown in the side panel before sign-in | `content.js`

> Good to know: once a user signs in, the side panel automatically picks up your live brand name and logo from your WaDesk server — so it self-brands. The names you set above are only the placeholders shown before sign-in. The one exception is the extension name in `manifest.json`, which Chrome always shows as-is, so set that one regardless.

After editing, open `chrome://extensions` and click the extension's reload icon to apply everything.

## Opening the Panel

1. Open web.whatsapp.com and make sure WhatsApp Web is logged in.
2. Click the WaDesk Companion toolbar icon and choose Open panel, or use the floating button the extension injects on the page.
3. The WaDesk side panel slides in alongside the WhatsApp Web conversation list.

If the panel does not appear, refresh the WhatsApp Web tab so the content script re-injects.

## Signing In

The panel asks for your WaDesk email and password — the same login you use for the web app. Once you're signed in, the extension stays connected until you sign out.

> Note: Your sign-in is held as a secure access key that lives only inside the extension; the server never stores it in readable form. Clicking Log out revokes that key immediately, so it can't be reused — do this on shared computers.

## Panel Features

The panel has three tabs:

- Send — build a recipient list (type numbers with a country dial-code picker, or import a CSV), compose a message, optionally enable a random delay between sends, and run the send with a live progress counter.
- Recent — your recent send history, with an Export CSV action.
- Templates — a searchable list of your workspace's message templates, so you can drop a template into the composer.

Everything in the panel — your sender numbers, merge fields, templates, send history, and plan usage — comes live from your WaDesk account, so it always matches the web app.

> Note: The sender and template lists match whichever WhatsApp connection your workspace uses. On the Unofficial API you see your connected phones; on the WhatsApp Cloud API or Twilio you see that channel's numbers, and only sendable templates are offered. The extension never mixes connection types.

## Importing Contacts (CSV)

On the Send tab, use the upload button to import a CSV or TXT file. An Import Contacts dialog lets you map the file to numbers:

- Pick the sheet (for multi-sheet files) and the column that holds phone numbers.
- Set the From row and To row range to import a slice of the file.

A Download demo CSV link provides a correctly-formatted starter file. Imported numbers are added to the recipient list, and a counter shows how many are queued. A Filter option lets you narrow the list before sending.

## Sending Messages

1. Confirm the recipient list and choose the sender number.
2. Compose the message text (and attach an image if needed).
3. Optionally enable the random gap toggle and set a min/max delay in seconds between sends.
4. Click Send. A progress indicator shows the count as each message goes out.

Each message is checked, sent through your workspace's WhatsApp connection, and recorded — so it shows up both in the panel's history and in the web app's message history.

> Caution: Always keep the random delay on for any list larger than a handful of numbers. Sending many messages back-to-back from a personal WhatsApp Web session is the fastest way to get a number flagged or banned.

## How sign-in stays secure

After you sign in, the extension uses a private access key — not your WhatsApp Web session and not a saved password — for every action it takes against your WaDesk account. That key is the only credential it holds, so treat it like a password:

- On a shared or public computer, always click Log out when you're done. That instantly revokes the key so no one else can use it.
- The key is stored only inside the extension on your own browser — it is never exposed elsewhere.