@laburen/openclaw-plugin-whatsapp-api 0.0.1

package/README.md

@@ -0,0 +1,123 @@
+# WhatsApp API Plugin for OpenClaw
+
+WhatsApp Cloud API channel for OpenClaw: your router receives Meta webhooks and forwards them to OpenClaw; replies go straight to the Meta Graph API.
+
+## Install
+
+```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).
+2. Point Meta’s webhook callback URL to **your** public HTTPS endpoint (router / reverse proxy). That service should forward the raw `POST` body to OpenClaw at the path you set as `webhookPath` (default below).
+3. Set the same verify token / shared secret flow your deployment uses: configure `inboundSharedSecret` in OpenClaw and send it from your router as the header `x-openclaw-shared-secret` (recommended).
+
+### Via OpenClaw Config
+
+Minimal example — set secrets and IDs (use env-backed config in production; never commit tokens):
+
+```bash
+openclaw config set channels.whatsapp-api.enabled true
+openclaw config set channels.whatsapp-api.inboundSharedSecret "your-internal-secret"
+openclaw config set channels.whatsapp-api.outboundPhoneNumberId "123456789012345"
+openclaw config set channels.whatsapp-api.outboundAccessToken "EAAG..."
+```
+
+Allow the plugin and enable its entry, then restart the gateway:
+
+```bash
+openclaw config set plugins.allow '["whatsapp-api"]'
+openclaw config set plugins.entries.whatsapp-api.enabled true
+openclaw gateway restart
+```
+
+## How It Works
+
+- Registers channel id **`whatsapp-api`** and exposes an inbound **`POST`** route (default **`/webhook/whatsapp-api`**).
+- Parses WhatsApp Cloud API webhook payloads (`entry[].changes[].value.messages[]`) and sends inbound text into the OpenClaw reply pipeline.
+- Outbound replies are sent **directly** to Meta:
+
+  `https://graph.facebook.com/{apiVersion}/{phoneNumberId}/messages`
+
+  with `Authorization: Bearer <outboundAccessToken>`.
+
+- Transient failures (`429`, `5xx`, timeouts) are retried according to `maxRetries`, `retryBackoffMs`, and `requestTimeoutMs`.
+
+**Inbound webhook (from your router to OpenClaw)**
+
+| Item | Detail |
+|------|--------|
+| Method | `POST` |
+| Path | Value of `webhookPath` |
+| Header (recommended) | `x-openclaw-shared-secret: <inboundSharedSecret>` |
+| Body | Raw WhatsApp Cloud webhook JSON forwarded by your router |
+
+Responses: **`403`** if the shared secret does not match, **`400`** if the payload is invalid, **`200`** when accepted (processing continues asynchronously after ACK).
+
+## Configuration
+
+```json
+{
+  "plugins": {
+    "allow": ["whatsapp-api"],
+    "entries": {
+      "whatsapp-api": {
+        "enabled": true
+      }
+    }
+  },
+  "channels": {
+    "whatsapp-api": {
+      "enabled": true,
+      "webhookPath": "/webhook/whatsapp-api",
+      "inboundSharedSecret": "replace-with-internal-secret",
+      "outboundPhoneNumberId": "123456789012345",
+      "outboundAccessToken": "EAAG...",
+      "outboundApiVersion": "v22.0",
+      "requestTimeoutMs": 10000,
+      "maxRetries": 2,
+      "retryBackoffMs": 500,
+      "dedupeTtlMs": 300000,
+      "maxBodyBytes": 524288,
+      "accounts": {
+        "default": {
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `plugins.entries.whatsapp-api.enabled` | Turn the plugin on or off | — |
+| `channels.whatsapp-api.enabled` | Turn the channel on or off | — |
+| `webhookPath` | HTTP path OpenClaw listens on for inbound webhooks | `/webhook/whatsapp-api` |
+| `inboundSharedSecret` | Secret your router must send (e.g. header `x-openclaw-shared-secret`) | — |
+| `outboundPhoneNumberId` | WhatsApp **Phone number ID** from Meta | — |
+| `outboundAccessToken` | Bearer token for Graph API sends | — |
+| `outboundApiVersion` | Graph API version segment in the URL | e.g. `v22.0` |
+| `requestTimeoutMs` | HTTP timeout for outbound calls (ms) | `10000` |
+| `maxRetries` | Retries on transient errors | `2` |
+| `retryBackoffMs` | Base backoff between retries (ms) | `500` |
+| `dedupeTtlMs` | Deduplication window for inbound events (ms) | `300000` |
+| `maxBodyBytes` | Max accepted webhook body size (bytes) | `524288` |
+| `accounts` | Per-account overrides (multi-tenant); keys are account ids | `{ "default": { "enabled": true } }` |
+
+Per-account fields can override phone id, token, retries, etc. under `channels["whatsapp-api"].accounts.<accountId>`.
+
+## Notes
+
+- Outbound mode is **direct-to-Meta** only (no third-party relay in this plugin).
+- Keep tokens out of logs and rotate them on a schedule.
+
+## Links
+
+- [WhatsApp Cloud API — Overview](https://developers.facebook.com/docs/whatsapp/cloud-api)
+- [Graph API — WhatsApp messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages)
+- [OpenClaw](https://github.com/openclaw/openclaw) (ecosystem reference)

package/index.ts

@@ -0,0 +1,16 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { createWhatsAppApiChannel } from "./src/channel.js";
+import { setPluginApi } from "./src/runtime.js";
+
+const plugin = {
+  id: "whatsapp-api",
+  name: "WhatsApp API",
+  description: "WhatsApp API channel plugin with inbound webhook and direct Meta outbound",
+  register(api: OpenClawPluginApi) {
+    setPluginApi(api);
+    api.registerChannel({ plugin: createWhatsAppApiChannel(api) });
+    api.logger.info("[whatsapp-api] plugin registered");
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,43 @@
+{
+  "id": "whatsapp-api",
+  "name": "WhatsApp API (Minimal)",
+  "description": "WhatsApp API channel plugin with inbound webhook and direct Meta outbound",
+  "channels": [
+    "whatsapp-api"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "defaults": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "outboundApiVersion": {
+            "type": "string"
+          },
+          "requestTimeoutMs": {
+            "type": "number",
+            "minimum": 100
+          },
+          "maxRetries": {
+            "type": "number",
+            "minimum": 0
+          },
+          "retryBackoffMs": {
+            "type": "number",
+            "minimum": 0
+          },
+          "dedupeTtlMs": {
+            "type": "number",
+            "minimum": 1000
+          },
+          "maxBodyBytes": {
+            "type": "number",
+            "minimum": 1024
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@laburen/openclaw-plugin-whatsapp-api",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "WhatsApp API channel plugin for OpenClaw",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,86 @@
+import type { ResolvedWhatsAppApiAccount } from "./types.js";
+
+const CHANNEL_ID = "whatsapp-api";
+const DEFAULT_ACCOUNT_ID = "default";
+const DEFAULT_WEBHOOK_PATH = "/webhook/whatsapp-api";
+const DEFAULT_API_VERSION = "v22.0";
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_BACKOFF_MS = 500;
+const DEFAULT_DEDUPE_TTL_MS = 5 * 60_000;
+const DEFAULT_MAX_BODY_BYTES = 512 * 1024;
+
+function getChannelConfig(cfg: Record<string, unknown>): Record<string, unknown> {
+  const channels = (cfg.channels as Record<string, unknown> | undefined) ?? {};
+  return (channels[CHANNEL_ID] as Record<string, unknown> | undefined) ?? {};
+}
+
+export function listAccountIds(cfg: Record<string, unknown>): string[] {
+  const channelCfg = getChannelConfig(cfg);
+  const ids = new Set<string>();
+  const accounts =
+    (channelCfg.accounts as Record<string, Record<string, unknown>> | undefined) ?? {};
+
+  if (Object.keys(accounts).length > 0) {
+    for (const id of Object.keys(accounts)) {
+      ids.add(id);
+    }
+  } else {
+    ids.add(DEFAULT_ACCOUNT_ID);
+  }
+
+  return [...ids];
+}
+
+export function resolveAccount(
+  cfg: Record<string, unknown>,
+  accountId?: string | null,
+): ResolvedWhatsAppApiAccount {
+  const channelCfg = getChannelConfig(cfg);
+  const id = accountId ?? DEFAULT_ACCOUNT_ID;
+  const accounts =
+    (channelCfg.accounts as Record<string, Record<string, unknown>> | undefined) ?? {};
+  const accountCfg = accounts[id] ?? {};
+
+  return {
+    accountId: id,
+    enabled: (accountCfg.enabled as boolean | undefined) ?? true,
+    webhookPath:
+      (accountCfg.webhookPath as string | undefined) ??
+      (channelCfg.webhookPath as string | undefined) ??
+      DEFAULT_WEBHOOK_PATH,
+    inboundSharedSecret:
+      (accountCfg.inboundSharedSecret as string | undefined) ??
+      (channelCfg.inboundSharedSecret as string | undefined),
+    outboundPhoneNumberId:
+      (accountCfg.outboundPhoneNumberId as string | undefined) ??
+      (channelCfg.outboundPhoneNumberId as string | undefined),
+    outboundAccessToken:
+      (accountCfg.outboundAccessToken as string | undefined) ??
+      (channelCfg.outboundAccessToken as string | undefined),
+    outboundApiVersion:
+      (accountCfg.outboundApiVersion as string | undefined) ??
+      (channelCfg.outboundApiVersion as string | undefined) ??
+      DEFAULT_API_VERSION,
+    requestTimeoutMs:
+      (accountCfg.requestTimeoutMs as number | undefined) ??
+      (channelCfg.requestTimeoutMs as number | undefined) ??
+      DEFAULT_REQUEST_TIMEOUT_MS,
+    maxRetries:
+      (accountCfg.maxRetries as number | undefined) ??
+      (channelCfg.maxRetries as number | undefined) ??
+      DEFAULT_MAX_RETRIES,
+    retryBackoffMs:
+      (accountCfg.retryBackoffMs as number | undefined) ??
+      (channelCfg.retryBackoffMs as number | undefined) ??
+      DEFAULT_RETRY_BACKOFF_MS,
+    dedupeTtlMs:
+      (accountCfg.dedupeTtlMs as number | undefined) ??
+      (channelCfg.dedupeTtlMs as number | undefined) ??
+      DEFAULT_DEDUPE_TTL_MS,
+    maxBodyBytes:
+      (accountCfg.maxBodyBytes as number | undefined) ??
+      (channelCfg.maxBodyBytes as number | undefined) ??
+      DEFAULT_MAX_BODY_BYTES,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,246 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { listAccountIds, resolveAccount } from "./accounts.js";
+import { sendWhatsAppApiText, normalizeReplyText } from "./outbound.js";
+import { getPluginRuntime } from "./runtime.js";
+import { handleWhatsAppApiWebhook } from "./webhook.js";
+import type { WhatsAppApiInboundMessage } from "./types.js";
+
+const CHANNEL_ID = "whatsapp-api";
+
+function waitUntilAbort(signal?: AbortSignal, onAbort?: () => void): Promise<void> {
+  return new Promise((resolve) => {
+    const done = () => {
+      onAbort?.();
+      resolve();
+    };
+    if (!signal) {
+      return;
+    }
+    if (signal.aborted) {
+      done();
+      return;
+    }
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+function buildInboundBody(rt: any, message: WhatsAppApiInboundMessage): string {
+  if (typeof rt?.channel?.reply?.formatInboundEnvelope === "function") {
+    return rt.channel.reply.formatInboundEnvelope({
+      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;
+}
+
+async function dispatchInboundToAgent(params: {
+  accountId: string;
+  message: WhatsAppApiInboundMessage;
+  log?: { info?: (msg: string) => void; error?: (msg: string) => void };
+  onOutbound?: () => void;
+}): Promise<void> {
+  const { accountId, message, log, onOutbound } = params;
+  const rt = getPluginRuntime() as any;
+  const cfg = await rt.config.loadConfig();
+  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 ctxPayload = rt.channel.reply.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,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: to,
+  });
+
+  await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg,
+    dispatcherOptions: {
+      deliver: async (payload: unknown) => {
+        const text = normalizeReplyText(payload);
+        if (!text) {
+          log?.info?.(
+            `[${CHANNEL_ID}] skipping outbound: reply text empty for messageId=${message.messageId}`,
+          );
+          return;
+        }
+        log?.info?.(
+          `[${CHANNEL_ID}] sending reply to ${message.from}, length=${text.length}`,
+        );
+        const account = resolveAccount(cfg, accountId);
+        const messageId = await sendWhatsAppApiText({
+          to: message.from,
+          text,
+          account,
+        });
+        log?.info?.(
+          `[${CHANNEL_ID}] reply sent to ${message.from}, messageId=${messageId}`,
+        );
+        onOutbound?.();
+      },
+      onError: (err: unknown, info: { kind?: string }) => {
+        log?.error?.(
+          `[${CHANNEL_ID}] ${info?.kind ?? "reply"} dispatch failed for account=${accountId} messageId=${message.messageId}: ${String(err)}`,
+        );
+      },
+    },
+  });
+}
+
+export function createWhatsAppApiChannel(api: OpenClawPluginApi) {
+  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" as const],
+      media: false,
+      threads: false,
+      reactions: false,
+      edit: false,
+      unsend: false,
+      reply: false,
+      effects: false,
+      blockStreaming: false,
+    },
+    config: {
+      listAccountIds: (cfg: Record<string, unknown>) => listAccountIds(cfg),
+      resolveAccount: (cfg: Record<string, unknown>, accountId?: string | null) =>
+        resolveAccount(cfg, accountId),
+      defaultAccountId: () => "default",
+    },
+    outbound: {
+      deliveryMode: "gateway" as const,
+      sendText: async ({
+        to,
+        text,
+        cfg,
+        accountId,
+      }: {
+        to: string;
+        text: string;
+        cfg: Record<string, unknown>;
+        accountId?: string;
+      }) => {
+        const account = resolveAccount(cfg, accountId ?? null);
+        const messageId = await sendWhatsAppApiText({
+          to,
+          text,
+          account,
+        });
+        return {
+          channel: CHANNEL_ID,
+          chatId: to,
+          messageId,
+        };
+      },
+    },
+    gateway: {
+      startAccount: async (ctx: any) => {
+        const account = resolveAccount(ctx.cfg, ctx.accountId);
+
+        if (!account.enabled) {
+          ctx.log?.info?.(`[${CHANNEL_ID}] account ${account.accountId} disabled, skipping route`);
+          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: ctx.log,
+              onMessage: async (message) => {
+                ctx.setStatus?.({
+                  accountId: account.accountId,
+                  lastInboundAt: Date.now(),
+                });
+                try {
+                  await dispatchInboundToAgent({
+                    accountId: account.accountId,
+                    message,
+                    log: ctx.log,
+                    onOutbound: () => {
+                      ctx.setStatus?.({
+                        accountId: account.accountId,
+                        lastOutboundAt: Date.now(),
+                      });
+                    },
+                  });
+                } catch (err) {
+                  ctx.setStatus?.({
+                    accountId: account.accountId,
+                    lastError: String(err),
+                  });
+                  throw err;
+                }
+              },
+            });
+          },
+        });
+
+        ctx.log?.info?.(`[${CHANNEL_ID}] registered HTTP route: ${routePath}`);
+
+        return waitUntilAbort(ctx.abortSignal, () => {
+          ctx.log?.info?.(`[${CHANNEL_ID}] stopped account ${account.accountId}`);
+          ctx.setStatus?.({
+            accountId: account.accountId,
+            running: false,
+            lastStopAt: Date.now(),
+          });
+        });
+      },
+      stopAccount: async (ctx: { accountId: string; log?: { info?: (msg: string) => void } }) => {
+        ctx.log?.info?.(`[${CHANNEL_ID}] stopAccount called for ${ctx.accountId}`);
+      },
+    },
+  };
+}

package/src/inbound.ts

@@ -0,0 +1,126 @@
+import type { WhatsAppApiInboundMessage } from "./types.js";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function readTextPayload(msg: Record<string, unknown>): string {
+  const msgType = typeof msg.type === "string" ? msg.type : "";
+  if (msgType === "text") {
+    const text = asRecord(msg.text);
+    return typeof text?.body === "string" ? text.body.trim() : "";
+  }
+
+  if (msgType === "image") return "<media:image>";
+  if (msgType === "video") return "<media:video>";
+  if (msgType === "audio") return "<media:audio>";
+  if (msgType === "document") return "<media:document>";
+  if (msgType === "sticker") return "<media:sticker>";
+  if (msgType === "location") return "<location>";
+  if (msgType === "contacts") return "<contacts>";
+  if (msgType === "reaction") return "<reaction>";
+  if (msgType === "button") return "<button>";
+  if (msgType === "interactive") return "<interactive>";
+
+  return "";
+}
+
+export function parseWhatsAppCloudInbound(params: {
+  payload: unknown;
+  accountId: string;
+}): WhatsAppApiInboundMessage[] {
+  const root = asRecord(params.payload);
+  if (!root) {
+    return [];
+  }
+
+  const result: WhatsAppApiInboundMessage[] = [];
+  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 = new Map<string, string>();
+      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 text = readTextPayload(msg);
+        if (!text) {
+          continue;
+        }
+
+        const context = asRecord(msg.context);
+        const replyToId = typeof context?.id === "string" ? context.id.trim() : undefined;
+        const timestampRaw = typeof msg.timestamp === "string" ? Number(msg.timestamp) : NaN;
+        const timestamp =
+          Number.isFinite(timestampRaw) && timestampRaw > 0 ? timestampRaw * 1000 : undefined;
+
+        result.push({
+          accountId: params.accountId,
+          from,
+          to,
+          messageId,
+          text,
+          chatType: "direct",
+          timestamp,
+          senderName: contactNames.get(from),
+          replyToId,
+        });
+      }
+    }
+  }
+
+  return result;
+}

package/src/outbound.ts

@@ -0,0 +1,126 @@
+import type {
+  ResolvedWhatsAppApiAccount,
+  WhatsAppApiSendTextParams,
+} from "./types.js";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeRecipient(to: string): string {
+  const trimmed = to.trim();
+  if (trimmed.startsWith("+")) {
+    return trimmed.slice(1);
+  }
+  return trimmed;
+}
+
+function readGraphError(bodyText: string): string | null {
+  try {
+    const parsed = JSON.parse(bodyText) as { error?: { message?: string } };
+    return parsed.error?.message ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+async function withTimeout(input: RequestInfo | URL, init: RequestInit, timeoutMs: number) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input, {
+      ...init,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function sendWhatsAppApiText(params: WhatsAppApiSendTextParams): Promise<string> {
+  const account = params.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");
+  }
+
+  const recipient = normalizeRecipient(params.to);
+  if (!recipient) {
+    throw new Error("Recipient id is empty");
+  }
+
+  const endpoint = `https://graph.facebook.com/${account.outboundApiVersion}/${phoneNumberId}/messages`;
+  const payload = {
+    messaging_product: "whatsapp",
+    to: recipient,
+    type: "text",
+    text: { body: params.text },
+  };
+
+  let lastErr: unknown = null;
+  const maxAttempts = Math.max(1, account.maxRetries + 1);
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const res = await withTimeout(
+        endpoint,
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${accessToken}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(payload),
+        },
+        account.requestTimeoutMs,
+      );
+      const bodyText = await res.text();
+      if (!res.ok) {
+        const detail = readGraphError(bodyText);
+        const err = new Error(
+          `Meta API send failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`,
+        );
+        if (!isRetryableStatus(res.status)) {
+          throw err;
+        }
+        lastErr = err;
+      } else {
+        const parsed = JSON.parse(bodyText) as { messages?: Array<{ id?: string }> };
+        const messageId = parsed.messages?.[0]?.id;
+        return messageId && messageId.trim() ? messageId.trim() : "unknown";
+      }
+    } catch (err) {
+      lastErr = err;
+      if (attempt >= maxAttempts) {
+        break;
+      }
+      await sleep(account.retryBackoffMs * attempt);
+      continue;
+    }
+
+    if (attempt >= maxAttempts) {
+      break;
+    }
+    await sleep(account.retryBackoffMs * attempt);
+  }
+
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown outbound error"));
+}
+
+export function normalizeReplyText(payload: unknown): string {
+  if (!payload || typeof payload !== "object") {
+    return "";
+  }
+  const asRecord = payload as Record<string, unknown>;
+  const candidates = [asRecord.text, asRecord.body];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return "";
+}

package/src/runtime.ts

@@ -0,0 +1,18 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+let pluginApi: OpenClawPluginApi | null = null;
+
+export function setPluginApi(api: OpenClawPluginApi): void {
+  pluginApi = api;
+}
+
+export function getPluginApi(): OpenClawPluginApi {
+  if (!pluginApi) {
+    throw new Error("whatsapp-api plugin API not initialized");
+  }
+  return pluginApi;
+}
+
+export function getPluginRuntime(): OpenClawPluginApi["runtime"] {
+  return getPluginApi().runtime;
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+export type ResolvedWhatsAppApiAccount = {
+  accountId: string;
+  enabled: boolean;
+  webhookPath: string;
+  inboundSharedSecret?: string;
+  outboundPhoneNumberId?: string;
+  outboundAccessToken?: string;
+  outboundApiVersion: string;
+  requestTimeoutMs: number;
+  maxRetries: number;
+  retryBackoffMs: number;
+  dedupeTtlMs: number;
+  maxBodyBytes: number;
+};
+
+export type WhatsAppApiInboundMessage = {
+  accountId: string;
+  from: string;
+  to: string;
+  messageId: string;
+  text: string;
+  chatType: "direct";
+  timestamp?: number;
+  senderName?: string;
+  replyToId?: string;
+};
+
+export type WhatsAppApiSendTextParams = {
+  to: string;
+  text: string;
+  account: ResolvedWhatsAppApiAccount;
+};

package/src/webhook.ts

@@ -0,0 +1,119 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { parseWhatsAppCloudInbound } from "./inbound.js";
+import type { ResolvedWhatsAppApiAccount, WhatsAppApiInboundMessage } from "./types.js";
+
+type LogLike = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+const dedupeStore = new Map<string, number>();
+
+function cleanupDedupe(now: number): void {
+  for (const [key, expiresAt] of dedupeStore.entries()) {
+    if (expiresAt <= now) {
+      dedupeStore.delete(key);
+    }
+  }
+}
+
+function isDuplicate(accountId: string, messageId: string, ttlMs: number): boolean {
+  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: IncomingMessage, maxBodyBytes: number): Promise<string> {
+  const chunks: Buffer[] = [];
+  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: IncomingMessage, account: ResolvedWhatsAppApiAccount): boolean {
+  const required = account.inboundSharedSecret?.trim();
+  if (!required) {
+    return true;
+  }
+  const header = req.headers["x-openclaw-shared-secret"];
+  const value = Array.isArray(header) ? header[0] : header;
+  return value?.trim() === required;
+}
+
+function json(res: ServerResponse, statusCode: number, body: Record<string, unknown>) {
+  res.statusCode = statusCode;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+}
+
+export async function handleWhatsAppApiWebhook(params: {
+  req: IncomingMessage;
+  res: ServerResponse;
+  account: ResolvedWhatsAppApiAccount;
+  log?: LogLike;
+  onMessage: (message: WhatsAppApiInboundMessage) => Promise<void>;
+}): Promise<boolean> {
+  const { req, res, account, log, 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: unknown;
+  try {
+    const bodyText = await readBody(req, account.maxBodyBytes);
+    payload = bodyText ? JSON.parse(bodyText) : {};
+  } catch (err) {
+    log?.warn?.(`[whatsapp-api] invalid inbound payload for account ${account.accountId}: ${String(err)}`);
+    json(res, 400, { ok: false, error: "Invalid payload" });
+    return true;
+  }
+
+  const inboundMessages = parseWhatsAppCloudInbound({
+    payload,
+    accountId: account.accountId,
+  });
+
+  // ACK immediately; process asynchronously to keep webhook latency low.
+  json(res, 200, {
+    ok: true,
+    accepted: inboundMessages.length,
+    accountId: account.accountId,
+  });
+
+  void (async () => {
+    for (const message of inboundMessages) {
+      if (isDuplicate(account.accountId, message.messageId, account.dedupeTtlMs)) {
+        continue;
+      }
+      try {
+        await onMessage(message);
+      } catch (err) {
+        log?.error?.(
+          `[whatsapp-api] failed processing message ${message.messageId} for account ${account.accountId}: ${String(err)}`,
+        );
+      }
+    }
+  })();
+
+  return true;
+}