WhatsApp Assistant

The WhatsApp assistant is a conduit between the user and their workspace: every message reads from, writes to, or creates data in the CRM. It runs on the AI v2 engine (the same LangGraph stack as the web chat) over WAHA, with the Units agent pinned — same tools, same permissions, same server-enforced write confirmation; only the surface differs (plain text, no charts).

Linking a number

1. In workspace settings, the admin enters their phone number (POST /admin/whatsapp/link). A 4-digit OTP is sent to that WhatsApp number — receiving it proves the number is a real, reachable WhatsApp account.
2. The admin types the code back in the web settings (POST /admin/whatsapp/verify). The number is now linked.
3. One number = one account, everywhere. Uniqueness is enforced among verified links by partial unique indexes (tenant DB + the cross-tenant main-DB registry). Linking a number someone else verified fails with This WhatsApp number is already linked to another account.
4. Offboarding: an admin with the admin.update permission can deregister every number of a teammate — DELETE /admin/whatsapp/admins/:adminSlug. Immediate: the bot stops resolving that phone on the next message.

How a message flows

• Identity: the sender's phone resolves to a verified admin_whatsapp link, then to the admin in that tenant. The AI inherits the admin's exact permissions — every tool re-checks them server-side. Unknown numbers get a human "not linked" reply.
• Isolation: each turn runs inside TenantScope.runInScope pinned to the admin's workspace (RLS on the shared DB). Links created before workspace stamping get a one-time "please re-link your number" reply.
• Confirmation before every write: v2's write gate is enforced by the server, not the prompt. The bot lists what it is about to do and waits for a bare yes / نعم (or no / لا). Any other reply abandons the gate and is treated as a new instruction — the user is never trapped.
• Sessions: conversation context lasts 30 minutes from the last message (sliding). After that the next message starts fresh — "change the priority" three days later gets "which record do you mean?", never a write to the wrong record. CRM data itself is the long-term memory and is never forgotten.
• Language: the assistant answers in the language the user writes (Arabic ↔ English), including the canned replies.
• Failures are never silent: out of AI credits → a billing hint; anything else → "I'm having trouble connecting right now."

What it can do

Everything the Units agent can, in text: read/search records, update fields (auto-computed serial/calculated fields are refused), append comments, create tasks (create_task — creator becomes owner unless they name a teammate, which needs task-edit access), assign tasks (assign_task), toggle task status, and look up teammates (list_admins). Views, table configuration, and file exports are web-only — the bot says so and points to the web app.

Document generation from templates is a future capability; the architecture (channel profiles + auto-discovered tools) admits it without a rebuild.

Operations

Session/gate state lives in Redis under whatsapp-ai:v2:* (conversation window, pending confirm gate, message dedup, per-phone turn lock). Credit usage is billed per turn with channel: 'whatsapp' on the ledger.