# Connect WhatsApp to Al Moasis

Connect a WhatsApp number to your Muassis in under 90 seconds.

## What you need

- A **dedicated WhatsApp number** (DO NOT use your personal number — see warning below)
- A phone with **WhatsApp Business** installed (recommended) OR regular WhatsApp
- The Muassis dashboard open at `http://127.0.0.1:3000/dashboard/`

## ⚠️ Critical: use a dedicated number

WhatsApp's terms allow **one device pairing per phone number**. When Muassis pairs, it appears as a "linked device" on your phone (just like WhatsApp Web does). You can still use WhatsApp on your phone afterward — but:

- Muassis will see every message arriving at that number
- Muassis will reply on your behalf
- Customers will see one inbox; you'll see two (your phone + Muassis dashboard)

**Best practice:** buy a separate SIM (any Saudi telco — STC / Mobily / Zain — supports a Business WhatsApp on a dedicated SIM). Keeps your personal chats separate from agent activity.

## Step 1 — Open the WhatsApp tab

In the dashboard, click the **📱 واتساب** tab.

You'll see a "Generate QR" button. Click it.

Within 5–10 seconds (longer on first run while Baileys loads), an ASCII QR code appears in the dashboard.

> **Why ASCII?** Renders in any browser, prints if needed, no image hosting required. The QR refreshes every 60 seconds — if it expires before you scan, click "Generate" again.

## Step 2 — Scan the QR code

On your phone (the one holding the WhatsApp number you're connecting):

### WhatsApp Business (recommended)
1. Open WhatsApp Business
2. Settings → **Linked Devices** → **Link a Device**
3. (Optional but recommended) Use phone number instead of QR — see "Phone-number pairing" below
4. Point camera at the dashboard QR

### Regular WhatsApp
1. Open WhatsApp
2. Settings → **Linked Devices** → **Link a Device**
3. Point camera at the dashboard QR

The QR turns into a "✅ Connected" indicator. The dashboard pill flips to green within 2 seconds.

## Step 3 — Verify

Send a test message **to** your WhatsApp Business number (not from it) — easiest way is:
- Use the dashboard's web chat (it goes through the same brain)
- Or text from another phone

You should see:
- The message logged in the **Conversations** tab
- Muassis reply within ~2–4 seconds
- The reply visible on **your** phone too (since Muassis is a linked device)

## What works

| Capability | Notes |
|---|---|
| Inbound DMs | ✅ full reply |
| Inbound group messages | ✅ ambient emoji reaction (✅/👀/🤔) — full reply only when mentioned |
| @mentions in groups | ✅ full reply (configurable wake-words: محسسن / @muassis / مساعد) |
| Outbound messages | ✅ via brain reply or `call_api` to WhatsApp Cloud API |
| Photos / images | ⏳ caption read but image processing in v1.2 |
| Voice notes | ⏳ planned |
| Documents (PDF, etc.) | ⏳ planned |
| Stickers / reactions on inbound | ✅ logged, ambient response |
| Multi-account (sales WA + support WA on one Muassis) | ✅ scaffold present, full UI in v1.2 |

## Phone-number pairing (alternative to QR scan)

For Saudi customers on slow networks where the QR doesn't render well:

1. Click the dashboard's "Pair with phone number instead" link (bottom of WhatsApp tab)
2. Enter your number with country code (e.g., `+966501234567`)
3. WhatsApp shows an 8-character code on your phone
4. Type that code into the dashboard
5. Same effect as QR scan

(This UI ships in v1.1.0 — if you don't see the link yet, run `npm i -g @almoasisai/muassis@latest`.)

## What if it doesn't work?

### "ERR_CONNECTION_REFUSED" when scanning
Gateway isn't running, or browser tab is stale. Check:
```bash
muassis status
# expect: ✓ Gateway running at http://127.0.0.1:3000
```
If not, run `muassis start` and wait 5 seconds before clicking Generate again.

### QR shown but scan does nothing
- Phone WhatsApp version too old. Update WhatsApp / WhatsApp Business in the App Store / Play Store.
- Phone clock is wrong (>5 min off). Set to automatic.
- Phone is on different network than the Muassis machine. Both must reach `web.whatsapp.com` — most networks fine.

### "Connection closed" loop in logs
Common causes:
- WhatsApp's anti-spam flagged the pair (unusual). Wait 24h, try with a different SIM.
- Muassis's browser fingerprint matches a flagged pattern. Update to latest Muassis (`npm i -g @almoasisai/muassis@latest`) — we keep the fingerprint current.
- Auth state corrupt. Delete `<dataDir>/whatsapp/<tenantId>/default/` and re-pair.

```bash
# Find dataDir
muassis env path
# Delete (irreversible — re-pair after)
rm -rf ~/Library/Application\ Support/Muassis/whatsapp/<your-tenant-id>/default/
# On Linux:
rm -rf ~/.local/share/muassis/whatsapp/<your-tenant-id>/default/
# On Windows: %APPDATA%\Muassis\whatsapp\<tenant-id>\default\
```

### Messages arrive but bot doesn't reply
Three checks:
1. `muassis status` shows the gateway running? (green)
2. Allowlist gate. Default for unknown senders is `ask` (escalation queue) — check the dashboard's escalations panel for a card waiting on you. To allow everyone:
   ```bash
   # Switch inbound_access to auto:
   muassis privacy show   # not this — privacy is for telemetry
   # Use the API or the Operations tab → Policies → inbound_access → auto
   ```
3. NIM key works:
   ```bash
   muassis env show
   # if no NVIDIA_API_KEY shown, the bundled key is being used (dev/test) — ensure it's decoded
   ```

### Specific WhatsApp account got banned
Two reasons:
- Too many messages in too short a time (look at the rate limiter — `MUASSIS_RATE_LIMIT=0` if you disabled it). Default limits are forgiving for normal traffic.
- Spam-like behavior (sending identical messages to many recipients).

WhatsApp ban appeals: `https://www.whatsapp.com/contact/?subject=messenger`. Time-to-resolution varies.

**Prevention:** never use Muassis to send unsolicited bulk messages. The Acceptable Use Policy (legal/ACCEPTABLE_USE_POLICY.md §3) explicitly forbids spam. WhatsApp's ToS is similar.

## Privacy + the linked-device model

When you scan the QR:
- Your phone's WhatsApp doesn't share the **history** of older chats with Muassis (only future messages from the moment of pairing forward, plus a small history sync window).
- Baileys (the library Muassis uses) is **unofficial**. It speaks WhatsApp's protocol but isn't blessed by Meta. WhatsApp could change protocols at any time and break Muassis. We update Muassis quickly when that happens.
- Meta's official "WhatsApp Cloud API" is the alternative: paid, requires a Facebook Business Manager account, blue verification, etc. If you grow past 10k messages/day or want enterprise SLAs, we'll help you migrate to Cloud API.

## Keep your number alive

Two things break a working pair over time:
1. **Your phone going offline for >2 weeks.** WhatsApp logs out linked devices when the primary phone is unreachable. Just open WhatsApp on the phone once a week.
2. **Updating WhatsApp on your phone to a major version that changes the protocol.** Rare; Muassis updates within 1–2 weeks usually.

## Multi-bot / multi-number

Run two WhatsApp numbers from one Muassis (e.g., sales line + support line)? Yes:
- Per-account directory isolation is built (`<dataDir>/whatsapp/<tenantId>/<accountId>/`)
- Today, accept the default `accountId='default'` for simple installs
- For two numbers: tracked on v1.2 roadmap with a "Connect another number" button in the dashboard

## Removing the connection

To unpair Muassis from your WhatsApp:
1. On your phone: Settings → Linked Devices → tap "Muassis" → **Log out**
2. In Muassis: dashboard → WhatsApp tab → **قطع الاتصال** (Disconnect)
3. Clean local auth: `rm -rf <dataDir>/whatsapp/<tenantId>/default/`

After step 1, Muassis will detect the logout in <30 seconds and stop trying to reconnect (`session.status='logged_out'`).

---

**Stuck?** Email support@taseesai.com with: which step you're on, the dashboard screenshot, the last 20 lines of `muassis status` log. We respond within 24h on weekdays.
