@laburen/openclaw-plugin-whatsapp-api 0.0.1 → 0.2.0

package/index.js

@@ -0,0 +1,1363 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+//#region src/core/accounts.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* Account resolution for the WhatsApp API channel.
+*
+* Reads `channels.whatsapp-api` (and per-account entries) from Clawdbot config
+* and returns fully resolved defaults for webhooks, Graph API, and media.
+*/
+const CHANNEL_ID$1 = "whatsapp-api";
+const DEFAULT_WEBHOOK_PATH = "/webhook/whatsapp-api";
+const DEFAULT_API_VERSION = "v22.0";
+const DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_BACKOFF_MS = 500;
+const DEFAULT_DEDUPE_TTL_MS = 5 * 6e4;
+const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
+const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+const DEFAULT_MEDIA_REQUEST_TIMEOUT_MS = 15e3;
+function getChannelConfig(cfg) {
+	return (cfg.channels ?? {})[CHANNEL_ID$1] ?? {};
+}
+/**
+* Lists configured WhatsApp API account ids.
+*
+* If `channels.whatsapp-api.accounts` is empty, returns the default account id
+* so a single implicit account still works.
+*
+* @param cfg - Loaded Clawdbot / OpenClaw configuration
+* @returns Distinct account ids
+*
+* @example
+* ```typescript
+* const ids = listAccountIds(cfg);
+* // ['default'] or ['acct-a', 'acct-b']
+* ```
+*/
+function listAccountIds(cfg) {
+	const channelCfg = getChannelConfig(cfg);
+	const ids = /* @__PURE__ */ new Set();
+	const accounts = channelCfg.accounts ?? {};
+	if (Object.keys(accounts).length > 0) for (const id of Object.keys(accounts)) ids.add(id);
+	else ids.add(DEFAULT_ACCOUNT_ID);
+	return [...ids];
+}
+/**
+* Resolves one account to effective settings (tokens, paths, limits).
+*
+* Unknown account ids fall back to an empty per-account object so channel-level
+* keys still apply.
+*
+* @param cfg - Loaded configuration
+* @param accountId - Account id, or `null`/`undefined` for default
+* @returns Merged {@link ResolvedWhatsAppApiAccount}
+*/
+function resolveAccount(cfg, accountId) {
+	const channelCfg = getChannelConfig(cfg);
+	const id = accountId ?? DEFAULT_ACCOUNT_ID;
+	const accountCfg = (channelCfg.accounts ?? {})[id] ?? {};
+	return {
+		accountId: id,
+		enabled: accountCfg.enabled ?? true,
+		webhookPath: accountCfg.webhookPath ?? channelCfg.webhookPath ?? DEFAULT_WEBHOOK_PATH,
+		inboundSharedSecret: accountCfg.inboundSharedSecret ?? channelCfg.inboundSharedSecret,
+		inboundAccessToken: accountCfg.inboundAccessToken ?? channelCfg.inboundAccessToken,
+		outboundPhoneNumberId: accountCfg.outboundPhoneNumberId ?? channelCfg.outboundPhoneNumberId,
+		outboundAccessToken: accountCfg.outboundAccessToken ?? channelCfg.outboundAccessToken,
+		outboundApiVersion: accountCfg.outboundApiVersion ?? channelCfg.outboundApiVersion ?? DEFAULT_API_VERSION,
+		requestTimeoutMs: accountCfg.requestTimeoutMs ?? channelCfg.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+		maxRetries: accountCfg.maxRetries ?? channelCfg.maxRetries ?? DEFAULT_MAX_RETRIES,
+		retryBackoffMs: accountCfg.retryBackoffMs ?? channelCfg.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS,
+		dedupeTtlMs: accountCfg.dedupeTtlMs ?? channelCfg.dedupeTtlMs ?? DEFAULT_DEDUPE_TTL_MS,
+		maxBodyBytes: accountCfg.maxBodyBytes ?? channelCfg.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+		mediaMaxBytes: accountCfg.mediaMaxBytes ?? channelCfg.mediaMaxBytes ?? DEFAULT_MEDIA_MAX_BYTES,
+		mediaRequestTimeoutMs: accountCfg.mediaRequestTimeoutMs ?? channelCfg.mediaRequestTimeoutMs ?? DEFAULT_MEDIA_REQUEST_TIMEOUT_MS,
+		mediaTempDir: accountCfg.mediaTempDir ?? channelCfg.mediaTempDir
+	};
+}
+//#endregion
+//#region src/utils/media/mime.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* MIME type and WhatsApp message kind inference from file names and MIME strings.
+*/
+const MIME_BY_EXT = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	".mp4": "video/mp4",
+	".mov": "video/quicktime",
+	".webm": "video/webm",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".ogg": "audio/ogg",
+	".opus": "audio/ogg",
+	".m4a": "audio/mp4",
+	".pdf": "application/pdf",
+	".txt": "text/plain",
+	".csv": "text/csv",
+	".json": "application/json",
+	".zip": "application/zip"
+};
+function normalizeMime(value) {
+	const trimmed = value?.trim();
+	if (!trimmed) return;
+	return trimmed.split(";")[0]?.trim().toLowerCase();
+}
+/**
+* Maps MIME type and/or file extension to a WhatsApp Cloud API `type` bucket.
+*
+* @param params.mimeType - Optional raw MIME (e.g. from Graph)
+* @param params.fileNameOrUrl - Used for extension fallback when MIME is absent
+* @returns One of `image`, `video`, `audio`, or `document`
+*/
+function mediaKindFromMimeOrName(params) {
+	const mime = normalizeMime(params.mimeType);
+	if (mime?.startsWith("image/")) return "image";
+	if (mime?.startsWith("video/")) return "video";
+	if (mime?.startsWith("audio/")) return "audio";
+	const extMime = MIME_BY_EXT[path.extname(params.fileNameOrUrl ?? "").toLowerCase()];
+	if (extMime?.startsWith("image/")) return "image";
+	if (extMime?.startsWith("video/")) return "video";
+	if (extMime?.startsWith("audio/")) return "audio";
+	return "document";
+}
+/**
+* Looks up a MIME type from a file path or name extension.
+*
+* @param fileNameOrPath - Path or URL ending with an extension
+*/
+function mimeFromFileName(fileNameOrPath) {
+	return MIME_BY_EXT[path.extname(fileNameOrPath).toLowerCase()];
+}
+/**
+* Picks a file extension for a MIME type (for saving inbound media to disk).
+*
+* @param mimeType - MIME string; unknown types map to `.bin`
+*/
+function extensionFromMime(mimeType) {
+	const mime = normalizeMime(mimeType);
+	if (!mime) return ".bin";
+	return Object.entries(MIME_BY_EXT).find(([, value]) => value === mime)?.[0] ?? ".bin";
+}
+//#endregion
+//#region src/utils/outbound/payload.ts
+function toTrimmedString(value) {
+	if (typeof value !== "string") return "";
+	return value.trim();
+}
+function asRecord$1(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+function parseNumber(value) {
+	const numeric = Number(value);
+	return Number.isFinite(numeric) ? numeric : void 0;
+}
+function getWhatsAppPayload(record) {
+	const whatsapp = asRecord$1(record.whatsapp) ?? {};
+	return {
+		...asRecord$1((asRecord$1(record.channelData) ?? {}).whatsapp) ?? {},
+		...whatsapp
+	};
+}
+function normalizeOutboundLocation(record) {
+	const whatsapp = getWhatsAppPayload(record);
+	const raw = asRecord$1(record.location) ?? asRecord$1(whatsapp.location);
+	if (!raw) return;
+	const latitude = parseNumber(raw.latitude ?? raw.lat);
+	const longitude = parseNumber(raw.longitude ?? raw.lng ?? raw.lon);
+	if (latitude === void 0 || longitude === void 0) return;
+	return {
+		latitude,
+		longitude,
+		name: toTrimmedString(raw.name || raw.title) || void 0,
+		address: toTrimmedString(raw.address) || void 0
+	};
+}
+function normalizeSingleContact(value) {
+	const raw = asRecord$1(value);
+	if (!raw) return;
+	const nameRecord = asRecord$1(raw.name);
+	const firstName = toTrimmedString(nameRecord?.first_name ?? raw.first_name ?? raw.firstName);
+	const lastName = toTrimmedString(nameRecord?.last_name ?? raw.last_name ?? raw.lastName);
+	const formattedName = toTrimmedString(nameRecord?.formatted_name) || toTrimmedString(raw.formatted_name || raw.formattedName || raw.display_name || raw.displayName) || [firstName, lastName].filter(Boolean).join(" ") || toTrimmedString(raw.phone || raw.msisdn);
+	if (!formattedName) return;
+	const phones = /* @__PURE__ */ new Set();
+	const directPhone = toTrimmedString(raw.phone || raw.msisdn);
+	if (directPhone) phones.add(directPhone);
+	const rawPhones = Array.isArray(raw.phones) ? raw.phones : [];
+	for (const rawPhone of rawPhones) {
+		if (typeof rawPhone === "string") {
+			const cleaned = toTrimmedString(rawPhone);
+			if (cleaned) phones.add(cleaned);
+			continue;
+		}
+		const cleaned = toTrimmedString(asRecord$1(rawPhone)?.phone);
+		if (cleaned) phones.add(cleaned);
+	}
+	return {
+		name: {
+			formatted_name: formattedName,
+			first_name: firstName || void 0,
+			last_name: lastName || void 0
+		},
+		phones: phones.size > 0 ? [...phones].map((phone) => ({ phone })) : void 0
+	};
+}
+function normalizeOutboundContacts(record) {
+	const whatsapp = getWhatsAppPayload(record);
+	const rawContacts = Array.isArray(record.contacts) && record.contacts || Array.isArray(whatsapp.contacts) && whatsapp.contacts || [];
+	const contacts = [];
+	for (const rawContact of rawContacts) {
+		const normalized = normalizeSingleContact(rawContact);
+		if (normalized) contacts.push(normalized);
+	}
+	const singleContact = normalizeSingleContact(record.contact) ?? normalizeSingleContact(whatsapp.contact);
+	if (singleContact) contacts.push(singleContact);
+	return contacts;
+}
+/**
+* Extracts text, `mediaUrl`/`mediaUrls`, location, and contacts from a reply payload.
+*
+* Supports nested `whatsapp` / `channelData.whatsapp` objects used by multi-channel hosts.
+*
+* @param payload - Arbitrary reply payload from the agent/dispatcher
+* @returns Safe defaults (empty strings/arrays) when shape is unknown
+*
+* @example
+* ```typescript
+* const n = normalizeOutboundPayload({ text: "Hi", mediaUrl: "https://..." });
+* // n.text, n.mediaUrls, n.location, n.contacts
+* ```
+*/
+function normalizeOutboundPayload(payload) {
+	if (!payload || typeof payload !== "object") return {
+		text: "",
+		mediaUrls: [],
+		contacts: []
+	};
+	const record = payload;
+	const text = toTrimmedString(record.text) || toTrimmedString(record.body);
+	const mediaUrls = /* @__PURE__ */ new Set();
+	const mediaUrl = toTrimmedString(record.mediaUrl);
+	if (mediaUrl) mediaUrls.add(mediaUrl);
+	if (Array.isArray(record.mediaUrls)) for (const value of record.mediaUrls) {
+		const url = toTrimmedString(value);
+		if (url) mediaUrls.add(url);
+	}
+	return {
+		text,
+		mediaUrls: [...mediaUrls],
+		location: normalizeOutboundLocation(record),
+		contacts: normalizeOutboundContacts(record)
+	};
+}
+//#endregion
+//#region src/outbound.ts
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeRecipient(to) {
+	const trimmed = to.trim();
+	if (trimmed.startsWith("+")) return trimmed.slice(1);
+	return trimmed;
+}
+function readGraphError(bodyText) {
+	try {
+		return JSON.parse(bodyText).error?.message ?? null;
+	} catch {
+		return null;
+	}
+}
+function isRetryableStatus$1(status) {
+	return status === 429 || status >= 500;
+}
+async function withTimeout$1(input, init, timeoutMs) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(input, {
+			...init,
+			signal: controller.signal
+		});
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function readRetryAfterMs(res) {
+	const value = res.headers.get("retry-after");
+	if (!value) return null;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds * 1e3);
+	return null;
+}
+function resolveGraphAuth(account) {
+	const phoneNumberId = account.outboundPhoneNumberId?.trim();
+	const accessToken = account.outboundAccessToken?.trim();
+	if (!phoneNumberId || !accessToken) throw new Error("Missing outboundPhoneNumberId/outboundAccessToken in whatsapp-api account config");
+	return {
+		phoneNumberId,
+		accessToken
+	};
+}
+async function sendWithRetry(params) {
+	let lastErr = null;
+	const maxAttempts = Math.max(1, params.account.maxRetries + 1);
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) try {
+		const res = await withTimeout$1(params.endpoint, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${params.accessToken}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify(params.payload)
+		}, params.account.requestTimeoutMs);
+		const bodyText = await res.text();
+		if (!res.ok) {
+			const detail = readGraphError(bodyText);
+			const err = /* @__PURE__ */ new Error(`Meta API send failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`);
+			if (!isRetryableStatus$1(res.status)) throw err;
+			lastErr = err;
+			const retryAfterMs = readRetryAfterMs(res);
+			if (attempt < maxAttempts) await sleep$1(retryAfterMs ?? params.account.retryBackoffMs * attempt);
+			continue;
+		}
+		const messageId = JSON.parse(bodyText).messages?.[0]?.id;
+		return messageId && messageId.trim() ? messageId.trim() : "unknown";
+	} catch (err) {
+		lastErr = err;
+		if (attempt >= maxAttempts) break;
+		await sleep$1(params.account.retryBackoffMs * attempt);
+		continue;
+	}
+	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown outbound error"));
+}
+async function uploadMediaFromLocalPath(params) {
+	const bytes = await readFile(params.localPath);
+	if (bytes.byteLength > params.account.mediaMaxBytes) throw new Error(`Local media exceeds mediaMaxBytes (${bytes.byteLength} > ${params.account.mediaMaxBytes})`);
+	const fileName = params.localPath.split("/").pop() ?? "media.bin";
+	const mimeType = mimeFromFileName(fileName);
+	const uploadEndpoint = params.endpoint.replace(/\/messages$/, "/media");
+	const maxAttempts = Math.max(1, params.account.maxRetries + 1);
+	let lastErr = null;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		try {
+			const form = new FormData();
+			form.append("messaging_product", "whatsapp");
+			form.append("type", mimeType ?? "application/octet-stream");
+			form.append("file", new Blob([bytes], { type: mimeType ?? "application/octet-stream" }), fileName);
+			const res = await withTimeout$1(uploadEndpoint, {
+				method: "POST",
+				headers: { authorization: `Bearer ${params.accessToken}` },
+				body: form
+			}, params.account.requestTimeoutMs);
+			const bodyText = await res.text();
+			if (!res.ok) {
+				const err = /* @__PURE__ */ new Error(`Meta media upload failed: HTTP ${res.status} ${bodyText}`);
+				if (!isRetryableStatus$1(res.status)) throw err;
+				lastErr = err;
+			} else {
+				const parsed = JSON.parse(bodyText);
+				if (!parsed.id?.trim()) throw new Error("Meta media upload did not return media id");
+				return {
+					id: parsed.id.trim(),
+					mimeType
+				};
+			}
+		} catch (err) {
+			lastErr = err;
+		}
+		if (attempt < maxAttempts) await sleep$1(params.account.retryBackoffMs * attempt);
+	}
+	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown media upload error"));
+}
+function isLocalMediaPath(value) {
+	return value.startsWith("/") || value.toLowerCase().startsWith("file://");
+}
+function toLocalPath(value) {
+	if (value.toLowerCase().startsWith("file://")) return decodeURIComponent(value.replace(/^file:\/\//i, ""));
+	return value;
+}
+async function sendWhatsAppApiMedia(params) {
+	const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
+	const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
+	const kind = mediaKindFromMimeOrName({ fileNameOrUrl: params.mediaUrl });
+	let mediaPayload;
+	if (isLocalMediaPath(params.mediaUrl)) {
+		const localPath = toLocalPath(params.mediaUrl);
+		const uploaded = await uploadMediaFromLocalPath({
+			endpoint,
+			account: params.account,
+			accessToken,
+			localPath,
+			kind
+		});
+		mediaPayload = kind === "document" ? {
+			id: uploaded.id,
+			filename: localPath.split("/").pop() ?? "document"
+		} : { id: uploaded.id };
+	} else mediaPayload = kind === "document" ? {
+		link: params.mediaUrl,
+		filename: params.mediaUrl.split("/").pop() ?? "document"
+	} : { link: params.mediaUrl };
+	if (params.text && (kind === "image" || kind === "video" || kind === "document")) mediaPayload.caption = params.text;
+	return await sendWithRetry({
+		endpoint,
+		account: params.account,
+		accessToken,
+		payload: {
+			messaging_product: "whatsapp",
+			to: normalizeRecipient(params.to),
+			type: kind,
+			[kind]: mediaPayload
+		}
+	});
+}
+async function sendWhatsAppApiLocation(params) {
+	const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
+	return await sendWithRetry({
+		endpoint: `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`,
+		account: params.account,
+		accessToken,
+		payload: {
+			messaging_product: "whatsapp",
+			to: normalizeRecipient(params.to),
+			type: "location",
+			location: {
+				latitude: params.location.latitude,
+				longitude: params.location.longitude,
+				name: params.location.name,
+				address: params.location.address
+			}
+		}
+	});
+}
+async function sendWhatsAppApiContacts(params) {
+	const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
+	return await sendWithRetry({
+		endpoint: `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`,
+		account: params.account,
+		accessToken,
+		payload: {
+			messaging_product: "whatsapp",
+			to: normalizeRecipient(params.to),
+			type: "contacts",
+			contacts: params.contacts
+		}
+	});
+}
+/**
+* Sends a plain text message via the Cloud API.
+*
+* @param params - Recipient, body, and resolved account (tokens + API version)
+* @returns Graph message id (or `"unknown"` if the response omits it)
+* @throws If outbound credentials are missing or the recipient is empty
+* @throws On non-retryable HTTP errors or exhausted retries
+*/
+async function sendWhatsAppApiText(params) {
+	const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
+	const recipient = normalizeRecipient(params.to);
+	if (!recipient) throw new Error("Recipient id is empty");
+	const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
+	const payload = {
+		messaging_product: "whatsapp",
+		to: recipient,
+		type: "text",
+		text: { body: params.text }
+	};
+	return await sendWithRetry({
+		endpoint,
+		account: params.account,
+		accessToken,
+		payload
+	});
+}
+/**
+* Sends one or more Graph messages derived from a structured reply payload.
+*
+* May send text only, multiple media messages, a location, and/or contacts vCard payloads.
+*
+* @param params.to - WhatsApp user id (digits; leading `+` is stripped upstream)
+* @param params.payload - Same shape as {@link normalizeOutboundPayload} accepts
+* @param params.account - Resolved account for Graph auth and limits
+* @returns Message ids for each Graph call; empty array if there is nothing to send
+*/
+async function sendWhatsAppApiReplyPayload(params) {
+	const normalized = normalizeOutboundPayload(params.payload);
+	if (!normalized.text && normalized.mediaUrls.length === 0 && !normalized.location && normalized.contacts.length === 0) return [];
+	if (normalized.mediaUrls.length === 0 && !normalized.location && normalized.contacts.length === 0) return [await sendWhatsAppApiText({
+		to: params.to,
+		text: normalized.text,
+		account: params.account
+	})];
+	const sentIds = [];
+	if (normalized.text && normalized.mediaUrls.length === 0) sentIds.push(await sendWhatsAppApiText({
+		to: params.to,
+		text: normalized.text,
+		account: params.account
+	}));
+	for (const [index, mediaUrl] of normalized.mediaUrls.entries()) {
+		const messageId = await sendWhatsAppApiMedia({
+			to: params.to,
+			mediaUrl,
+			text: index === 0 ? normalized.text : void 0,
+			account: params.account
+		});
+		sentIds.push(messageId);
+	}
+	if (normalized.location) sentIds.push(await sendWhatsAppApiLocation({
+		to: params.to,
+		location: normalized.location,
+		account: params.account
+	}));
+	if (normalized.contacts.length > 0) sentIds.push(await sendWhatsAppApiContacts({
+		to: params.to,
+		contacts: normalized.contacts,
+		account: params.account
+	}));
+	return sentIds;
+}
+//#endregion
+//#region src/core/runtime.ts
+let pluginApi = null;
+/**
+* Stores the plugin API for the lifetime of the process (set from `register()`).
+*
+* @param api - OpenClaw plugin API instance
+*/
+function setPluginApi(api) {
+	pluginApi = api;
+}
+/**
+* Returns the stored plugin API.
+*
+* @returns The API previously passed to {@link setPluginApi}
+* @throws If {@link setPluginApi} has not been called yet
+*/
+function getPluginApi() {
+	if (!pluginApi) throw new Error("whatsapp-api plugin API not initialized");
+	return pluginApi;
+}
+/**
+* Convenience accessor for `getPluginApi().runtime` (config, logging, channel hooks).
+*
+* @returns OpenClaw plugin runtime
+* @throws If the plugin API was not initialised
+*/
+function getPluginRuntime() {
+	return getPluginApi().runtime;
+}
+//#endregion
+//#region src/utils/common.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* Small type-narrowing helpers for parsing untrusted JSON (webhooks, payloads).
+*/
+/**
+* Narrows a value to a plain object record (not array, not null).
+*
+* @param value - Typically a JSON subtree
+* @returns The object, or `null` if not a non-array object
+*/
+function asRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	return value;
+}
+/**
+* Returns the value if it is an array, otherwise an empty array.
+*
+* @param value - Any JSON value
+*/
+function asArray(value) {
+	return Array.isArray(value) ? value : [];
+}
+/**
+* Returns a non-empty trimmed string, or `undefined`.
+*
+* @param value - Any JSON value
+*/
+function asTrimmedString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+//#endregion
+//#region src/core/wa-logger.ts
+const CYAN = "\x1B[36m";
+const YELLOW = "\x1B[33m";
+const RED = "\x1B[31m";
+const GRAY = "\x1B[90m";
+const RESET = "\x1B[0m";
+function consoleFallback(subsystem) {
+	const tag = `whatsapp-api/${subsystem}`;
+	return {
+		debug: (msg, meta) => console.debug(`${GRAY}[${tag}]${RESET}`, msg, ...meta ? [meta] : []),
+		info: (msg, meta) => console.log(`${CYAN}[${tag}]${RESET}`, msg, ...meta ? [meta] : []),
+		warn: (msg, meta) => console.warn(`${YELLOW}[${tag}]${RESET}`, msg, ...meta ? [meta] : []),
+		error: (msg, meta) => console.error(`${RED}[${tag}]${RESET}`, msg, ...meta ? [meta] : [])
+	};
+}
+function resolveRuntimeLogger(subsystem) {
+	try {
+		return getPluginRuntime().logging.getChildLogger({ subsystem: `whatsapp-api/${subsystem}` });
+	} catch {
+		return null;
+	}
+}
+function formatMessage(message, meta) {
+	if (!meta || Object.keys(meta).length === 0) return message;
+	const parts = Object.entries(meta).map(([k, v]) => {
+		if (v === void 0 || v === null) return null;
+		if (typeof v === "object") return `${k}=${JSON.stringify(v)}`;
+		return `${k}=${v}`;
+	}).filter(Boolean);
+	return parts.length > 0 ? `${message} (${parts.join(", ")})` : message;
+}
+function createWaLogger(subsystem) {
+	let cachedLogger = null;
+	let resolved = false;
+	function getLogger() {
+		if (!resolved) {
+			cachedLogger = resolveRuntimeLogger(subsystem);
+			if (cachedLogger) resolved = true;
+		}
+		return cachedLogger ?? consoleFallback(subsystem);
+	}
+	return {
+		subsystem,
+		debug(message, meta) {
+			getLogger().debug?.(formatMessage(message, meta), meta);
+		},
+		info(message, meta) {
+			getLogger().info(formatMessage(message, meta), meta);
+		},
+		warn(message, meta) {
+			getLogger().warn(formatMessage(message, meta), meta);
+		},
+		error(message, meta) {
+			getLogger().error(formatMessage(message, meta), meta);
+		},
+		child(name) {
+			return createWaLogger(`${subsystem}/${name}`);
+		}
+	};
+}
+/**
+* Creates a logger for a logical subsystem (e.g. `"webhook"`, `"channel/gateway"`).
+*
+* @param subsystem - Short name; prefixed with `whatsapp-api/` for routing
+* @returns Logger with `debug`/`info`/`warn`/`error` and `child()`
+*
+* @example
+* ```typescript
+* const log = waLogger("channel/gateway");
+* log.info("registered HTTP route", { path: routePath });
+* ```
+*/
+function waLogger(subsystem) {
+	return createWaLogger(subsystem);
+}
+//#endregion
+//#region src/utils/media/inbound.ts
+/**
+* SPDX-License-Identifier: MIT
+*
+* Downloads inbound media from the Graph API and writes a temp file for the agent.
+*
+* Uses `inboundAccessToken` or falls back to `outboundAccessToken` for bearer auth.
+*/
+const mediaLog = waLogger("media/inbound");
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableStatus(status) {
+	return status === 429 || status >= 500;
+}
+async function withTimeout(input, init, timeoutMs) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(input, {
+			...init,
+			signal: controller.signal
+		});
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function fetchWithRetry(params) {
+	const maxAttempts = Math.max(1, params.account.maxRetries + 1);
+	let lastErr = null;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		try {
+			const res = await withTimeout(params.url, params.init, Math.max(500, params.account.mediaRequestTimeoutMs));
+			if (res.ok) return res;
+			const body = await res.text();
+			const err = /* @__PURE__ */ new Error(`HTTP ${res.status} ${body}`);
+			if (!isRetryableStatus(res.status)) throw err;
+			lastErr = err;
+		} catch (err) {
+			lastErr = err;
+		}
+		if (attempt < maxAttempts) await sleep(params.account.retryBackoffMs * attempt);
+	}
+	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown media error"));
+}
+function resolveAccessToken(account) {
+	const token = account.inboundAccessToken?.trim() ?? account.outboundAccessToken?.trim();
+	if (!token) throw new Error("Missing inboundAccessToken/outboundAccessToken for media download");
+	return token;
+}
+function resolveMediaStorageDir(account) {
+	const root = account.mediaTempDir?.trim() || path.join(tmpdir(), "openclaw-whatsapp-api-media");
+	return path.join(root, account.accountId);
+}
+function sanitizeFileName(base) {
+	return base.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+/**
+* Resolves `message.media` to a local file path for OpenClaw's inbound context.
+*
+* On any failure (missing token, Graph error, size limit), returns `{}` and logs.
+*
+* @param params.account - Resolved account (tokens, version, media limits, temp dir)
+* @param params.message - Parsed inbound message (must include `media.id` to fetch)
+* @param params.log - Optional warn sink (e.g. channel logger)
+* @returns `mediaPath` and `mediaType` when a file was written; otherwise empty object
+*/
+async function downloadInboundMediaAttachment(params) {
+	try {
+		const media = params.message.media;
+		if (!media?.id) return {};
+		const token = resolveAccessToken(params.account);
+		const mediaInfoEndpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${media.id}`;
+		let mediaInfoRes;
+		try {
+			mediaInfoRes = await fetchWithRetry({
+				account: params.account,
+				url: mediaInfoEndpoint,
+				init: {
+					method: "GET",
+					headers: { authorization: `Bearer ${token}` }
+				}
+			});
+		} catch (err) {
+			mediaLog.warn("media metadata fetch failed", {
+				mediaId: media.id,
+				error: String(err)
+			});
+			return {};
+		}
+		const meta = asRecord(await mediaInfoRes.json());
+		const mediaUrl = typeof meta?.url === "string" ? meta.url.trim() : "";
+		if (!mediaUrl) {
+			mediaLog.warn("media metadata missing URL", { mediaId: media.id });
+			return {};
+		}
+		const mediaType = typeof meta?.mime_type === "string" && meta.mime_type.trim() || media.mimeType || void 0;
+		let mediaRes;
+		try {
+			mediaRes = await fetchWithRetry({
+				account: params.account,
+				url: mediaUrl,
+				init: {
+					method: "GET",
+					headers: { authorization: `Bearer ${token}` }
+				}
+			});
+		} catch (err) {
+			mediaLog.warn("media download failed", {
+				mediaId: media.id,
+				error: String(err)
+			});
+			return {};
+		}
+		const bytes = new Uint8Array(await mediaRes.arrayBuffer());
+		if (bytes.byteLength > params.account.mediaMaxBytes) {
+			mediaLog.warn("media too large", {
+				mediaId: media.id,
+				size: bytes.byteLength,
+				limit: params.account.mediaMaxBytes
+			});
+			return {};
+		}
+		const dir = resolveMediaStorageDir(params.account);
+		await mkdir(dir, { recursive: true });
+		const extension = extensionFromMime(mediaType);
+		const baseName = sanitizeFileName(media.fileName || `${media.kind}-${media.id}${extension}`);
+		const filePath = path.join(dir, `${Date.now()}-${baseName}`);
+		await writeFile(filePath, bytes);
+		return {
+			mediaPath: filePath,
+			mediaType
+		};
+	} catch (err) {
+		mediaLog.warn("media attachment resolution failed", {
+			messageId: params.message.messageId,
+			error: String(err)
+		});
+		return {};
+	}
+}
+//#endregion
+//#region src/inbound.ts
+function readTextPayload(msg) {
+	const readLocationText = (location) => {
+		const coord = `${location.latitude.toFixed(6)}, ${location.longitude.toFixed(6)}`;
+		const parts = [location.name, location.address].filter((value) => typeof value === "string" && Boolean(value.trim()));
+		return `<location: ${coord}${parts.length > 0 ? `; ${parts.join(" - ")}` : ""}>`;
+	};
+	const readContactLabel = (contact) => {
+		const primaryPhone = contact.phones[0];
+		const fields = [contact.name, primaryPhone].filter((value) => typeof value === "string" && Boolean(value.trim()));
+		return fields.length > 0 ? fields.join(", ") : void 0;
+	};
+	const readContactsText = (contacts) => {
+		if (contacts.length === 0) return "<contacts>";
+		if (contacts.length === 1) {
+			const label = readContactLabel(contacts[0]);
+			return label ? `<contact: ${label}>` : "<contact>";
+		}
+		const labels = contacts.map((contact) => readContactLabel(contact)).filter((value) => Boolean(value));
+		if (labels.length === 0) return `<contacts: ${contacts.length} contacts>`;
+		const shown = labels.slice(0, 3);
+		const remaining = Math.max(contacts.length - shown.length, 0);
+		const suffix = remaining > 0 ? ` (+${remaining} more)` : "";
+		return `<contacts: ${shown.join(", ")}${suffix}>`;
+	};
+	const msgType = typeof msg.type === "string" ? msg.type : "";
+	if (msgType === "text") {
+		const text = asRecord(msg.text);
+		return { text: typeof text?.body === "string" ? text.body.trim() : "" };
+	}
+	if (msgType === "image" || msgType === "video" || msgType === "audio" || msgType === "document" || msgType === "sticker") {
+		const rawMedia = asRecord(msg[msgType]);
+		const mediaId = asTrimmedString(rawMedia?.id);
+		const mimeType = asTrimmedString(rawMedia?.mime_type);
+		const fileName = asTrimmedString(rawMedia?.filename);
+		const caption = asTrimmedString(rawMedia?.caption);
+		const placeholder = `<media:${msgType}>`;
+		return {
+			text: caption ? `${caption}\n\n${placeholder}` : placeholder,
+			media: mediaId ? {
+				id: mediaId,
+				kind: msgType,
+				mimeType,
+				fileName
+			} : void 0
+		};
+	}
+	if (msgType === "location") {
+		const rawLocation = asRecord(msg.location);
+		const latitude = Number(rawLocation?.latitude);
+		const longitude = Number(rawLocation?.longitude);
+		if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) return { text: "<location>" };
+		const location = {
+			latitude,
+			longitude,
+			name: asTrimmedString(rawLocation?.name),
+			address: asTrimmedString(rawLocation?.address),
+			url: asTrimmedString(rawLocation?.url)
+		};
+		return {
+			text: readLocationText(location),
+			location
+		};
+	}
+	if (msgType === "contacts") {
+		const contacts = [];
+		for (const contactRaw of asArray(msg.contacts)) {
+			const contact = asRecord(contactRaw);
+			if (!contact) continue;
+			const nameRecord = asRecord(contact.name);
+			const name = asTrimmedString(nameRecord?.formatted_name) ?? asTrimmedString(nameRecord?.first_name) ?? asTrimmedString(nameRecord?.last_name);
+			const phones = asArray(contact.phones).map((phoneRaw) => asTrimmedString(asRecord(phoneRaw)?.phone)).filter((value) => Boolean(value));
+			contacts.push({
+				name,
+				phones
+			});
+		}
+		return {
+			text: readContactsText(contacts),
+			contacts
+		};
+	}
+	if (msgType === "reaction") return { text: "<reaction>" };
+	if (msgType === "button") return { text: "<button>" };
+	if (msgType === "interactive") return { text: "<interactive>" };
+	return { text: "" };
+}
+/**
+* Extracts inbound user messages from a Cloud API webhook body.
+*
+* Skips non-`messages` fields, empty bodies, and entries without `from`/`id`.
+*
+* @param params.payload - Parsed JSON object from the webhook POST body
+* @param params.accountId - Account id to attach to each message
+* @returns Zero or more normalised messages (order preserved)
+*
+* @example
+* ```typescript
+* const messages = parseWhatsAppCloudInbound({ payload: JSON.parse(body), accountId: "default" });
+* for (const m of messages) {
+*   console.log(m.from, m.text);
+* }
+* ```
+*/
+function parseWhatsAppCloudInbound(params) {
+	const root = asRecord(params.payload);
+	if (!root) return [];
+	const result = [];
+	const entries = asArray(root.entry);
+	for (const entryRaw of entries) {
+		const entry = asRecord(entryRaw);
+		if (!entry) continue;
+		const changes = asArray(entry.changes);
+		for (const changeRaw of changes) {
+			const change = asRecord(changeRaw);
+			if (!change) continue;
+			if (change.field !== "messages") continue;
+			const value = asRecord(change.value);
+			if (!value) continue;
+			const metadata = asRecord(value.metadata) ?? {};
+			const to = typeof metadata.display_phone_number === "string" && metadata.display_phone_number.trim() || typeof metadata.phone_number_id === "string" && metadata.phone_number_id.trim() || "";
+			const contactNames = /* @__PURE__ */ new Map();
+			for (const contactRaw of asArray(value.contacts)) {
+				const contact = asRecord(contactRaw);
+				if (!contact) continue;
+				const waId = typeof contact.wa_id === "string" ? contact.wa_id.trim() : "";
+				const profile = asRecord(contact.profile);
+				const name = typeof profile?.name === "string" ? profile.name.trim() : "";
+				if (waId && name) contactNames.set(waId, name);
+			}
+			const messages = asArray(value.messages);
+			for (const messageRaw of messages) {
+				const msg = asRecord(messageRaw);
+				if (!msg) continue;
+				const from = typeof msg.from === "string" ? msg.from.trim() : "";
+				const messageId = typeof msg.id === "string" ? msg.id.trim() : "";
+				if (!from || !messageId) continue;
+				const parsed = readTextPayload(msg);
+				if (!parsed.text) continue;
+				const context = asRecord(msg.context);
+				const replyToId = asTrimmedString(context?.id) ?? asTrimmedString(context?.message_id);
+				const replyToSender = asTrimmedString(context?.from);
+				const replyToBody = asTrimmedString(context?.body) ?? asTrimmedString(asRecord(context?.text)?.body) ?? asTrimmedString(asRecord(context?.quoted_message)?.body);
+				const timestampRaw = typeof msg.timestamp === "string" ? Number(msg.timestamp) : NaN;
+				const timestamp = Number.isFinite(timestampRaw) && timestampRaw > 0 ? timestampRaw * 1e3 : void 0;
+				result.push({
+					accountId: params.accountId,
+					from,
+					to,
+					messageId,
+					text: parsed.text,
+					chatType: "direct",
+					timestamp,
+					senderName: contactNames.get(from),
+					replyToId,
+					replyToBody,
+					replyToSender,
+					media: parsed.media,
+					location: parsed.location,
+					contacts: parsed.contacts
+				});
+			}
+		}
+	}
+	return result;
+}
+//#endregion
+//#region src/webhook.ts
+const webhookLog = waLogger("webhook");
+const dedupeStore = /* @__PURE__ */ new Map();
+function cleanupDedupe(now) {
+	for (const [key, expiresAt] of dedupeStore.entries()) if (expiresAt <= now) dedupeStore.delete(key);
+}
+function isDuplicate(accountId, messageId, ttlMs) {
+	const now = Date.now();
+	cleanupDedupe(now);
+	const key = `${accountId}:${messageId}`;
+	const current = dedupeStore.get(key);
+	if (current && current > now) return true;
+	dedupeStore.set(key, now + ttlMs);
+	return false;
+}
+async function readBody(req, maxBodyBytes) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+		total += buf.length;
+		if (total > maxBodyBytes) throw new Error("Payload exceeds maxBodyBytes");
+		chunks.push(buf);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+function isAuthorized(req, account) {
+	const required = account.inboundSharedSecret?.trim();
+	if (!required) return true;
+	const header = req.headers["x-openclaw-shared-secret"];
+	return (Array.isArray(header) ? header[0] : header)?.trim() === required;
+}
+function json(res, statusCode, body) {
+	res.statusCode = statusCode;
+	res.setHeader("content-type", "application/json; charset=utf-8");
+	res.end(JSON.stringify(body));
+}
+/**
+* Handles a single HTTP request for the account's webhook path.
+*
+* - Rejects non-`POST` with `405`.
+* - Enforces `X-Openclaw-Shared-Secret` when `inboundSharedSecret` is set.
+* - Returns `400` on oversize or invalid JSON.
+* - Always ends the response; runs `onMessage` after responding (fire-and-forget loop).
+*
+* @param params.req - Node HTTP incoming message
+* @param params.res - Node HTTP server response (will be `end()`ed)
+* @param params.account - Resolved account (limits, secrets, dedupe TTL)
+* @param params.log - Optional overrides for info/warn/error (gateway may inject)
+* @param params.onMessage - Called for each non-duplicate parsed message
+* @returns `true` when this handler wrote the response (caller should not double-send)
+*/
+async function handleWhatsAppApiWebhook(params) {
+	const { req, res, account, onMessage } = params;
+	if (req.method !== "POST") {
+		json(res, 405, {
+			ok: false,
+			error: "Method not allowed"
+		});
+		return true;
+	}
+	if (!isAuthorized(req, account)) {
+		json(res, 403, {
+			ok: false,
+			error: "Forbidden"
+		});
+		return true;
+	}
+	let payload;
+	try {
+		const bodyText = await readBody(req, account.maxBodyBytes);
+		payload = bodyText ? JSON.parse(bodyText) : {};
+	} catch (err) {
+		webhookLog.warn("invalid inbound payload", {
+			accountId: account.accountId,
+			error: String(err)
+		});
+		json(res, 400, {
+			ok: false,
+			error: "Invalid payload"
+		});
+		return true;
+	}
+	const inboundMessages = parseWhatsAppCloudInbound({
+		payload,
+		accountId: account.accountId
+	});
+	json(res, 200, {
+		ok: true,
+		accepted: inboundMessages.length,
+		accountId: account.accountId
+	});
+	(async () => {
+		for (const message of inboundMessages) {
+			if (isDuplicate(account.accountId, message.messageId, account.dedupeTtlMs)) continue;
+			try {
+				await onMessage(message);
+			} catch (err) {
+				webhookLog.error("failed processing message", {
+					messageId: message.messageId,
+					accountId: account.accountId,
+					error: String(err)
+				});
+			}
+		}
+	})();
+	return true;
+}
+//#endregion
+//#region src/channel/plugin.ts
+const CHANNEL_ID = "whatsapp-api";
+const log$1 = waLogger("channel");
+/**
+* Resolves when `signal` aborts, or never if `signal` is undefined.
+*
+* @param signal - Gateway abort signal from OpenClaw
+* @param onAbort - Optional cleanup (e.g. update status) when aborted
+*/
+function waitUntilAbort(signal, onAbort) {
+	return new Promise((resolve) => {
+		const done = () => {
+			onAbort?.();
+			resolve();
+		};
+		if (!signal) return;
+		if (signal.aborted) {
+			done();
+			return;
+		}
+		signal.addEventListener("abort", done, { once: true });
+	});
+}
+/**
+* Builds the string shown to the agent, using host `formatInboundEnvelope` when present.
+*
+* @param rt - Plugin runtime (may expose `channel.reply.formatInboundEnvelope`)
+* @param message - Parsed inbound message
+*/
+function buildInboundBody(rt, message) {
+	const formatFn = ((rt?.channel)?.reply)?.formatInboundEnvelope;
+	if (typeof formatFn === "function") return formatFn({
+		channel: "WhatsApp API",
+		from: message.senderName || message.from,
+		timestamp: message.timestamp,
+		body: message.text,
+		chatType: "direct",
+		sender: {
+			name: message.senderName,
+			id: message.from
+		}
+	});
+	return message.text;
+}
+/**
+* Resolves routing, enriches context (including optional media download), and runs the host dispatcher.
+*
+* @param params.accountId - Account handling this webhook
+* @param params.message - Normalised inbound message
+* @param params.onOutbound - Hook after at least one outbound Graph send succeeds
+*/
+async function dispatchInboundToAgent(params) {
+	const { accountId, message, onOutbound } = params;
+	const rt = getPluginRuntime();
+	const cfg = rt.config.loadConfig();
+	const account = resolveAccount(cfg, accountId);
+	const route = rt.channel.routing.resolveAgentRoute({
+		cfg,
+		channel: CHANNEL_ID,
+		accountId,
+		peer: {
+			kind: "direct",
+			id: message.from
+		}
+	});
+	const body = buildInboundBody(rt, message);
+	const to = `whatsapp-api:${message.from}`;
+	const mediaAttachment = await downloadInboundMediaAttachment({
+		account,
+		message,
+		log: { warn: (msg) => log$1.warn(msg) }
+	});
+	const replyApi = rt.channel.reply;
+	const ctxPayload = replyApi.finalizeInboundContext({
+		Body: body,
+		BodyForAgent: message.text,
+		RawBody: message.text,
+		CommandBody: message.text,
+		From: `whatsapp-api:${message.from}`,
+		To: to,
+		SessionKey: route.sessionKey,
+		AccountId: route.accountId,
+		ChatType: "direct",
+		ConversationLabel: message.senderName || message.from,
+		SenderName: message.senderName,
+		SenderId: message.from,
+		Provider: CHANNEL_ID,
+		Surface: CHANNEL_ID,
+		MessageSid: message.messageId,
+		ReplyToId: message.replyToId,
+		ReplyToBody: message.replyToBody,
+		ReplyToSender: message.replyToSender,
+		MediaPath: mediaAttachment.mediaPath,
+		MediaType: mediaAttachment.mediaType,
+		OriginatingChannel: CHANNEL_ID,
+		OriginatingTo: to
+	});
+	const dispatchFn = replyApi.dispatchReplyWithBufferedBlockDispatcher;
+	await dispatchFn({
+		ctx: ctxPayload,
+		cfg,
+		dispatcherOptions: {
+			deliver: async (payload) => {
+				const account = resolveAccount(cfg, accountId);
+				const sent = await sendWhatsAppApiReplyPayload({
+					to: message.from,
+					payload,
+					account
+				});
+				if (sent.length === 0) {
+					log$1.info("skipping outbound: reply payload empty", { messageId: message.messageId });
+					return;
+				}
+				log$1.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`, {
+					accountId,
+					messageId: message.messageId,
+					error: String(err)
+				});
+			}
+		}
+	});
+}
+/**
+* Factory for the WhatsApp API channel plugin instance.
+*
+* Call from the plugin `register()` hook with the same `api` used for HTTP routes.
+*
+* @param api - OpenClaw plugin API (runtime, `registerHttpRoute`, logger)
+* @returns `ChannelPlugin` metadata, config, outbound, and gateway implementation
+*
+* @example
+* ```typescript
+* api.registerChannel({ plugin: createWhatsAppApiChannel(api) });
+* ```
+*/
+function createWhatsAppApiChannel(api) {
+	return {
+		id: CHANNEL_ID,
+		meta: {
+			id: CHANNEL_ID,
+			label: "WhatsApp API",
+			selectionLabel: "WhatsApp API (Cloud)",
+			detailLabel: "WhatsApp API (Cloud)",
+			docsPath: "/channels/whatsapp-api",
+			blurb: "WhatsApp Cloud API channel with router-fed inbound webhook",
+			order: 5
+		},
+		capabilities: {
+			chatTypes: ["direct"],
+			media: true,
+			threads: false,
+			reactions: false,
+			edit: false,
+			unsend: false,
+			reply: false,
+			effects: false,
+			blockStreaming: false
+		},
+		config: {
+			listAccountIds: (cfg) => listAccountIds(cfg),
+			resolveAccount: (cfg, accountId) => resolveAccount(cfg, accountId),
+			defaultAccountId: () => DEFAULT_ACCOUNT_ID
+		},
+		outbound: {
+			deliveryMode: "gateway",
+			sendText: async ({ to, text, cfg, accountId }) => {
+				return {
+					channel: CHANNEL_ID,
+					chatId: to,
+					messageId: await sendWhatsAppApiText({
+						to,
+						text,
+						account: resolveAccount(cfg, accountId ?? null)
+					})
+				};
+			}
+		},
+		gateway: {
+			startAccount: async (ctx) => {
+				const gwLog = waLogger("channel/gateway");
+				const account = resolveAccount(ctx.cfg, ctx.accountId);
+				if (!account.enabled) {
+					gwLog.info("account disabled, skipping route", { accountId: account.accountId });
+					return waitUntilAbort(ctx.abortSignal);
+				}
+				const routePath = account.webhookPath;
+				ctx.setStatus({
+					accountId: account.accountId,
+					running: true,
+					lastStartAt: Date.now(),
+					lastError: null
+				});
+				api.registerHttpRoute({
+					path: routePath,
+					auth: "plugin",
+					replaceExisting: true,
+					handler: async (req, res) => {
+						return await handleWhatsAppApiWebhook({
+							req,
+							res,
+							account,
+							log: {
+								info: (msg) => gwLog.info(msg),
+								warn: (msg) => gwLog.warn(msg),
+								error: (msg) => gwLog.error(msg)
+							},
+							onMessage: async (message) => {
+								ctx.setStatus({
+									accountId: account.accountId,
+									lastInboundAt: Date.now()
+								});
+								try {
+									await dispatchInboundToAgent({
+										accountId: account.accountId,
+										message,
+										onOutbound: () => {
+											ctx.setStatus({
+												accountId: account.accountId,
+												lastOutboundAt: Date.now()
+											});
+										}
+									});
+								} catch (err) {
+									ctx.setStatus({
+										accountId: account.accountId,
+										lastError: String(err)
+									});
+									throw err;
+								}
+							}
+						});
+					}
+				});
+				gwLog.info("registered HTTP route", { path: routePath });
+				return waitUntilAbort(ctx.abortSignal, () => {
+					gwLog.info("stopped account", { accountId: account.accountId });
+					ctx.setStatus({
+						accountId: account.accountId,
+						running: false,
+						lastStopAt: Date.now()
+					});
+				});
+			},
+			stopAccount: async (ctx) => {
+				waLogger("channel/gateway").info("stopAccount called", { accountId: ctx.accountId });
+			}
+		}
+	};
+}
+//#endregion
+//#region index.ts
+const log = waLogger("plugin");
+/**
+* Default export: OpenClaw plugin manifest + `register` hook.
+*/
+const plugin = {
+	id: "whatsapp-api",
+	name: "WhatsApp API",
+	description: "WhatsApp API channel plugin with inbound webhook and direct Meta outbound",
+	configSchema: emptyPluginConfigSchema(),
+	register(api) {
+		setPluginApi(api);
+		api.registerChannel({ plugin: createWhatsAppApiChannel(api) });
+		log.info("plugin registered");
+	}
+};
+//#endregion
+export { plugin as default };