@laburen/openclaw-plugin-whatsapp-api 0.3.0 → 0.4.0

package/README.md

@@ -7,17 +7,6 @@ WhatsApp Cloud API channel for OpenClaw: your router receives Meta webhooks and
 ```bash
 openclaw plugins install @laburen/openclaw-plugin-whatsapp-api
 ```
-
-If you install from a local folder instead, copy the package into your OpenClaw extensions root and enable it in config (same plugin id: `whatsapp-api`).
-
-## Context window reminder (cron scripts)
-
-The plugin stores the last inbound message so **`check.sh`** can remind the user before Meta’s 24-hour window ends. Run **`setup.sh`** by path (no `cd` needed—the script resolves `check.sh` next to itself):
-
-```bash
-bash ~/.openclaw/extensions/whatsapp-api/src/scripts/setup.sh
-```
-
 ## Setup
 
 1. In [Meta for Developers](https://developers.facebook.com/), create or open an app with **WhatsApp** product enabled and note your **Phone number ID** and a long-lived **System User** or **Temporary** access token with `whatsapp_business_messaging` (and webhook permissions as required by your setup).
@@ -55,6 +44,18 @@ openclaw gateway restart
 
 - Transient failures (`429`, `5xx`, timeouts) are retried according to `maxRetries`, `retryBackoffMs`, and `requestTimeoutMs`.
 
+### WhatsApp 24-hour context window (reminder)
+
+WhatsApp Cloud API lets you send **session** messages (normal replies) only within about **24 hours** of the user’s last inbound message. After that window, outbound traffic is limited to **approved templates** until the user writes again.
+
+This plugin can nudge you before the window closes:
+
+1. **Snapshot on inbound:** For each user message handled by the channel, a hook writes `<OpenClaw state dir>/whatsapp-api/last-inbound-message.json` with `from`, `content`, `timestamp`, channel/account/conversation ids when present, and **`notified: false`**. That reset means a new user message clears any previous “we already warned” state.
+2. **Cron from the host:** On service start, the plugin runs `setup.sh` (shipped under `src/scripts/` in the npm package). The script registers an OpenClaw cron job that periodically invokes `check.sh` via the exec tool (see the job’s description in `setup.sh`).
+3. **`check.sh` behavior:** It reads the JSON file, skips if missing or `notified` is already `true`, and compares elapsed time since `timestamp` to a threshold (default **23 hours**). If the threshold is met, it runs `openclaw message send` to the user’s phone (parsed from `from`) with a configurable warning text, then sets **`notified: true`** in the same file so the warning is not sent again until the next inbound message.
+
+Useful environment variables for the scripts: `OPENCLAW_DIR` (defaults to `/home/<user>/.openclaw`), `THRESHOLD_MINUTES`, `WARNING_MESSAGE`, and `EVERY` for the cron interval when installing (default `30m`). To remove the job: `bash /path/to/node_modules/@laburen/openclaw-plugin-whatsapp-api/src/scripts/setup.sh --uninstall` (adjust path to your install).
+
 **Inbound webhook (from your router to OpenClaw)**
 
 | Item | Detail |

package/index.js

@@ -1,6 +1,8 @@
 import fs, { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 //#region src/core/accounts.ts
 const CHANNEL_ID$1 = "whatsapp-api";
 const DEFAULT_WEBHOOK_PATH = "/webhook/whatsapp-api";
@@ -95,9 +97,12 @@ const MIME_BY_EXT = {
 	".m4a": "audio/mp4",
 	".pdf": "application/pdf",
 	".txt": "text/plain",
+	".md": "text/markdown",
 	".csv": "text/csv",
 	".json": "application/json",
-	".zip": "application/zip"
+	".zip": "application/zip",
+	".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 };
 function normalizeMime(value) {
 	const trimmed = value?.trim();
@@ -1260,6 +1265,19 @@ function createWhatsAppApiChannel(api) {
 						account: resolveAccount(cfg, accountId ?? null)
 					})
 				};
+			},
+			sendMedia: async ({ to, mediaUrl, text, cfg, accountId }) => {
+				const account = resolveAccount(cfg, accountId ?? null);
+				return {
+					channel: CHANNEL_ID,
+					chatId: to,
+					messageId: await sendWhatsAppApiMedia({
+						to,
+						mediaUrl,
+						text: text || void 0,
+						account
+					})
+				};
 			}
 		},
 		gateway: {
@@ -1388,7 +1406,7 @@ async function writeLastInboundMessage(stateDir, data) {
 /**
 * SPDX-License-Identifier: MIT
 *
-* Persist last inbound message snapshot (used by background services).
+* Persist last inbound message snapshot for `check.sh` / cron window alerts.
 */
 const log$2 = waLogger("message-received/persist-last-inbound");
 async function handlePersistLastInbound(event, ctx) {
@@ -1430,17 +1448,33 @@ function registerAllPluginHooks(api) {
 //#endregion
 //#region src/services/context-window-check/register.ts
 const log$1 = waLogger("context-window-check");
-/**
-* Registers the `whatsapp-api` plugin service (state dir wiring; see `start` for
-* the commented in-process poll vs OpenClaw cron + scripts, described in the
-* module comment above).
-*/
+const SETUP_SH = path.join(path.dirname(fileURLToPath(import.meta.url)), "src", "scripts", "setup.sh");
+function runSetupSh() {
+	return new Promise((resolve, reject) => {
+		const child = spawn("bash", [SETUP_SH], {
+			stdio: "inherit",
+			env: process.env
+		});
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(`setup.sh exited with code ${code ?? signal}`));
+		});
+	});
+}
+/** Registers the `whatsapp-api` plugin service (state dir + cron setup). */
 function registerContextWindowCheckService(api) {
 	api.registerService({
 		id: "whatsapp-api",
 		start: async (ctx) => {
 			setPluginServiceStateDir(ctx.stateDir);
 			log$1.info("service started");
+			try {
+				await runSetupSh();
+				log$1.info("setup.sh finished");
+			} catch (error) {
+				log$1.error("setup.sh failed", { error: String(error) });
+			}
 		},
 		stop: async (_ctx) => {
 			setPluginServiceStateDir(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laburen/openclaw-plugin-whatsapp-api",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "WhatsApp API channel plugin for OpenClaw",
   "main": "index.js",