WATranslate v4.6 — New Message Alerts

PURPOSE
Make new incoming WhatsApp messages difficult for the agent to miss.

ALERT LAYERS

1. IN-APP VISUAL NOTIFICATION
When a new incoming message is detected:
- a notification card appears over WATranslate
- current application icon is shown
- contact/customer name is shown
- translated/latest message preview is shown
- click/tap the notification to open that conversation

Works on:
- desktop/web
- installed mobile/PWA while the app is running

2. SOUND
A short WATranslate notification chime is included.

Default:
ON

Setting:
Menu (...) → Settings → Notification sound

The setting is stored per browser/device.

3. UNREAD BADGE
A green unread counter appears beside the contact name.

The browser/PWA page title also shows the total unread count:
(2) WATranslate

Opening the contact clears that contact's unread counter.

Unread state is stored on the device so it survives a normal reload.

4. BROWSER / SYSTEM NOTIFICATION
Menu (...) → Settings → Enable notifications

The agent must grant browser/device permission.

When permission is granted, WATranslate uses the service worker to show
a browser/system notification when the WATranslate window is not visible
or not focused.

The notification uses:
- current WATranslate app icon
- contact/customer name
- latest translated message preview

Clicking the system notification focuses WATranslate and opens the contact
when an existing app/browser client is available.

5. TEST BUTTON
Menu (...) → Settings → Test notification

This tests:
- in-app notification
- sound
- browser/system notification if permission has been granted

NEW MESSAGE DETECTION
The existing 5-second WATranslate polling interval is retained.

A lightweight API action:
notification_snapshot

checks the latest message ID/direction for all contacts.

Only NEW incoming messages trigger alerts.
Outgoing agent messages and delivery/read status updates do not trigger alerts.

The first time v4.6 runs on a device it establishes a baseline and does NOT
notify the agent about every old message already in the database.

If WATranslate is later reopened, the stored baseline lets it detect a newer
message that arrived since the last stored snapshot.

LOCALIZATION
All new controls/messages are included in:
- English
- Russian
- German
- Spanish

NO SQL / DATABASE MIGRATION REQUIRED.

FILES TO OVERWRITE
public/index.php
public/api.php
assets/app.js
public/assets/app.js
service-worker.js

FILES TO ADD
assets/notifications-v4.6.css
public/assets/notifications-v4.6.css
assets/notification.wav
public/assets/notification.wav

DO NOT CHANGE
root api.php wrapper
public/webhook.php
config.php
database
Google configuration
Meta configuration
branding settings/storage

INSTALL
1. Back up the current WATranslate folder.
2. Upload this ZIP to:
   public_html/whatsapp-server-translator/
3. Extract and overwrite.
4. Desktop: hard refresh.
5. Installed iPhone PWA:
   fully close WATranslate from the app switcher and reopen it.

THEN ENABLE SYSTEM NOTIFICATIONS
Menu (...) → Settings → Enable notifications

Grant the permission requested by the browser/device.

Then press:
Test notification

IMPORTANT LIMITATION
This v4.6 alert system detects messages through the existing WATranslate
5-second polling while the web/PWA application has an active runtime.

Desktop browsers can normally continue to notify while the tab is in the
background.

Mobile operating systems may suspend a PWA after it has been fully closed or
inactive for a period. Instant alerts while the iPhone PWA is fully terminated
require a separate server Web Push implementation triggered directly from the
WhatsApp webhook. That is intentionally NOT added in this patch because it
requires push subscriptions/VAPID/server-side delivery rather than the current
polling architecture.
