npm - @rubytech/taskmaster - Versions diffs - 1.29.1 → 1.30.0 - Mend

@rubytech/taskmaster 1.29.1 → 1.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/dist/agents/tools/cron-tool.js +10 -3
package/dist/build-info.json +3 -3
package/dist/control-ui/assets/{index-B_QfEVs7.js → index-CkGA_2Sq.js} +543 -469
package/dist/control-ui/assets/index-CkGA_2Sq.js.map +1 -0
package/dist/control-ui/assets/{index-CAE6wsJy.css → index-CxVLKv6r.css} +1 -1
package/dist/control-ui/index.html +2 -2
package/dist/cron/normalize.js +8 -4
package/dist/cron/parse.js +48 -7
package/dist/cron/service/jobs.js +4 -1
package/dist/cron/service/ops.js +16 -0
package/dist/gateway/server-methods/whatsapp-conversations.js +41 -7
package/dist/web/auto-reply/monitor/group-activation.js +1 -1
package/dist/web/inbound/monitor.js +34 -3
package/package.json +1 -1
package/skills/event-management/references/events.md +16 -6
package/skills/whatsapp-business/SKILL.md +47 -0
package/skills/whatsapp-business/references/setup-guide.md +258 -0
package/dist/control-ui/assets/index-B_QfEVs7.js.map +0 -1

package/dist/control-ui/index.html CHANGED Viewed

@@ -6,8 +6,8 @@
     <title>Taskmaster Control</title>
     <meta name="color-scheme" content="dark light" />
     <link rel="icon" type="image/png" href="./favicon.png" />
-    <script type="module" crossorigin src="./assets/index-B_QfEVs7.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-CAE6wsJy.css">
+    <script type="module" crossorigin src="./assets/index-CkGA_2Sq.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-CxVLKv6r.css">
   </head>
   <body>
     <taskmaster-app></taskmaster-app>

package/dist/cron/normalize.js CHANGED Viewed

@@ -7,15 +7,19 @@ const DEFAULT_OPTIONS = {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function coerceSchedule(schedule) {
+function coerceSchedule(schedule, opts) {
     const next = { ...schedule };
     const kind = typeof schedule.kind === "string" ? schedule.kind : undefined;
     const atMsRaw = schedule.atMs;
     const atRaw = schedule.at;
+    // When the agent passes a timezone-naive ISO string (e.g. "2026-03-11T09:00:00"),
+    // interpret it in the user's configured timezone — not UTC.  A schedule-level
+    // `tz` field takes priority over the account default.
+    const tz = (typeof schedule.tz === "string" ? schedule.tz.trim() : undefined) || opts?.userTimezone;
     const parsedAtMs = typeof atMsRaw === "string"
-        ? parseAbsoluteTimeMs(atMsRaw)
+        ? parseAbsoluteTimeMs(atMsRaw, tz)
         : typeof atRaw === "string"
-            ? parseAbsoluteTimeMs(atRaw)
+            ? parseAbsoluteTimeMs(atRaw, tz)
             : null;
     if (!kind) {
         if (typeof schedule.atMs === "number" ||
@@ -92,7 +96,7 @@ export function normalizeCronJobInput(raw, options = DEFAULT_OPTIONS) {
         }
     }
     if (isRecord(base.schedule)) {
-        next.schedule = coerceSchedule(base.schedule);
+        next.schedule = coerceSchedule(base.schedule, { userTimezone: options.userTimezone });
     }
     if (isRecord(base.payload)) {
         next.payload = coercePayload(base.payload);

package/dist/cron/parse.js CHANGED Viewed

@@ -1,16 +1,57 @@
 const ISO_TZ_RE = /(Z|[+-]\d{2}:?\d{2})$/i;
 const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const ISO_DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T/;
-function normalizeUtcIso(raw) {
+/**
+ * Resolve the UTC offset string (e.g. "+01:00") for a given IANA timezone at
+ * a specific instant.  Returns undefined if the timezone is invalid.
+ */
+function offsetForTimezone(tz, date) {
+    try {
+        // Format in en-US with timeZoneName to extract the UTC offset.
+        const parts = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            timeZoneName: "longOffset",
+        }).formatToParts(date);
+        const tzPart = parts.find((p) => p.type === "timeZoneName")?.value ?? "";
+        // Intl returns "GMT" for UTC, "GMT+1:00", "GMT-5:00", etc.
+        if (tzPart === "GMT")
+            return "+00:00";
+        const match = tzPart.match(/GMT([+-]\d{1,2}):?(\d{2})?/);
+        if (!match)
+            return undefined;
+        const hours = match[1].padStart(3, match[1][0] === "-" ? "-" : "+");
+        const minutes = match[2] ?? "00";
+        return `${hours}:${minutes}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeIso(raw, tz) {
     if (ISO_TZ_RE.test(raw))
         return raw;
-    if (ISO_DATE_RE.test(raw))
-        return `${raw}T00:00:00Z`;
-    if (ISO_DATE_TIME_RE.test(raw))
-        return `${raw}Z`;
+    if (ISO_DATE_RE.test(raw)) {
+        const suffix = tz ? resolveOffsetSuffix(`${raw}T00:00:00`, tz) : "Z";
+        return `${raw}T00:00:00${suffix}`;
+    }
+    if (ISO_DATE_TIME_RE.test(raw)) {
+        const suffix = tz ? resolveOffsetSuffix(raw, tz) : "Z";
+        return `${raw}${suffix}`;
+    }
     return raw;
 }
-export function parseAbsoluteTimeMs(input) {
+/**
+ * Compute the UTC offset suffix for a timezone-naive ISO string interpreted in
+ * the given IANA timezone.  We do a two-pass approach: first parse as UTC to
+ * get a rough Date, then look up the real offset for that instant.
+ */
+function resolveOffsetSuffix(naiveIso, tz) {
+    const rough = new Date(`${naiveIso}Z`);
+    if (Number.isNaN(rough.getTime()))
+        return "Z";
+    return offsetForTimezone(tz, rough) ?? "Z";
+}
+export function parseAbsoluteTimeMs(input, tz) {
     const raw = input.trim();
     if (!raw)
         return null;
@@ -19,6 +60,6 @@ export function parseAbsoluteTimeMs(input) {
         if (Number.isFinite(n) && n > 0)
             return Math.floor(n);
     }
-    const parsed = Date.parse(normalizeUtcIso(raw));
+    const parsed = Date.parse(normalizeIso(raw, tz));
     return Number.isFinite(parsed) ? parsed : null;
 }

package/dist/cron/service/jobs.js CHANGED Viewed

@@ -23,7 +23,10 @@ export function computeJobNextRunAtMs(job, nowMs) {
         // One-shot jobs stay due until they successfully finish.
         if (job.state.lastStatus === "ok" && job.state.lastRunAtMs)
             return undefined;
-        return job.schedule.atMs;
+        // Guard: if atMs is in the past, treat as expired — never fire immediately.
+        // A past atMs typically means the agent computed the timestamp incorrectly
+        // (e.g. timezone-naive ISO string interpreted as UTC).
+        return job.schedule.atMs > nowMs ? job.schedule.atMs : undefined;
     }
     // For "every" schedules without an explicit anchor, use the job's creation
     // time so the schedule stays grid-aligned across daemon restarts.  Without

package/dist/cron/service/ops.js CHANGED Viewed

@@ -65,6 +65,22 @@ export async function add(state, input) {
         warnIfDisabled(state, "add");
         await ensureLoaded(state);
         const job = createJob(state, input);
+        // If a one-shot "at" job resolved to no nextRunAtMs, the atMs was in the
+        // past.  Reject it outright so the agent gets a clear error instead of a
+        // silently disabled job that never fires.
+        if (job.schedule.kind === "at" &&
+            job.enabled &&
+            job.state.nextRunAtMs == null &&
+            !job.state.lastRunAtMs) {
+            const nowMs = state.deps.nowMs();
+            const delta = nowMs - job.schedule.atMs;
+            const nowIso = new Date(nowMs).toISOString();
+            const atIso = new Date(job.schedule.atMs).toISOString();
+            state.deps.log.warn({ atMs: job.schedule.atMs, atIso, nowIso, deltaMs: delta }, "cron.add rejected: atMs is in the past — reminder would fire immediately");
+            throw new Error(`schedule.atMs resolved to ${atIso} which is ${Math.round(delta / 1000)}s in the past ` +
+                `(current time: ${nowIso}). The reminder would fire immediately. ` +
+                "Call current_time to confirm the current date and year, then retry with a future timestamp.");
+        }
         state.store?.jobs.push(job);
         await persist(state);
         armTimer(state);

package/dist/gateway/server-methods/whatsapp-conversations.js CHANGED Viewed

@@ -4,7 +4,7 @@ import { updateSessionStore } from "../../config/sessions.js";
 import { listRecords } from "../../records/records-manager.js";
 import { normalizeAccountId } from "../../routing/session-key.js";
 import { parseAgentSessionKey } from "../../sessions/session-key-utils.js";
-import { requireActiveWebListener } from "../../web/active-listener.js";
+import { getActiveWebListener, requireActiveWebListener } from "../../web/active-listener.js";
 import { stripEnvelope } from "../chat-sanitize.js";
 import { ErrorCodes, errorShape, formatValidationErrors, validateWhatsAppConversationsParams, validateWhatsAppGroupInfoParams, validateWhatsAppMessagesParams, validateWhatsAppSendMessageParams, validateWhatsAppSetActivationParams, } from "../protocol/index.js";
 import { loadCombinedSessionStoreForGateway, parseGroupKey } from "../session-utils.js";
@@ -239,9 +239,9 @@ export const whatsappConversationsHandlers = {
                 respond(true, { messages: [] });
                 return;
             }
-            // Read transcript and transform to WhatsApp message format
+            // --- Session transcript messages (agent-processed only) ---
             const rawMessages = readSessionMessages(matchedSessionId, storePath, matchedSessionFile);
-            const messages = [];
+            const transcriptMessages = [];
             for (const raw of rawMessages) {
                 const msg = raw;
                 if (!msg.role || (msg.role !== "user" && msg.role !== "assistant"))
@@ -263,8 +263,8 @@ export const whatsappConversationsHandlers = {
                 }
                 if (!text.trim())
                     continue;
-                messages.push({
-                    id: `${matchedSessionId}-${messages.length}`,
+                transcriptMessages.push({
+                    id: `transcript-${matchedSessionId}-${transcriptMessages.length}`,
                     sender,
                     senderName,
                     body: text,
@@ -272,8 +272,42 @@ export const whatsappConversationsHandlers = {
                     fromMe,
                 });
             }
-            // Return the most recent N messages
-            const limited = messages.slice(-limit);
+            // --- Baileys in-memory store (all messages seen since gateway started) ---
+            const listener = getActiveWebListener(accountId);
+            const baileysMessages = listener?.getMessages
+                ? await listener.getMessages(jid, limit * 4)
+                : [];
+            // Merge: use Baileys as the primary source for inbound messages.
+            // Keep transcript assistant (fromMe) messages that Baileys doesn't have,
+            // and deduplicate inbound messages that appear in both sources.
+            let merged;
+            if (baileysMessages.length > 0) {
+                // Build a dedup set from Baileys entries: timestamp (±5s window) + body prefix
+                const baileysSignatures = new Set();
+                for (const m of baileysMessages) {
+                    // Use 5-second timestamp buckets so minor clock drift doesn't cause duplicates
+                    const bucket = Math.floor(m.timestamp / 5);
+                    baileysSignatures.add(`${bucket}:${m.body.slice(0, 60)}`);
+                }
+                // From transcript, keep only assistant messages not already in Baileys
+                const transcriptOnly = transcriptMessages.filter((m) => {
+                    if (!m.fromMe) {
+                        const bucket = Math.floor(m.timestamp / 5);
+                        return !baileysSignatures.has(`${bucket}:${m.body.slice(0, 60)}`);
+                    }
+                    // Always include assistant messages — Baileys store has no agent responses
+                    return true;
+                });
+                merged = [...baileysMessages, ...transcriptOnly];
+            }
+            else {
+                // Baileys store is empty (gateway just started or account not connected) —
+                // fall back to session transcript only.
+                merged = transcriptMessages;
+            }
+            // Sort by timestamp, then return the most recent N
+            merged.sort((a, b) => a.timestamp - b.timestamp);
+            const limited = merged.slice(-limit);
             respond(true, { messages: limited });
         }
         catch (err) {

package/dist/web/auto-reply/monitor/group-activation.js CHANGED Viewed

@@ -35,5 +35,5 @@ export function resolveGroupActivationFor(params) {
         channel: "whatsapp",
         groupId: groupId ?? params.conversationId,
     });
-    return configActivation ?? "mention";
+    return configActivation ?? "off";
 }

package/dist/web/inbound/monitor.js CHANGED Viewed

@@ -88,6 +88,18 @@ export async function monitorWebInbox(options) {
             inboundConsoleLog.error(`Failed handling inbound web message: ${String(err)}`);
         },
     });
+    // In-memory message store: captures all inbound messages per JID (including
+    // history catch-up / append type) so the UI can show a complete conversation view.
+    const messageStore = new Map();
+    const MESSAGE_STORE_MAX = 500; // max entries per JID
+    const storeMessageEntry = (jid, entry) => {
+        const entries = messageStore.get(jid) ?? [];
+        entries.push(entry);
+        if (entries.length > MESSAGE_STORE_MAX) {
+            entries.splice(0, entries.length - MESSAGE_STORE_MAX);
+        }
+        messageStore.set(jid, entries);
+    };
     const groupMetaCache = new Map();
     const GROUP_META_TTL_MS = 5 * 60 * 1000; // 5 minutes
     const lidLookup = sock.signalRepository?.lidMapping;
@@ -177,6 +189,25 @@ export async function monitorWebInbox(options) {
             const messageTimestampMs = msg.messageTimestamp
                 ? Number(msg.messageTimestamp) * 1000
                 : undefined;
+            // Store in the in-memory conversation store so the UI sees all messages,
+            // including history catch-up (append type) and messages from participants
+            // that don't trigger the agent. Runs before access control.
+            const storeBody = extractText(msg.message ?? undefined);
+            if (storeBody) {
+                const fromMe = Boolean(msg.key?.fromMe);
+                const replyCtx = describeReplyContext(msg.message);
+                storeMessageEntry(remoteJid, {
+                    id: id ?? `${remoteJid}-${messageTimestampMs ?? 0}`,
+                    sender: senderE164 ?? participantJid ?? (fromMe ? (selfE164 ?? "") : ""),
+                    senderName: msg.pushName ?? undefined,
+                    body: storeBody,
+                    timestamp: messageTimestampMs ? Math.floor(messageTimestampMs / 1000) : 0,
+                    fromMe,
+                    quoted: replyCtx
+                        ? { id: replyCtx.id ?? "", body: replyCtx.body, sender: replyCtx.sender }
+                        : undefined,
+                });
+            }
             const access = await checkInboundAccessControl({
                 accountId: options.accountId,
                 from,
@@ -414,9 +445,9 @@ export async function monitorWebInbox(options) {
             }
             return entries;
         },
-        getMessages: async (_jid, _limit) => {
-            // No in-memory message store — Baileys makeInMemoryStore is not used.
-            return [];
+        getMessages: async (jid, limit) => {
+            const entries = messageStore.get(jid) ?? [];
+            return limit ? entries.slice(-limit) : entries;
         },
         getGroupMetadata: async (jid) => {
             const meta = await sock.groupMetadata(jid);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"

package/skills/event-management/references/events.md CHANGED Viewed

@@ -105,14 +105,24 @@ The reminder's payload text should reference the event clearly so the recipient
 ### Computing the cron timestamp safely
-The `cron` tool takes `atMs` — a Unix timestamp in **milliseconds**. Errors here cause the job to fire immediately (if the time is in the past) with no warning.
+The `cron` tool accepts `atMs` as either a numeric Unix timestamp in milliseconds or an **ISO 8601 datetime string**. The ISO string approach is strongly preferred because it avoids epoch arithmetic errors.
-**Always call `current_time` before scheduling a cron job.** Use the returned `unix` value (seconds since epoch) as your anchor:
+**Always call `current_time` before scheduling a cron job** to confirm the current date and year.
-1. Get `unix` from `current_time` — this is the current time in seconds.
-2. Calculate how many seconds until the reminder should fire (days × 86400 + hours × 3600 + minutes × 60).
-3. Add to `unix`, then multiply by 1000 to get `atMs`.
-4. Before submitting: verify your computed `atMs` is strictly greater than `unix × 1000`. If it is not, the job will fire immediately — recalculate.
+**Preferred approach — ISO string:**
+1. Call `current_time` to confirm today's date and year.
+2. Pass `atMs` as an ISO 8601 string: `"2026-03-11T09:00:00"` (no timezone suffix needed — the system uses the user's configured timezone automatically).
+3. Double-check that the year in your string matches the year from `current_time`.
+The system rejects timestamps that resolve to the past — you will get a clear error with the current time if this happens.
+**Fallback approach — numeric timestamp:**
+1. Get `unix` from `current_time`.
+2. Calculate offset in seconds (days × 86400 + hours × 3600 + minutes × 60).
+3. Compute: `atMs = (unix + offset) × 1000`.
+4. Verify `atMs > unix × 1000` before submitting.
 Never compute a Unix timestamp from a fixed epoch date (e.g. "January 1, 2026 = X"). Epoch arithmetic done from scratch is the most common source of year-off errors.

package/skills/whatsapp-business/SKILL.md ADDED Viewed

@@ -0,0 +1,47 @@
+---
+name: whatsapp-business
+description: WhatsApp Business Cloud API setup — guides the user through creating a Meta Business Portfolio, registering a phone number, generating a permanent System User access token, configuring the webhook, and entering credentials into Taskmaster. Use when a user wants to connect WhatsApp via Meta's official Cloud API (verified badge, no QR dependency).
+metadata: {"taskmaster":{"emoji":"📱"}}
+---
+# WhatsApp Business Cloud API
+Handles the full Meta Cloud API setup. This is the official WhatsApp Business Platform — messages arrive via Meta webhooks instead of a QR-linked device. It unlocks a verified green checkmark, message templates for proactive outreach, and eliminates the phone dependency entirely.
+## When to activate
+- User asks about connecting WhatsApp via Meta's official API or Business Platform
+- User mentions "Cloud API", "WABA", "Meta Business Manager", "verified badge", or "green checkmark"
+- User wants WhatsApp without needing a physical phone linked
+- User has a dedicated number for a business WhatsApp account
+- User asks why they need a separate number for Cloud API
+## What it unlocks
+- **Verified business profile** — Meta's green checkmark badge builds customer trust
+- **No phone dependency** — no linked device, no QR scan every 14 days
+- **Message templates** — send proactive outreach messages to opted-in customers
+- **Higher reliability** — webhooks from Meta's infrastructure, not a linked device session
+## Important: Number exclusivity
+A phone number can only be on **one** WhatsApp connection at a time. A number registered with Meta Cloud API cannot also be used with Baileys (QR). The two providers can coexist on one Taskmaster instance but must use different phone numbers.
+## Key Storage
+Cloud API credentials are stored directly in the Taskmaster config, not in API key slots. Use the Setup page (WhatsApp → gear icon → Add Cloud API Account) to enter them. The four required values are:
+| Field | What it is | Where to find it |
+|-------|-----------|-----------------|
+| Phone Number ID | Numeric ID for the registered number | WhatsApp Manager → Phone Numbers tab |
+| Business Account ID | Your WABA (WhatsApp Business Account) ID | WhatsApp Manager → Business Account section |
+| Access Token | Permanent System User token | Meta Business Settings → System Users |
+| Webhook Verify Token | A string you define (shared secret) | You generate this; enter same value in Taskmaster and Meta |
+## References
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Full Meta Cloud API setup | Credentials not yet entered or user starting from scratch | `references/setup-guide.md` |
+Load the reference and follow it step by step.

package/skills/whatsapp-business/references/setup-guide.md ADDED Viewed

@@ -0,0 +1,258 @@
+# WhatsApp Business Cloud API — Setup Guide
+Walk the user through the full Meta Cloud API setup from scratch: Business Portfolio → WABA → number registration → System User token → webhook → Taskmaster config.
+## Before You Start
+**Remote Access must be enabled first.** Cloud API requires a publicly reachable webhook URL so Meta can deliver messages. Check that Remote Access (Tailscale Funnel) is active in Setup. If it isn't, the "Cloud API" option in Setup will be greyed out. Guide the user to enable it before proceeding — the `taskmaster` skill has a Remote Access setup guide.
+**Only one QR-linked (Baileys) account is supported per workspace.** If the workspace already has a Baileys account, the Baileys option will be greyed out in Setup. Cloud API accounts have no Taskmaster-enforced limit (Meta allows up to 2 phone numbers per WABA on the free tier).
+**Sessions are shared across numbers.** Taskmaster sessions are keyed by customer phone number, not by which WhatsApp number they messaged. A customer who texts both the Baileys number and a Cloud API number lands in the same conversation thread. This is usually desirable (one agent, continuous history), but means the agent cannot distinguish which number the customer used.
+1. Check memory (e.g. `memory/admin/infrastructure.md`) for the public URL — do NOT ask the user for it. Construct the webhook URL as `https://{public-host}/webhook/whatsapp`. The Setup page shows this URL automatically once Remote Access is active.
+2. The user needs a phone number that has never been registered with WhatsApp — or one that has been fully deleted from any previous WhatsApp account. A fresh SIM or a VoIP number works. They said they already have one — confirm this.
+3. Have the user ready at a desktop browser.
+## What to tell the user upfront
+> "To connect via Meta's official WhatsApp Business API, we need to set up four things in Meta:
+>
+> 1. A Meta Business Portfolio (if you don't have one)
+> 2. A WhatsApp Business Account with your new number registered
+> 3. A permanent access token from a System User
+> 4. A webhook so Meta can send messages to Taskmaster
+>
+> This takes about 15–20 minutes. I'll guide you through each step."
+---
+## Step 1: Meta Business Portfolio
+**URL: business.facebook.com**
+> "Go to **business.facebook.com** and sign in with your Facebook/Meta account.
+>
+> If you see a Business Portfolio dashboard, you're good. If you're prompted to create one, click **Create account**, enter your business name, and follow the prompts."
+Wait for confirmation.
+---
+## Step 2: Create a WhatsApp Business Account (WABA) and register the phone number
+This is a single 3-step wizard in Meta Business Suite that covers both WABA creation and phone number registration.
+**Before starting the wizard**, make sure the Business Portfolio has complete contact information — Meta will block the wizard if it doesn't:
+> "First, click the gear icon (⚙) at the bottom-left to open Settings → **Business info**.
+>
+> Check that the following are filled in: business address (street, city, postcode, country), phone number, and email. If any are missing, add them and save before continuing."
+Then start the wizard:
+> "Still in Settings, click the gear icon (⚙) at the bottom-left of business.facebook.com to open Settings.
+>
+> In the left sidebar, click **Accounts** → **WhatsApp accounts**.
+>
+> Click the **+ Add** button (top-right), then choose **Create a new WhatsApp business account** (not 'Link')."
+**Step 2a — Details:**
+> "Fill in:
+> - **WhatsApp business display name** — your business name (e.g. Beagle Taxi)
+> - **Category** — choose the most appropriate (e.g. Travel and transportation)
+> - Optionally expand **Show more options** to set timezone, description, and website
+>
+> Click **Continue**."
+**Step 2b — Phone number:**
+> "Enter your dedicated phone number. Click **Continue**."
+**Step 2c — Phone verification:**
+> "Meta will call or SMS the number with a verification code. Enter the code to confirm ownership."
+Wait for confirmation the WABA and phone number are verified and the wizard has completed.
+---
+## Step 3: Get the Business Account ID and Phone Number ID
+Now open WhatsApp Manager (the WABA now exists, so access is granted):
+> "In your browser, go to: **https://business.facebook.com/latest/whatsapp_manager**"
+**Phone Number ID:**
+> "In the left sidebar, click **Phone numbers**. Click on your number to open its details.
+>
+> Look for **Phone number ID** — a long string of digits. Copy it and send it to me."
+Store as `phoneNumberId` in config.
+**Business Account ID (WABA ID):**
+> "At the top of WhatsApp Manager, near your account name, you'll see the **WhatsApp Business Account ID** (a long number). Copy it and send it to me."
+Store as `businessAccountId` in config.
+---
+## Step 5: Create a Meta App (if needed)
+To use the Cloud API, you need a Meta Developer App linked to your WABA.
+**URL: developers.facebook.com/apps**
+> "Go to **developers.facebook.com/apps** and sign in.
+>
+> Click **Create App**. Choose **Business** as the app type. Enter a name (e.g. 'Taskmaster') and click **Create app**."
+Once the app is created:
+> "Inside the app dashboard, click **Add Product** → find **WhatsApp** → click **Set up**.
+>
+> You'll be asked to connect a WhatsApp Business Account. Select the WABA you just created."
+Wait for confirmation.
+---
+## Step 6: Create a System User with a permanent access token
+User access tokens expire. A System User token is permanent.
+**Navigation: business.facebook.com → Business Settings → System Users**
+> "Go back to **business.facebook.com**. In the left sidebar, click **Business Settings** → **Users** → **System Users**.
+>
+> Click **Add** and create a new system user:
+> - **Name:** something like 'Taskmaster Bot'
+> - **Role:** Admin (needed to send messages)
+>
+> Click **Add system user**."
+Now grant the system user access to the WhatsApp asset:
+> "With the system user selected, click **Add Assets**.
+>
+> Choose **Apps**, find your Taskmaster app, tick **Manage app**, and click **Save changes**.
+>
+> Then choose **WhatsApp Accounts**, select your WABA, tick **Full control**, and click **Save changes**."
+Now generate the token:
+> "Click **Generate token** at the top of the system user page.
+>
+> Select your Taskmaster app from the dropdown.
+>
+> Tick these permissions: `whatsapp_business_messaging` and `whatsapp_business_management`.
+>
+> Set expiry to **Never**.
+>
+> Click **Generate token** and copy the token — it starts with `EAA...`. Send it to me."
+Validate: must start with `EAA`, 100+ characters.
+Store: enter as Access Token in Taskmaster UI (next step).
+---
+## Step 7: Generate a Webhook Verify Token
+The verify token is a shared secret you define — Meta sends it to Taskmaster when verifying the webhook.
+> "We need a short random string for the webhook verify token. I'll suggest one — or you can make up your own (letters and numbers, no spaces):
+>
+> `tm-{random 8 chars}` — for example: `tm-xk29mq7r`
+>
+> This goes into both Taskmaster and Meta. Note it down."
+---
+## Step 8: Enter credentials in Taskmaster
+> "Now open the Taskmaster control panel at `{control_panel_url}`.
+>
+> Go to **Setup** → find the WhatsApp row → click the gear icon → scroll to **Add Cloud API Account**.
+>
+> Enter:
+> - **Account name:** something like 'Business' or 'Meta'
+> - **Phone Number ID:** (from Step 4)
+> - **Business Account ID:** (from Step 4)
+> - **Access Token:** (from Step 6)
+> - **Webhook Verify Token:** (from Step 7)
+>
+> Click **Add Account**. Note the **Webhook URL** shown — you'll need it in the next step."
+Wait for confirmation. The webhook URL will be shown in the UI after saving.
+---
+## Step 9: Configure the webhook in Meta
+**Navigation: developers.facebook.com → Your App → WhatsApp → Configuration → Webhooks**
+> "Back in the Meta Developer App dashboard:
+>
+> Click **WhatsApp** in the left sidebar → **Configuration**.
+>
+> Under **Webhooks**, click **Edit** (or **Configure webhooks**).
+>
+> Enter:
+> - **Callback URL:** `{webhook_url}` (from the Taskmaster UI in the previous step)
+> - **Verify token:** `{verify_token}` (the string from Step 7)
+>
+> Click **Verify and save**."
+Meta will send a GET request to Taskmaster to verify. If it succeeds, the webhook status changes to Verified.
+> "After verification, subscribe to webhook fields. Tick **messages** under the WhatsApp Business Account section. Click **Save**."
+Wait for confirmation.
+---
+## Step 10: Confirm
+> "WhatsApp Business Cloud API is now connected:
+>
+> - **Number:** {phone number} — registered with Meta
+> - **Provider:** Meta Cloud API (webhook-based, no phone dependency)
+> - **Webhook:** verified and subscribed
+>
+> Send a test message to the number from a customer's phone. Taskmaster should respond within a few seconds."
+Store setup details in memory (WABA ID, phone number ID, app name, webhook URL, system user name) for future reference.
+---
+## Webhook URL
+The webhook URL is always: `https://{public-host}/webhook/whatsapp`
+Where `{public-host}` is the device's public URL (Tailscale Funnel or other tunnel). This must be accessible from the public internet — Meta's servers must be able to reach it.
+---
+## Troubleshooting
+| Problem | Solution |
+|---------|----------|
+| "Setup can't be completed — business has not met WhatsApp's policy requirements" | The Business Portfolio is missing contact information. Go to Settings → **Business info** and fill in: business address (street, city, postcode, country), phone number, and email. Save, then retry the WABA creation wizard. |
+| Webhook verification fails | Check the webhook URL is publicly accessible (not just on Tailscale). Tailscale Funnel must be enabled. Check the verify token matches exactly. |
+| Phone number already in use | The number must be removed from any existing WhatsApp account first. Go to WhatsApp app → Settings → Linked Devices and remove if it's there. Or contact Meta support if it's stuck. |
+| Token expires | System User tokens with "Never" expiry don't expire. If it does, regenerate in Business Settings → System Users → Generate token. |
+| Messages not arriving | Check webhook subscription: App Dashboard → WhatsApp → Configuration → confirm "messages" field is subscribed. |
+| "Permission denied" errors | System user needs Admin role AND asset access to both the App and the WABA. Recheck Step 6. |
+| 401 from Meta API | Access token invalid or revoked. Regenerate in Business Settings → System Users. |
+| Number not eligible | Some VoIP numbers are rejected by Meta. Use a real mobile number or try a different VoIP provider. |
+---
+## Test vs Live
+| | Test number | Registered number |
+|---|---|---|
+| Provided by | Meta (in Developer app sandbox) | You register your own number |
+| Recipients | Only pre-approved test numbers | Any WhatsApp user |
+| For | Development and testing | Production |
+The Developer App sandbox provides a free test number and pre-approved recipients. Use it to verify the integration works before registering your real business number.