levix-bot 2.3.0 → 3.0.0-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "levix-bot",
-  "version": "2.3.0",
+  "version": "3.0.0-beta",
   "description": "A self-hosted personal WhatsApp bot with an AI agent, group moderation and a web control panel.",
   "main": "src/index.js",
   "scripts": {

package/public/dashboard.css

@@ -1825,6 +1825,48 @@ td.wrap {
 .steps li::marker {
   color: var(--blue-bright);
   font-family: var(--mono);
+}
+
+.pair-chooser {
+  margin: 16px 0 8px;
+}
+
+.pair-methods {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px 20px;
+  margin: 8px 0 12px;
+}
+
+.pair-option {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+.pair-phone-wrap {
+  display: grid;
+  gap: 6px;
+  max-width: 360px;
+  margin-bottom: 12px;
+}
+
+.pair-phone-wrap[hidden] {
+  display: none;
+}
+
+.pairing-code {
+  font-family: var(--mono);
+  font-size: 2rem;
+  letter-spacing: 0.18em;
+  font-weight: 700;
+  padding: 18px 24px;
+  border-radius: 14px;
+  background: var(--panel-raised);
+  color: var(--text);
+  border: 1px solid var(--line);
+}
   font-weight: 700;
 }
 

package/public/dashboard.js

@@ -190,7 +190,7 @@
   const SESSION_LABELS = {
     idle: { tone: "off", label: "Not started", tag: "danger", tagText: "Not started" },
     starting: { tone: "warn", label: "Connecting", tag: "warn", tagText: "Connecting" },
-    waiting_for_qr: { tone: "warn", label: "Waiting for scan", tag: "warn", tagText: "Waiting for scan" },
+    waiting_for_qr: { tone: "warn", label: "Waiting to link", tag: "warn", tagText: "Waiting to link" },
     linking: { tone: "warn", label: "Linking", tag: "warn", tagText: "Linking" },
     connected: { tone: "on", label: "Connected", tag: "ok", tagText: "Linked" },
     reconnecting: { tone: "warn", label: "Reconnecting", tag: "warn", tagText: "Reconnecting" },
@@ -284,6 +284,28 @@
   // --- connection ---------------------------------------------------------
 
   let qrRendered = null;
+  let pairingRendered = null;
+
+  function formatPairingCode(code) {
+    const raw = String(code || "").replace(/\s|-/g, "");
+    if (raw.length === 8) return `${raw.slice(0, 4)}-${raw.slice(4)}`;
+    return raw;
+  }
+
+  function preferredPairMethod() {
+    return /Android|iPhone|Mobile/i.test(navigator.userAgent) ? "pairing" : "qr";
+  }
+
+  function selectedPairMethod() {
+    const picked = document.querySelector('input[name="pair-method"]:checked');
+    return picked ? picked.value : preferredPairMethod();
+  }
+
+  function syncPairChooser() {
+    const pairing = selectedPairMethod() === "pairing";
+    const wrap = $("#pair-phone-wrap");
+    if (wrap) wrap.hidden = !pairing;
+  }
 
   function renderQr(text) {
     if (!text || qrRendered === text) return;
@@ -307,6 +329,31 @@
     $("#qr-note").textContent = "Waiting for a QR code…";
   }
 
+  function renderPairingCode(code, phone) {
+    if (!code || pairingRendered === code) return;
+    pairingRendered = code;
+    const el = $("#pairing-code");
+    if (el) el.textContent = formatPairingCode(code);
+    const phoneEl = $("#pairing-phone");
+    if (phoneEl) {
+      phoneEl.textContent = phone ? `For WhatsApp +${phone}` : "";
+    }
+    const note = $("#pairing-note");
+    if (note) {
+      note.textContent = "Link with phone number instead — not the QR camera.";
+    }
+  }
+
+  function clearPairingCode() {
+    pairingRendered = null;
+    const el = $("#pairing-code");
+    if (el) el.textContent = "••••-••••";
+    const phoneEl = $("#pairing-phone");
+    if (phoneEl) phoneEl.textContent = "";
+    const note = $("#pairing-note");
+    if (note) note.textContent = "Waiting for a pairing code…";
+  }
+
   function retryHint(snapshot) {
     if (snapshot.state !== "reconnecting" || !snapshot.nextRetryAt) return "";
     const seconds = Math.max(0, Math.round((snapshot.nextRetryAt - Date.now()) / 1000));
@@ -378,10 +425,21 @@
     // that can only be cleared by unlinking.
     $("#unlink-btn").disabled = !snapshot.canUnlink;
 
-    // The QR frame is only up while a code can actually be scanned.
-    const pairing = snapshot.state === "waiting_for_qr";
-    $("#qr-panel").style.display = pairing ? "block" : "none";
-    if (!pairing) clearQr();
+    const chooser = $("#pair-chooser");
+    if (chooser) chooser.style.display = snapshot.canStart ? "" : "none";
+
+    // Offer QR or pairing code only while a link attempt is actually waiting.
+    const waiting = snapshot.state === "waiting_for_qr";
+    $("#qr-panel").style.display = waiting ? "block" : "none";
+    const showCode = waiting && (snapshot.hasPairingCode || snapshot.pairingMethod === "pairing");
+    const qrBox = $("#qr-box");
+    const pairingBox = $("#pairing-box");
+    if (qrBox) qrBox.hidden = showCode;
+    if (pairingBox) pairingBox.hidden = !showCode;
+    if (!waiting) {
+      clearQr();
+      clearPairingCode();
+    }
   }
 
   VIEWS.connection = {
@@ -390,10 +448,13 @@
     // offer before this tab existed — a reload has to show the real backend
     // state, not an empty frame.
     load: guard(async () => {
-      const { session, qr } = await api("/bot/session");
+      const { session, qr, pairingCode } = await api("/bot/session");
       setStatus(session);
       renderConnection();
-      if (qr && session.state === "waiting_for_qr") renderQr(qr);
+      if (session.state === "waiting_for_qr") {
+        if (pairingCode) renderPairingCode(pairingCode, session.pairingPhone);
+        else if (qr) renderQr(qr);
+      }
     }),
   };
 
@@ -415,7 +476,10 @@
         // request must not leave a dead button behind.
         $("#start-btn").disabled = true;
         try {
-          const { session } = await api("/bot/session/start", { method: "POST" });
+          const method = selectedPairMethod();
+          const body = { method };
+          if (method === "pairing") body.phone = ($("#pair-phone")?.value || "").trim();
+          const { session } = await api("/bot/session/start", { method: "POST", body });
           setStatus(session);
           toast("Session starting…", "ok");
         } finally {
@@ -451,7 +515,7 @@
     $("#unlink-btn").addEventListener(
       "click",
       confirmed(
-        "Unlink this WhatsApp account? The bot stops answering until you start a new session and scan a QR code.",
+        "Unlink this WhatsApp account? The bot stops answering until you start a new session and link again.",
         async () => {
           const { session } = await api("/bot/logout", { method: "POST" });
           setStatus(session);
@@ -1287,6 +1351,16 @@
 
     socket.on("qr_cleared", () => clearQr());
 
+    socket.on("pairing_code", (payload) => {
+      const code = payload && payload.code;
+      if (code) renderPairingCode(code, payload.phone);
+      if (currentView !== "connection") {
+        toast("A pairing code is ready — open Connection to enter it.");
+      }
+    });
+
+    socket.on("pairing_code_cleared", () => clearPairingCode());
+
     // A socket that dropped may have missed transitions while it was away.
     socket.on("connect", () => {
       if (currentView === "connection") VIEWS.connection.load();
@@ -1297,6 +1371,15 @@
   initTheme();
   initRouting();
   initConnectionActions();
+  {
+    const def = preferredPairMethod();
+    const radio = document.querySelector(`input[name="pair-method"][value="${def}"]`);
+    if (radio) radio.checked = true;
+    document.querySelectorAll('input[name="pair-method"]').forEach((el) => {
+      el.addEventListener("change", syncPairChooser);
+    });
+    syncPairChooser();
+  }
   initCommandActions();
   initAiActions();
   initGroupActions();

package/src/bootstrap/panel.js

@@ -88,7 +88,11 @@ export async function bootstrapPanel({ core } = {}) {
  */
 export function resolveBindAddress() {
   const configured = settings.get("bind_address");
-  return configured || "0.0.0.0";
+  if (configured) return configured;
+  // The phone is the host: keep the panel on loopback until a later phase
+  // opens it in a WebView. LAN bind stays an explicit setting.
+  if (process.env.LEVIX_ANDROID === "1") return "127.0.0.1";
+  return "0.0.0.0";
 }
 
 /** The address a person should type, given how this install is reachable. */

package/src/bootstrap/session-startup-policy.js

@@ -1,13 +1,16 @@
 // Decide whether the WhatsApp session should be started during process boot.
 //
 // Baileys writes a `creds` row as soon as auth state is initialized, even before
-// a QR is successfully paired. Only `creds.me.id` proves that this installation
-// was actually linked to a WhatsApp account.
+// a QR is successfully paired. `requestPairingCode` also writes `creds.me.id`
+// before the phone accepts the code. A finished link has `me.id` and is not
+// still `registered: false`.
 export function hasPairedCredentials(rawCreds) {
   if (!rawCreds) return false;
   try {
     const creds = typeof rawCreds === "string" ? JSON.parse(rawCreds) : rawCreds;
-    return Boolean(creds?.me?.id);
+    if (!creds?.me?.id) return false;
+    if (creds.registered === false) return false;
+    return true;
   } catch {
     return false;
   }

package/src/config/baileys.config.js

@@ -22,8 +22,13 @@ export function setRecentMessageGetter(fn) {
   getRecentMessage = fn;
 }
 
-export const getBaileysConfig = (cachedGroupMetadata) => ({
-  browser: Browsers.windows("Desktop"),
+// QR pairing is happy with a Windows desktop companion. Pairing *codes*
+// are not: WhatsApp rejects them unless the companion looks like Chrome.
+export const BAILEYS_BROWSER_QR = Browsers.windows("Desktop");
+export const BAILEYS_BROWSER_PAIRING = Browsers.macOS("Chrome");
+
+export const getBaileysConfig = (cachedGroupMetadata, { pairingCode = false } = {}) => ({
+  browser: pairingCode ? BAILEYS_BROWSER_PAIRING : BAILEYS_BROWSER_QR,
   markOnlineOnConnect: false,
   logger: pino({ level: "silent" }),
   cachedGroupMetadata,

package/src/core/session.js

@@ -78,6 +78,45 @@ function withTimeout(promise, ms) {
   ]);
 }
 
+const ARABIC_INDIC = /[\u0660-\u0669]/g;
+const EASTERN_ARABIC = /[\u06F0-\u06F9]/g;
+
+/** Digits-only international number for Baileys `requestPairingCode`. */
+export function normalizePairingPhone(input) {
+  let value = String(input ?? "");
+  value = value.replace(ARABIC_INDIC, (ch) => String(ch.charCodeAt(0) - 0x0660));
+  value = value.replace(EASTERN_ARABIC, (ch) => String(ch.charCodeAt(0) - 0x06f0));
+  const digits = value.replace(/\D/g, "");
+  if (digits.startsWith("0")) {
+    const error = new Error(
+      "Drop the leading 0 and include the country code (e.g. 2010… not 010…)."
+    );
+    error.code = "PAIRING_PHONE";
+    throw error;
+  }
+  if (digits.length < 8 || digits.length > 15) {
+    const error = new Error(
+      "Enter the WhatsApp number with country code, digits only (e.g. 2010…)."
+    );
+    error.code = "PAIRING_PHONE";
+    throw error;
+  }
+  return digits;
+}
+
+/** How this start should pair, if the install is not linked yet. */
+export function parseStartOptions({ method, phone } = {}) {
+  if (method == null || method === "" || method === "qr") {
+    return { method: "qr", phone: null };
+  }
+  if (method === "pairing") {
+    return { method: "pairing", phone: normalizePairingPhone(phone) };
+  }
+  const error = new Error("Choose QR code or pairing code.");
+  error.code = "PAIRING_PHONE";
+  throw error;
+}
+
 export const SESSION_STATES = Object.freeze({
   IDLE: "idle",
   STARTING: "starting",
@@ -150,6 +189,9 @@ export class WhatsAppSession {
   #proxyConfig = null;
 
   #qr = null;
+  #pairingCode = null;
+  #pairingIntent = { method: "qr", phone: null };
+  #pairingCodeRequest = null;
   #reason = null;
   #detail = null;
   #lastDisconnect = null;
@@ -173,6 +215,7 @@ export class WhatsAppSession {
     emit = () => {},
     retryDelaysMs = RETRY_SCHEDULE_MS,
     log = logger,
+    pairingCodeDelayMs = 1500,
   } = {}) {
     this.createSocket = createSocket;
     this.attachListeners = attachListeners;
@@ -185,6 +228,7 @@ export class WhatsAppSession {
     this.clearCredentials = clearCredentials;
     this.retryDelaysMs = retryDelaysMs;
     this.log = log;
+    this.pairingCodeDelayMs = pairingCodeDelayMs;
   }
 
   // -------------------------------------------------------------------------
@@ -212,6 +256,13 @@ export class WhatsAppSession {
     return this.#qr;
   }
 
+  /**
+   * The 8-character pairing code, or null. Same rule as `qr`: not in getState().
+   */
+  get pairingCode() {
+    return this.#pairingCode;
+  }
+
   /** Everything the dashboard needs to render the Connection screen. */
   getState() {
     const terminal =
@@ -241,6 +292,10 @@ export class WhatsAppSession {
       connected: this.#state === S.CONNECTED,
       terminal,
       hasQr: !!this.#qr,
+      hasPairingCode: !!this.#pairingCode,
+      pairingMethod: this.#pairingIntent?.method || "qr",
+      pairingPhone:
+        this.#pairingIntent?.method === "pairing" ? this.#pairingIntent.phone : null,
       reason: this.#reason,
       detail: this.#detail,
       lastDisconnect: this.#lastDisconnect,
@@ -258,7 +313,7 @@ export class WhatsAppSession {
    * Bring the session up. Idempotent: if a socket exists or is being made, this
    * returns the state it is already in and creates nothing.
    */
-  async start({ reason = "manual" } = {}) {
+  async start({ reason = "manual", method, phone } = {}) {
     if (this.#shuttingDown) return this.getState();
 
     if (this.#starting) {
@@ -267,6 +322,8 @@ export class WhatsAppSession {
     }
     if (BUSY_STATES.has(this.#state)) return this.getState();
 
+    this.#pairingIntent = parseStartOptions({ method, phone });
+
     // A manual start clears whatever the last failure left behind.
     this.#cancelRetry();
     this.#attempt = 0;
@@ -433,7 +490,10 @@ export class WhatsAppSession {
 
     let created;
     try {
-      created = await this.createSocket({ proxy });
+      created = await this.createSocket({
+        proxy,
+        pairingCode: this.#pairingIntent.method === "pairing",
+      });
     } catch (error) {
       this.log.error({ err: error }, "[Session] failed to create the WhatsApp socket");
       this.#transition(S.ERROR, {
@@ -473,9 +533,15 @@ export class WhatsAppSession {
         this.#onHandshakeRejected(generation, sock, response),
     });
 
+    const waitingForCode =
+      this.#pairing && this.#pairingIntent.method === "pairing";
     this.#transition(this.#pairing ? S.WAITING_FOR_QR : S.STARTING, {
       reason,
-      detail: this.#pairing ? "Waiting for a QR code" : "Connecting to WhatsApp",
+      detail: this.#pairing
+        ? waitingForCode
+          ? "Waiting for a pairing code…"
+          : "Waiting for a QR code"
+        : "Connecting to WhatsApp",
     });
 
     this.log.info("[Session] WhatsApp socket created");
@@ -580,7 +646,7 @@ export class WhatsAppSession {
 
     const { connection, lastDisconnect, qr, isNewLogin } = update || {};
 
-    if (qr) this.#onQr(qr);
+    if (qr) await this.#onQr(qr);
 
     // The phone scanned the code. Pairing succeeded even though the connection
     // is about to be torn down and restarted — this is WhatsApp's own login
@@ -598,7 +664,18 @@ export class WhatsAppSession {
     else if (connection === "close") await this.#onClose(lastDisconnect);
   }
 
-  #onQr(qr) {
+  async #onQr(qr) {
+    // Pair-device readiness. In pairing-code mode the QR must not be shown;
+    // requestPairingCode waits for this stanza (or queues until it arrives).
+    if (
+      this.#pairing &&
+      this.#pairingIntent.method === "pairing" &&
+      this.#pairingIntent.phone
+    ) {
+      await this.#requestPairingCode();
+      return;
+    }
+
     this.#qr = qr;
     try {
       saveQrCode(qr);
@@ -612,6 +689,56 @@ export class WhatsAppSession {
     this.emitEvent("qr", qr);
   }
 
+  async #requestPairingCode() {
+    if (this.#pairingCode || this.#pairingCodeRequest) return;
+    const sock = this.#socket;
+    const phone = this.#pairingIntent.phone;
+    if (!phone) return;
+    if (typeof sock?.requestPairingCode !== "function") {
+      this.log.error("[Session] this socket cannot request a pairing code");
+      this.#transition(S.ERROR, {
+        reason: "pairing_unsupported",
+        detail: "Pairing code is not available on this connection. Use QR instead.",
+      });
+      return;
+    }
+
+    this.#pairingCodeRequest = (async () => {
+      try {
+        if (this.pairingCodeDelayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, this.pairingCodeDelayMs));
+        }
+        if (!this.#pairing || this.#shuttingDown) return;
+        const raw = await sock.requestPairingCode(phone);
+        if (!this.#pairing || this.#shuttingDown) return;
+        this.#pairingCode = String(raw || "").replace(/\s|-/g, "");
+        this.#transition(S.WAITING_FOR_QR, {
+          reason: "pairing_code",
+          detail:
+            "Enter the code in WhatsApp → Linked devices → Link with phone number.",
+        });
+        this.emitEvent("pairing_code", {
+          code: this.#pairingCode,
+          phone,
+        });
+      } catch (error) {
+        this.log.error(
+          { err: error?.message },
+          "[Session] pairing code request failed"
+        );
+        if (!this.#pairing || this.#shuttingDown) return;
+        this.#transition(S.ERROR, {
+          reason: "pairing_failed",
+          detail: "Could not get a pairing code. Check the number and try again.",
+        });
+      } finally {
+        this.#pairingCodeRequest = null;
+      }
+    })();
+
+    await this.#pairingCodeRequest;
+  }
+
   async #onOpen() {
     this.#attempt = 0;
     this.#nextRetryAt = null;
@@ -797,14 +924,17 @@ export class WhatsAppSession {
    * GET /qr would happily serve it to somebody.
    */
   #clearQr() {
-    const had = this.#qr !== null;
+    const hadQr = this.#qr !== null;
+    const hadCode = this.#pairingCode !== null;
     this.#qr = null;
+    this.#pairingCode = null;
     try {
       deleteQrCode();
     } catch (error) {
       this.log.debug({ err: error?.message }, "[Session] failed to delete the stored QR");
     }
-    if (had) this.emitEvent("qr_cleared", {});
+    if (hadQr) this.emitEvent("qr_cleared", {});
+    if (hadCode) this.emitEvent("pairing_code_cleared", {});
   }
 
   #transition(state, { reason = null, detail = null } = {}) {

package/src/core/socket.js

@@ -54,7 +54,7 @@ function withThumbnailSupport(sock) {
  *   rather than read here, so this factory stays a pure function of its
  *   arguments and a test can hand it a fake.
  */
-export async function createWhatsAppSocket({ proxy = null } = {}) {
+export async function createWhatsAppSocket({ proxy = null, pairingCode = false } = {}) {
   logger.info(
     proxy
       ? `[Socket] Initializing WhatsApp socket through ${proxy.label}`
@@ -64,16 +64,15 @@ export async function createWhatsAppSocket({ proxy = null } = {}) {
   const { state, saveCreds, clearAll } = await useDatabaseAuthState();
 
   // Whether this install is already paired. NOT `store.hasCredentials()`: the
-  // auth state writes a `creds` row on its very first call, paired or not, so
-  // that row proves nothing. `creds.me.id` is only filled in by a successful
-  // pairing, which is exactly the question the session manager is asking —
-  // it decides whether a close is a failed pairing attempt or a dropped
-  // connection worth retrying.
-  const isPaired = !!state?.creds?.me?.id;
+  // auth state writes a `creds` row on its very first call, paired or not.
+  // `requestPairingCode` also writes `creds.me.id` *before* the phone accepts
+  // the code, so `me.id` alone is not proof. `registered === false` means the
+  // handshake never finished.
+  const isPaired = !!state?.creds?.me?.id && state?.creds?.registered !== false;
 
   const cachedGroupMetadata = (jid) => groupMetadataCache.get(jid);
 
-  const config = getBaileysConfig(cachedGroupMetadata);
+  const config = getBaileysConfig(cachedGroupMetadata, { pairingCode });
 
   // Three separate hooks, because Baileys has three separate network paths:
   //   agent              -> the `ws` WebSocket        (https.request, classic agent)

package/src/index.js

@@ -185,6 +185,10 @@ async function startWithPanel({ open }) {
   // the Connection screen offers a Start button.
   const core = await bootstrapCore({ autoStart: false });
   liveSession = core.session;
+  if (process.env.LEVIX_ANDROID === "1") {
+    console.log("Database ready");
+    console.log("Commands loaded " + core.commandCount);
+  }
 
   let panel;
   try {
@@ -202,6 +206,10 @@ async function startWithPanel({ open }) {
   const url = panelUrl({ port: panel.port, firstRun });
 
   logger.info(`✅ Control panel: ${url}`);
+  if (process.env.LEVIX_ANDROID === "1") {
+    console.log("Panel listening " + url);
+    console.log("Levix ready");
+  }
 
   line();
   line(`  ${brand.name} is running`);

package/src/routes/dashboard.api.esm.js

@@ -850,7 +850,12 @@ router.post("/security/password", (req, res) => {
 // pairing was already waiting showed an empty frame until Baileys happened to
 // issue the next one.
 router.get("/bot/session", (req, res) => {
-  res.json({ success: true, session: sessionState(), qr: session?.qr ?? null });
+  res.json({
+    success: true,
+    session: sessionState(),
+    qr: session?.qr ?? null,
+    pairingCode: session?.pairingCode ?? null,
+  });
 });
 
 // Idempotent by construction: the manager returns the state it is already in
@@ -862,7 +867,17 @@ router.post(
     if (!session) {
       return res.status(503).json({ success: false, error: "Session manager is not ready" });
     }
-    const state = await session.start({ reason: "dashboard" });
+    let state;
+    try {
+      state = await session.start({
+        reason: "dashboard",
+        method: req.body?.method,
+        phone: req.body?.phone,
+      });
+    } catch (error) {
+      if (error.code === "PAIRING_PHONE") return badRequest(res, error.message);
+      throw error;
+    }
     logger.info(`[Dashboard] Start session requested — now ${state.state}`);
     res.json({ success: true, session: state });
   })

package/src/utils/logger.cjs

@@ -19,6 +19,12 @@ function isPackaged() {
   }
 }
 
+// Worker-thread transports load targets by module path. That fails inside a
+// SEA, and Android's Bionic Node is happier with in-process streams too.
+function useInProcessLogs() {
+  return isPackaged() || process.env.LEVIX_ANDROID === "1";
+}
+
 const base = {
   level: "trace",
   serializers: {
@@ -38,7 +44,7 @@ const PRETTY = {
 const combined = path.join(logDir, "combined.log");
 const errors = path.join(logDir, "error.log");
 
-const logger = isPackaged()
+const logger = useInProcessLogs()
   ? pino(
       base,
       pino.multistream([

package/views/dashboard.ejs

@@ -319,6 +319,31 @@
 
               <div class="hint" id="conn-proxy"></div>
 
+              <div id="pair-chooser" class="pair-chooser">
+                <p class="hint">How should this phone link?</p>
+                <div class="pair-methods">
+                  <label class="pair-option">
+                    <input type="radio" name="pair-method" value="qr" />
+                    QR code
+                  </label>
+                  <label class="pair-option">
+                    <input type="radio" name="pair-method" value="pairing" />
+                    Pairing code
+                  </label>
+                </div>
+                <div id="pair-phone-wrap" class="pair-phone-wrap" hidden>
+                  <label for="pair-phone">WhatsApp number with country code</label>
+                  <input
+                    id="pair-phone"
+                    type="tel"
+                    inputmode="numeric"
+                    autocomplete="tel"
+                    placeholder="2010…"
+                  />
+                  <p class="hint">This WhatsApp’s own number. Country code, no leading 0 (Egypt: 2010… not 010…).</p>
+                </div>
+              </div>
+
               <div class="inline action-cluster">
                 <button class="btn btn-primary" id="start-btn" type="button">
                   Start session
@@ -347,15 +372,25 @@
               </div>
 
               <div id="qr-panel" style="display: none">
-                <div class="qr-box">
+                <div class="qr-box" id="qr-box">
                   <div class="qr-frame" id="qr-frame"></div>
                   <div class="hint" id="qr-note">Waiting for a QR code…</div>
-                  <ol class="steps">
+                  <ol class="steps" id="qr-steps">
                     <li>Open WhatsApp on the phone the bot should use.</li>
                     <li>Settings → Linked devices → Link a device.</li>
                     <li>Point the camera at the code above.</li>
                   </ol>
                 </div>
+                <div class="qr-box" id="pairing-box" hidden>
+                  <div class="pairing-code" id="pairing-code">••••-••••</div>
+                  <div class="hint" id="pairing-phone"></div>
+                  <div class="hint" id="pairing-note">Waiting for a pairing code…</div>
+                  <ol class="steps">
+                    <li>Open WhatsApp on that number → Settings → Linked devices.</li>
+                    <li>Link a device → Link with phone number instead.</li>
+                    <li>Type the code above. Get a new code if it fails.</li>
+                  </ol>
+                </div>
               </div>
             </div>
           </section>