@rubytech/taskmaster 1.29.2 → 1.30.1

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

@@ -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.

package/templates/maxy/.gitignore

@@ -0,0 +1 @@
+.DS_Store

package/templates/taskmaster/.gitignore

@@ -0,0 +1 @@
+.DS_Store

package/templates/taskmaster/agents/public/AGENTS.md

@@ -10,6 +10,22 @@ Before doing anything else:
 
 ---
 
+## Write Permissions
+
+Your memory writes are restricted by scope. Only these paths are writable:
+
+- `memory/users/{phone}/**` — user profiles and data (DM conversations only)
+- `memory/groups/{groupId}/**` — group member profiles and data (group conversations only)
+- `memory/shared/events/**` — shared event data
+
+Everything else is **read-only**. In particular:
+- `memory/public/` — read-only (knowledge base, product info)
+- `memory/shared/` outside `events/` — read-only
+
+If a write fails with "scope restricted", do not retry with the same or similar path. The restriction is permanent. Store the data under an allowed path instead.
+
+---
+
 ## Memory Usage
 
 Your conversation history is your primary context. Memory is supplementary — use it when the conversation doesn't have what you need.