@laburen/openclaw-plugin-whatsapp-api 0.2.3 → 0.3.1

package/README.md

@@ -7,9 +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`).
-
 ## 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).
@@ -47,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.d.ts

@@ -2,16 +2,21 @@ import { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
 //#region index.d.ts
 /**
- * Default export: OpenClaw plugin manifest + `register` hook.
+ * OpenClaw plugin metadata and registration hook. Default export of this package.
+ *
+ * Channel behaviour is implemented by {@link createWhatsAppApiChannel}; hooks and
+ * services are aggregated via {@link registerAllPluginHooks} and
+ * {@link registerAllPluginServices}.
  */
 declare const plugin: {
   id: string;
   name: string;
   description: string;
   /**
-   * Wires the channel into OpenClaw: saves plugin API, registers `whatsapp-api`.
+   * Called by OpenClaw when the plugin loads: publishes the channel, wires the
+   * global plugin API holder, then registers pipeline hooks and plugin services.
    *
-   * @param api - Provided by the host at plugin load time
+   * @param api - Plugin API injected by the host (config, runtime, registration helpers)
    */
   register(api: OpenClawPluginApi): void;
 };

package/index.js

@@ -1,6 +1,8 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+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";
@@ -1079,7 +1081,7 @@ async function handleWhatsAppApiWebhook(params) {
 //#endregion
 //#region src/channel/plugin.ts
 const CHANNEL_ID = "whatsapp-api";
-const log$1 = waLogger("channel");
+const log$3 = waLogger("channel");
 const DEFAULT_ACCOUNT_ID = "default";
 /**
 * Resolves when `signal` aborts, or never if `signal` is undefined.
@@ -1148,7 +1150,7 @@ async function dispatchInboundToAgent(params) {
 	const mediaAttachment = await downloadInboundMediaAttachment({
 		account,
 		message,
-		log: { warn: (msg) => log$1.warn(msg) }
+		log: { warn: (msg) => log$3.warn(msg) }
 	});
 	const replyApi = rt.channel.reply;
 	const ctxPayload = replyApi.finalizeInboundContext({
@@ -1188,17 +1190,17 @@ async function dispatchInboundToAgent(params) {
 					account
 				});
 				if (sent.length === 0) {
-					log$1.info("skipping outbound: reply payload empty", { messageId: message.messageId });
+					log$3.info("skipping outbound: reply payload empty", { messageId: message.messageId });
 					return;
 				}
-				log$1.info(`sent ${sent.length} outbound message(s)`, {
+				log$3.info(`sent ${sent.length} outbound message(s)`, {
 					to: message.from,
 					messageId: message.messageId
 				});
 				onOutbound?.();
 			},
 			onError: (err, info) => {
-				log$1.error(`${info?.kind ?? "reply"} dispatch failed`, {
+				log$3.error(`${info?.kind ?? "reply"} dispatch failed`, {
 					accountId,
 					messageId: message.messageId,
 					error: String(err)
@@ -1335,10 +1337,152 @@ function createWhatsAppApiChannel(api) {
 	};
 }
 //#endregion
+//#region src/plugin/plugin-state-dir.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* OpenClaw provides `ctx.stateDir` only inside a registered service's `start`.
+* Pipeline hooks (e.g. `message_received`) do not receive that context, so any
+* hook that must read/write under the plugin state tree needs the same path.
+*
+* Only code that actually persists or reads plugin state should import this module.
+* Other hooks/services stay unaware of it.
+*/
+let serviceStateDir = null;
+/**
+* @returns The last `stateDir` set by a plugin service `start`, or `null` if
+*   no service has started or after `stop` cleared it.
+*/
+function getPluginServiceStateDir() {
+	return serviceStateDir;
+}
+/**
+* Updates the path exposed to hooks. Called from service lifecycle (typically
+* `start` / `stop` of whichever service owns the OpenClaw service context).
+*/
+function setPluginServiceStateDir(dir) {
+	serviceStateDir = dir;
+}
+//#endregion
+//#region src/utils/last-inbound-persistence/store.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* Atomic JSON persistence for {@link LastInboundMessageSnapshot} under the
+* plugin state directory. Shared util for hooks and services.
+*/
+function getLastInboundMessagePath(stateDir) {
+	return path.join(stateDir, "whatsapp-api", "last-inbound-message.json");
+}
+/**
+* Persists the last inbound message snapshot (write-to-temp + rename).
+*/
+async function writeLastInboundMessage(stateDir, data) {
+	const filePath = getLastInboundMessagePath(stateDir);
+	const dir = path.dirname(filePath);
+	await fs.mkdir(dir, { recursive: true });
+	const tmpPath = `${filePath}.tmp`;
+	await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), "utf8");
+	await fs.rename(tmpPath, filePath);
+}
+//#endregion
+//#region src/hooks/message-received/handlers/persist-last-inbound.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* 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) {
+	const stateDir = getPluginServiceStateDir();
+	if (!stateDir) return;
+	const now = Date.now();
+	const inboundTimestamp = typeof event.timestamp === "number" && Number.isFinite(event.timestamp) ? event.timestamp : now;
+	const payload = {
+		from: event.from,
+		content: event.content,
+		timestamp: inboundTimestamp,
+		channelId: ctx.channelId,
+		accountId: ctx.accountId,
+		conversationId: ctx.conversationId,
+		notified: false
+	};
+	try {
+		await writeLastInboundMessage(stateDir, payload);
+		log$2.debug("last inbound message persisted");
+	} catch (error) {
+		log$2.warn(`failed to persist last inbound message: ${String(error)}`);
+	}
+}
+//#endregion
+//#region src/hooks/message-received/register.ts
+function registerMessageReceivedHook(api) {
+	api.on("message_received", async (event, ctx) => {
+		await handlePersistLastInbound(event, ctx);
+	});
+}
+//#endregion
+//#region src/hooks/register.ts
+/**
+* Registers all plugin-managed OpenClaw hooks for this extension.
+*/
+function registerAllPluginHooks(api) {
+	registerMessageReceivedHook(api);
+}
+//#endregion
+//#region src/services/context-window-check/register.ts
+const log$1 = waLogger("context-window-check");
+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);
+			log$1.info("service stopped");
+		}
+	});
+}
+//#endregion
+//#region src/services/register.ts
+/**
+* Registers all plugin-managed OpenClaw services for this extension.
+*/
+function registerAllPluginServices(api) {
+	registerContextWindowCheckService(api);
+}
+//#endregion
 //#region index.ts
 const log = waLogger("plugin");
 /**
-* Default export: OpenClaw plugin manifest + `register` hook.
+* OpenClaw plugin metadata and registration hook. Default export of this package.
+*
+* Channel behaviour is implemented by {@link createWhatsAppApiChannel}; hooks and
+* services are aggregated via {@link registerAllPluginHooks} and
+* {@link registerAllPluginServices}.
 */
 const plugin = {
 	id: "whatsapp-api",
@@ -1348,6 +1492,8 @@ const plugin = {
 		setPluginApi(api);
 		api.registerChannel({ plugin: createWhatsAppApiChannel(api) });
 		log.info("plugin registered");
+		registerAllPluginHooks(api);
+		registerAllPluginServices(api);
 	}
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laburen/openclaw-plugin-whatsapp-api",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "type": "module",
   "description": "WhatsApp API channel plugin for OpenClaw",
   "main": "index.js",
@@ -8,6 +8,7 @@
     "index.js",
     "index.d.ts",
     "openclaw.plugin.json",
+    "src/scripts",
     "README.md",
     "LICENSE"
   ],

package/src/scripts/check.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# check.sh - WhatsApp context window notifier
+# Reads last-inbound-message.json and sends a warning if the user hasn't
+# written in more than THRESHOLD_MINUTES and notified=false.
+
+OPENCLAW_DIR="${OPENCLAW_DIR:-/home/$(whoami)/.openclaw}"
+LAST_MSG_FILE="$OPENCLAW_DIR/whatsapp-api/last-inbound-message.json"
+# 23 hours in minutes
+THRESHOLD_MINUTES="${THRESHOLD_MINUTES:-$((23 * 60))}"
+WARNING_MESSAGE="${WARNING_MESSAGE:-Aviso: la ventana de contexto de WhatsApp esta por vencer. Si quieres seguir recibiendo mensajes, responde este chat para reabrir la ventana de 24 horas.}"
+
+if [ ! -f "$LAST_MSG_FILE" ]; then
+  echo "[whatsapp-window-notifier] File not found: $LAST_MSG_FILE — skipping."
+  exit 0
+fi
+
+TIMESTAMP=$(jq -r '.timestamp' "$LAST_MSG_FILE")
+NOTIFIED=$(jq -r '.notified' "$LAST_MSG_FILE")
+FROM=$(jq -r '.from' "$LAST_MSG_FILE")
+
+# Extract phone number: "whatsapp-api:5493496460785" → "5493496460785"
+PHONE=$(echo "$FROM" | sed 's/.*://')
+
+if [ "$NOTIFIED" = "true" ]; then
+  echo "[whatsapp-window-notifier] Already notified, skipping."
+  exit 0
+fi
+
+NOW_MS=$(date +%s%3N)
+ELAPSED_MS=$((NOW_MS - TIMESTAMP))
+ELAPSED_MIN=$((ELAPSED_MS / 60000))
+
+echo "[whatsapp-window-notifier] Elapsed: ${ELAPSED_MIN}m / threshold: ${THRESHOLD_MINUTES}m / target: $PHONE"
+
+if [ "$ELAPSED_MIN" -ge "$THRESHOLD_MINUTES" ]; then
+  openclaw message send \
+    --channel whatsapp-api \
+    --target "$PHONE" \
+    --message "$WARNING_MESSAGE"
+
+  TMP=$(mktemp)
+  jq '.notified = true' "$LAST_MSG_FILE" > "$TMP" && mv "$TMP" "$LAST_MSG_FILE"
+  echo "[whatsapp-window-notifier] Notification sent to $PHONE, notified=true set."
+else
+  echo "[whatsapp-window-notifier] Not enough time elapsed, no action."
+fi

package/src/scripts/setup.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# setup.sh - Installs/uninstalls the whatsapp-window-notifier cron job.
+# Run once per OpenClaw instance.
+#
+# Usage:
+#   bash setup.sh             → installs the cron
+#   bash setup.sh --uninstall → removes the cron
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK_SCRIPT="$SCRIPT_DIR/check.sh"
+JOB_NAME="whatsapp-window-notifier"
+EVERY="${EVERY:-30m}"
+UNINSTALL=false
+
+for arg in "$@"; do
+  case $arg in
+    --uninstall) UNINSTALL=true ;;
+  esac
+done
+
+if [ "$UNINSTALL" = "true" ]; then
+  JOB_ID=$(openclaw cron list --json 2>/dev/null | jq -r ".jobs[] | select(.name == \"$JOB_NAME\") | .id")
+  if [ -n "$JOB_ID" ]; then
+    openclaw cron rm "$JOB_ID"
+    echo "[$JOB_NAME] Cron job removed (id: $JOB_ID)."
+  else
+    echo "[$JOB_NAME] No cron job found to remove."
+  fi
+  exit 0
+fi
+
+# Check if already installed
+EXISTING=$(openclaw cron list --json 2>/dev/null | jq -r ".jobs[] | select(.name == \"$JOB_NAME\") | .id")
+if [ -n "$EXISTING" ]; then
+  echo "[$JOB_NAME] Already installed (id: $EXISTING). Run with --uninstall first to reinstall."
+  exit 0
+fi
+
+chmod +x "$CHECK_SCRIPT"
+
+openclaw cron add \
+  --name "$JOB_NAME" \
+  --every "$EVERY" \
+  --session isolated \
+  --no-deliver \
+  --description "Notifies user when WhatsApp 24h context window is about to expire" \
+  --message "Run this bash script using the exec tool and report nothing to the user: $CHECK_SCRIPT"
+
+echo "[$JOB_NAME] Cron job installed. Runs every $EVERY."