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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laburen/openclaw-plugin-whatsapp-api",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "type": "module",
   "description": "WhatsApp API channel plugin for OpenClaw",
   "files": [

package/src/accounts.ts

@@ -9,6 +9,8 @@ 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;
+const DEFAULT_MEDIA_MAX_BYTES = 20 * 1024 * 1024;
+const DEFAULT_MEDIA_REQUEST_TIMEOUT_MS = 15_000;
 
 function getChannelConfig(cfg: Record<string, unknown>): Record<string, unknown> {
   const channels = (cfg.channels as Record<string, unknown> | undefined) ?? {};
@@ -52,6 +54,9 @@ export function resolveAccount(
     inboundSharedSecret:
       (accountCfg.inboundSharedSecret as string | undefined) ??
       (channelCfg.inboundSharedSecret as string | undefined),
+    inboundAccessToken:
+      (accountCfg.inboundAccessToken as string | undefined) ??
+      (channelCfg.inboundAccessToken as string | undefined),
     outboundPhoneNumberId:
       (accountCfg.outboundPhoneNumberId as string | undefined) ??
       (channelCfg.outboundPhoneNumberId as string | undefined),
@@ -82,5 +87,16 @@ export function resolveAccount(
       (accountCfg.maxBodyBytes as number | undefined) ??
       (channelCfg.maxBodyBytes as number | undefined) ??
       DEFAULT_MAX_BODY_BYTES,
+    mediaMaxBytes:
+      (accountCfg.mediaMaxBytes as number | undefined) ??
+      (channelCfg.mediaMaxBytes as number | undefined) ??
+      DEFAULT_MEDIA_MAX_BYTES,
+    mediaRequestTimeoutMs:
+      (accountCfg.mediaRequestTimeoutMs as number | undefined) ??
+      (channelCfg.mediaRequestTimeoutMs as number | undefined) ??
+      DEFAULT_MEDIA_REQUEST_TIMEOUT_MS,
+    mediaTempDir:
+      (accountCfg.mediaTempDir as string | undefined) ??
+      (channelCfg.mediaTempDir as string | undefined),
   };
 }

package/src/channel.ts

@@ -1,7 +1,8 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { listAccountIds, resolveAccount } from "./accounts.js";
-import { sendWhatsAppApiText, normalizeReplyText } from "./outbound.js";
+import { sendWhatsAppApiReplyPayload, sendWhatsAppApiText } from "./outbound.js";
 import { getPluginRuntime } from "./runtime.js";
+import { downloadInboundMediaAttachment } from "./utils/media/inbound.js";
 import { handleWhatsAppApiWebhook } from "./webhook.js";
 import type { WhatsAppApiInboundMessage } from "./types.js";
 
@@ -44,12 +45,13 @@ function buildInboundBody(rt: any, message: WhatsAppApiInboundMessage): string {
 async function dispatchInboundToAgent(params: {
   accountId: string;
   message: WhatsAppApiInboundMessage;
-  log?: { info?: (msg: string) => void; error?: (msg: string) => void };
+  log?: { info?: (msg: string) => void; warn?: (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 account = resolveAccount(cfg, accountId);
   const route = rt.channel.routing.resolveAgentRoute({
     cfg,
     channel: CHANNEL_ID,
@@ -61,6 +63,11 @@ async function dispatchInboundToAgent(params: {
   });
   const body = buildInboundBody(rt, message);
   const to = `whatsapp-api:${message.from}`;
+  const mediaAttachment = await downloadInboundMediaAttachment({
+    account,
+    message,
+    log: params.log,
+  });
   const ctxPayload = rt.channel.reply.finalizeInboundContext({
     Body: body,
     BodyForAgent: message.text,
@@ -78,6 +85,10 @@ async function dispatchInboundToAgent(params: {
     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,
   });
@@ -87,24 +98,20 @@ async function dispatchInboundToAgent(params: {
     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({
+        const sent = await sendWhatsAppApiReplyPayload({
           to: message.from,
-          text,
+          payload,
           account,
         });
+        if (sent.length === 0) {
+          log?.info?.(
+            `[${CHANNEL_ID}] skipping outbound: reply payload empty for messageId=${message.messageId}`,
+          );
+          return;
+        }
         log?.info?.(
-          `[${CHANNEL_ID}] reply sent to ${message.from}, messageId=${messageId}`,
+          `[${CHANNEL_ID}] sent ${sent.length} outbound message(s) to ${message.from} for inbound=${message.messageId}`,
         );
         onOutbound?.();
       },
@@ -131,7 +138,7 @@ export function createWhatsAppApiChannel(api: OpenClawPluginApi) {
     },
     capabilities: {
       chatTypes: ["direct" as const],
-      media: false,
+      media: true,
       threads: false,
       reactions: false,
       edit: false,

package/src/inbound.ts

@@ -1,35 +1,132 @@
-import type { WhatsAppApiInboundMessage } from "./types.js";
+import type {
+  WhatsAppApiInboundContact,
+  WhatsAppApiInboundLocation,
+  WhatsAppApiInboundMessage,
+} from "./types.js";
+import { asArray, asRecord, asTrimmedString } from "./utils/common.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 readTextPayload(msg: Record<string, unknown>): {
+  text: string;
+  media?: WhatsAppApiInboundMessage["media"];
+  location?: WhatsAppApiInboundLocation;
+  contacts?: WhatsAppApiInboundContact[];
+} {
+  const readLocationText = (location: WhatsAppApiInboundLocation): string => {
+    const coord = `${location.latitude.toFixed(6)}, ${location.longitude.toFixed(6)}`;
+    const parts = [location.name, location.address].filter(
+      (value): value is string => typeof value === "string" && Boolean(value.trim()),
+    );
+    const suffix = parts.length > 0 ? `; ${parts.join(" - ")}` : "";
+    return `<location: ${coord}${suffix}>`;
+  };
 
-function asArray(value: unknown): unknown[] {
-  return Array.isArray(value) ? value : [];
-}
+  const readContactLabel = (contact: WhatsAppApiInboundContact): string | undefined => {
+    const primaryPhone = contact.phones[0];
+    const fields = [contact.name, primaryPhone].filter(
+      (value): value is string => typeof value === "string" && Boolean(value.trim()),
+    );
+    return fields.length > 0 ? fields.join(", ") : undefined;
+  };
+
+  const readContactsText = (contacts: WhatsAppApiInboundContact[]): string => {
+    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): value is string => 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}>`;
+  };
 
-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() : "";
+    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,
+          }
+        : undefined,
+    };
+  }
+  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: WhatsAppApiInboundLocation = {
+      latitude,
+      longitude,
+      name: asTrimmedString(rawLocation?.name),
+      address: asTrimmedString(rawLocation?.address),
+      url: asTrimmedString(rawLocation?.url),
+    };
+    return {
+      text: readLocationText(location),
+      location,
+    };
+  }
+  if (msgType === "contacts") {
+    const contacts: WhatsAppApiInboundContact[] = [];
+    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): value is string => 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>" };
 
-  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 "";
+  return { text: "" };
 }
 
 export function parseWhatsAppCloudInbound(params: {
@@ -96,13 +193,18 @@ export function parseWhatsAppCloudInbound(params: {
           continue;
         }
 
-        const text = readTextPayload(msg);
-        if (!text) {
+        const parsed = readTextPayload(msg);
+        if (!parsed.text) {
           continue;
         }
 
         const context = asRecord(msg.context);
-        const replyToId = typeof context?.id === "string" ? context.id.trim() : undefined;
+        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 * 1000 : undefined;
@@ -112,11 +214,16 @@ export function parseWhatsAppCloudInbound(params: {
           from,
           to,
           messageId,
-          text,
+          text: parsed.text,
           chatType: "direct",
           timestamp,
           senderName: contactNames.get(from),
           replyToId,
+          replyToBody,
+          replyToSender,
+          media: parsed.media,
+          location: parsed.location,
+          contacts: parsed.contacts,
         });
       }
     }

package/src/outbound.ts

@@ -2,6 +2,9 @@ import type {
   ResolvedWhatsAppApiAccount,
   WhatsAppApiSendTextParams,
 } from "./types.js";
+import { readFile } from "node:fs/promises";
+import { mediaKindFromMimeOrName, mimeFromFileName } from "./utils/media/mime.js";
+import { normalizeOutboundPayload } from "./utils/outbound/payload.js";
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -41,42 +44,48 @@ async function withTimeout(input: RequestInfo | URL, init: RequestInit, timeoutM
   }
 }
 
-export async function sendWhatsAppApiText(params: WhatsAppApiSendTextParams): Promise<string> {
-  const account = params.account;
+function readRetryAfterMs(res: Response): number | null {
+  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 * 1000);
+  }
+  return null;
+}
+
+function resolveGraphAuth(account: ResolvedWhatsAppApiAccount): { phoneNumberId: string; accessToken: string } {
   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 };
+}
 
-  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 },
-  };
-
+async function sendWithRetry(params: {
+  endpoint: string;
+  account: ResolvedWhatsAppApiAccount;
+  accessToken: string;
+  payload: Record<string, unknown>;
+}): Promise<string> {
   let lastErr: unknown = null;
-  const maxAttempts = Math.max(1, account.maxRetries + 1);
+  const maxAttempts = Math.max(1, params.account.maxRetries + 1);
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     try {
       const res = await withTimeout(
-        endpoint,
+        params.endpoint,
         {
           method: "POST",
           headers: {
-            authorization: `Bearer ${accessToken}`,
+            authorization: `Bearer ${params.accessToken}`,
             "content-type": "application/json",
           },
-          body: JSON.stringify(payload),
+          body: JSON.stringify(params.payload),
         },
-        account.requestTimeoutMs,
+        params.account.requestTimeoutMs,
       );
       const bodyText = await res.text();
       if (!res.ok) {
@@ -88,39 +97,294 @@ export async function sendWhatsAppApiText(params: WhatsAppApiSendTextParams): Pr
           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";
+        const retryAfterMs = readRetryAfterMs(res);
+        if (attempt < maxAttempts) {
+          await sleep(retryAfterMs ?? params.account.retryBackoffMs * attempt);
+        }
+        continue;
       }
+      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);
+      await sleep(params.account.retryBackoffMs * attempt);
       continue;
     }
+  }
+
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown outbound error"));
+}
 
-    if (attempt >= maxAttempts) {
-      break;
+async function uploadMediaFromLocalPath(params: {
+  endpoint: string;
+  account: ResolvedWhatsAppApiAccount;
+  accessToken: string;
+  localPath: string;
+  kind: "image" | "video" | "audio" | "document";
+}): Promise<{ id: string; mimeType?: string }> {
+  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: unknown = 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(
+        uploadEndpoint,
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${params.accessToken}`,
+          },
+          body: form,
+        },
+        params.account.requestTimeoutMs,
+      );
+      const bodyText = await res.text();
+      if (!res.ok) {
+        const err = new Error(`Meta media upload failed: HTTP ${res.status} ${bodyText}`);
+        if (!isRetryableStatus(res.status)) {
+          throw err;
+        }
+        lastErr = err;
+      } else {
+        const parsed = JSON.parse(bodyText) as { id?: string };
+        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(params.account.retryBackoffMs * attempt);
     }
-    await sleep(account.retryBackoffMs * attempt);
   }
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown media upload error"));
+}
 
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr ?? "Unknown outbound error"));
+function isLocalMediaPath(value: string): boolean {
+  return value.startsWith("/") || value.toLowerCase().startsWith("file://");
+}
+
+function toLocalPath(value: string): string {
+  if (value.toLowerCase().startsWith("file://")) {
+    return decodeURIComponent(value.replace(/^file:\/\//i, ""));
+  }
+  return value;
+}
+
+async function sendWhatsAppApiMedia(params: {
+  to: string;
+  text?: string;
+  mediaUrl: string;
+  account: ResolvedWhatsAppApiAccount;
+}): Promise<string> {
+  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: Record<string, unknown>;
+  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: {
+  to: string;
+  location: {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+  };
+  account: ResolvedWhatsAppApiAccount;
+}): Promise<string> {
+  const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
+  const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
+  return await sendWithRetry({
+    endpoint,
+    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: {
+  to: string;
+  contacts: Array<{
+    name: {
+      formatted_name: string;
+      first_name?: string;
+      last_name?: string;
+    };
+    phones?: Array<{
+      phone: string;
+      type?: string;
+      wa_id?: string;
+    }>;
+  }>;
+  account: ResolvedWhatsAppApiAccount;
+}): Promise<string> {
+  const { phoneNumberId, accessToken } = resolveGraphAuth(params.account);
+  const endpoint = `https://graph.facebook.com/${params.account.outboundApiVersion}/${phoneNumberId}/messages`;
+  return await sendWithRetry({
+    endpoint,
+    account: params.account,
+    accessToken,
+    payload: {
+      messaging_product: "whatsapp",
+      to: normalizeRecipient(params.to),
+      type: "contacts",
+      contacts: params.contacts,
+    },
+  });
+}
+
+export async function sendWhatsAppApiText(params: WhatsAppApiSendTextParams): Promise<string> {
+  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,
+  });
 }
 
 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 normalizeOutboundPayload(payload).text;
+}
+
+export async function sendWhatsAppApiReplyPayload(params: {
+  to: string;
+  payload: unknown;
+  account: ResolvedWhatsAppApiAccount;
+}): Promise<string[]> {
+  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: string[] = [];
+  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 : undefined,
+      account: params.account,
+    });
+    sentIds.push(messageId);
+  }
+
+  if (normalized.location) {
+    sentIds.push(
+      await sendWhatsAppApiLocation({
+        to: params.to,
+        location: normalized.location,
+        account: params.account,
+      }),
+    );
   }
-  return "";
+
+  if (normalized.contacts.length > 0) {
+    sentIds.push(
+      await sendWhatsAppApiContacts({
+        to: params.to,
+        contacts: normalized.contacts,
+        account: params.account,
+      }),
+    );
+  }
+
+  return sentIds;
 }

package/src/types.ts

@@ -3,6 +3,7 @@ export type ResolvedWhatsAppApiAccount = {
   enabled: boolean;
   webhookPath: string;
   inboundSharedSecret?: string;
+  inboundAccessToken?: string;
   outboundPhoneNumberId?: string;
   outboundAccessToken?: string;
   outboundApiVersion: string;
@@ -11,6 +12,29 @@ export type ResolvedWhatsAppApiAccount = {
   retryBackoffMs: number;
   dedupeTtlMs: number;
   maxBodyBytes: number;
+  mediaMaxBytes: number;
+  mediaRequestTimeoutMs: number;
+  mediaTempDir?: string;
+};
+
+export type WhatsAppApiInboundMedia = {
+  id: string;
+  kind: "image" | "video" | "audio" | "document" | "sticker";
+  mimeType?: string;
+  fileName?: string;
+};
+
+export type WhatsAppApiInboundLocation = {
+  latitude: number;
+  longitude: number;
+  name?: string;
+  address?: string;
+  url?: string;
+};
+
+export type WhatsAppApiInboundContact = {
+  name?: string;
+  phones: string[];
 };
 
 export type WhatsAppApiInboundMessage = {
@@ -23,6 +47,11 @@ export type WhatsAppApiInboundMessage = {
   timestamp?: number;
   senderName?: string;
   replyToId?: string;
+  replyToBody?: string;
+  replyToSender?: string;
+  media?: WhatsAppApiInboundMedia;
+  location?: WhatsAppApiInboundLocation;
+  contacts?: WhatsAppApiInboundContact[];
 };
 
 export type WhatsAppApiSendTextParams = {

package/src/utils/common.ts

@@ -0,0 +1,19 @@
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+export function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+export function asTrimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+

package/src/utils/media/inbound.ts

@@ -0,0 +1,164 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import type { ResolvedWhatsAppApiAccount, WhatsAppApiInboundMessage } from "../../types.js";
+import { asRecord } from "../common.js";
+import { extensionFromMime } from "./mime.js";
+
+type LogLike = {
+  warn?: (message: string) => void;
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+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);
+  }
+}
+
+async function fetchWithRetry(params: {
+  account: ResolvedWhatsAppApiAccount;
+  url: string;
+  init: RequestInit;
+}): Promise<Response> {
+  const maxAttempts = Math.max(1, params.account.maxRetries + 1);
+  let lastErr: unknown = 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 = 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: ResolvedWhatsAppApiAccount): string {
+  const token = account.inboundAccessToken?.trim() ?? account.outboundAccessToken?.trim();
+  if (!token) {
+    throw new Error("Missing inboundAccessToken/outboundAccessToken for media download");
+  }
+  return token;
+}
+
+function resolveMediaStorageDir(account: ResolvedWhatsAppApiAccount): string {
+  const root = account.mediaTempDir?.trim() || path.join(tmpdir(), "openclaw-whatsapp-api-media");
+  return path.join(root, account.accountId);
+}
+
+function sanitizeFileName(base: string): string {
+  return base.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+export async function downloadInboundMediaAttachment(params: {
+  account: ResolvedWhatsAppApiAccount;
+  message: WhatsAppApiInboundMessage;
+  log?: LogLike;
+}): Promise<{ mediaPath?: string; mediaType?: string }> {
+  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: Response;
+    try {
+      mediaInfoRes = await fetchWithRetry({
+        account: params.account,
+        url: mediaInfoEndpoint,
+        init: {
+          method: "GET",
+          headers: {
+            authorization: `Bearer ${token}`,
+          },
+        },
+      });
+    } catch (err) {
+      params.log?.warn?.(`[whatsapp-api] media metadata fetch failed for mediaId=${media.id}: ${String(err)}`);
+      return {};
+    }
+
+    const metaRaw = (await mediaInfoRes.json()) as unknown;
+    const meta = asRecord(metaRaw);
+    const mediaUrl = typeof meta?.url === "string" ? meta.url.trim() : "";
+    if (!mediaUrl) {
+      params.log?.warn?.(`[whatsapp-api] media metadata missing URL for mediaId=${media.id}`);
+      return {};
+    }
+    const mediaType =
+      (typeof meta?.mime_type === "string" && meta.mime_type.trim()) || media.mimeType || undefined;
+
+    let mediaRes: Response;
+    try {
+      mediaRes = await fetchWithRetry({
+        account: params.account,
+        url: mediaUrl,
+        init: {
+          method: "GET",
+          headers: {
+            authorization: `Bearer ${token}`,
+          },
+        },
+      });
+    } catch (err) {
+      params.log?.warn?.(`[whatsapp-api] media download failed for mediaId=${media.id}: ${String(err)}`);
+      return {};
+    }
+
+    const bytes = new Uint8Array(await mediaRes.arrayBuffer());
+    if (bytes.byteLength > params.account.mediaMaxBytes) {
+      params.log?.warn?.(
+        `[whatsapp-api] media too large for mediaId=${media.id}: ${bytes.byteLength} > ${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) {
+    params.log?.warn?.(
+      `[whatsapp-api] media attachment resolution failed for messageId=${params.message.messageId}: ${String(err)}`,
+    );
+    return {};
+  }
+}

package/src/utils/media/mime.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+
+const MIME_BY_EXT: Record<string, string> = {
+  ".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?: string): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed.split(";")[0]?.trim().toLowerCase();
+}
+
+export function mediaKindFromMimeOrName(params: {
+  mimeType?: string;
+  fileNameOrUrl?: string;
+}): "image" | "video" | "audio" | "document" {
+  const mime = normalizeMime(params.mimeType);
+  if (mime?.startsWith("image/")) {
+    return "image";
+  }
+  if (mime?.startsWith("video/")) {
+    return "video";
+  }
+  if (mime?.startsWith("audio/")) {
+    return "audio";
+  }
+
+  const ext = path.extname(params.fileNameOrUrl ?? "").toLowerCase();
+  const extMime = MIME_BY_EXT[ext];
+  if (extMime?.startsWith("image/")) {
+    return "image";
+  }
+  if (extMime?.startsWith("video/")) {
+    return "video";
+  }
+  if (extMime?.startsWith("audio/")) {
+    return "audio";
+  }
+  return "document";
+}
+
+export function mimeFromFileName(fileNameOrPath: string): string | undefined {
+  const ext = path.extname(fileNameOrPath).toLowerCase();
+  return MIME_BY_EXT[ext];
+}
+
+export function extensionFromMime(mimeType?: string): string {
+  const mime = normalizeMime(mimeType);
+  if (!mime) {
+    return ".bin";
+  }
+  const found = Object.entries(MIME_BY_EXT).find(([, value]) => value === mime)?.[0];
+  return found ?? ".bin";
+}
+

package/src/utils/outbound/payload.ts

@@ -0,0 +1,173 @@
+export type NormalizedOutboundPayload = {
+  text: string;
+  mediaUrls: string[];
+  location?: {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+  };
+  contacts: Array<{
+    name: {
+      formatted_name: string;
+      first_name?: string;
+      last_name?: string;
+    };
+    phones?: Array<{
+      phone: string;
+      type?: string;
+      wa_id?: string;
+    }>;
+  }>;
+};
+
+function toTrimmedString(value: unknown): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+  return value.trim();
+}
+
+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 parseNumber(value: unknown): number | undefined {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : undefined;
+}
+
+function getWhatsAppPayload(record: Record<string, unknown>): Record<string, unknown> {
+  const whatsapp = asRecord(record.whatsapp) ?? {};
+  const channelData = asRecord(record.channelData) ?? {};
+  const channelDataWhatsapp = asRecord(channelData.whatsapp) ?? {};
+  return {
+    ...channelDataWhatsapp,
+    ...whatsapp,
+  };
+}
+
+function normalizeOutboundLocation(record: Record<string, unknown>): NormalizedOutboundPayload["location"] {
+  const whatsapp = getWhatsAppPayload(record);
+  const raw = asRecord(record.location) ?? asRecord(whatsapp.location);
+  if (!raw) {
+    return undefined;
+  }
+  const latitude = parseNumber(raw.latitude ?? raw.lat);
+  const longitude = parseNumber(raw.longitude ?? raw.lng ?? raw.lon);
+  if (latitude === undefined || longitude === undefined) {
+    return undefined;
+  }
+  return {
+    latitude,
+    longitude,
+    name: toTrimmedString(raw.name || raw.title) || undefined,
+    address: toTrimmedString(raw.address) || undefined,
+  };
+}
+
+function normalizeSingleContact(value: unknown): NormalizedOutboundPayload["contacts"][number] | undefined {
+  const raw = asRecord(value);
+  if (!raw) {
+    return undefined;
+  }
+  const nameRecord = asRecord(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 undefined;
+  }
+  const phones = new Set<string>();
+  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 phoneRecord = asRecord(rawPhone);
+    const cleaned = toTrimmedString(phoneRecord?.phone);
+    if (cleaned) {
+      phones.add(cleaned);
+    }
+  }
+  return {
+    name: {
+      formatted_name: formattedName,
+      first_name: firstName || undefined,
+      last_name: lastName || undefined,
+    },
+    phones:
+      phones.size > 0
+        ? [...phones].map((phone) => ({
+            phone,
+          }))
+        : undefined,
+  };
+}
+
+function normalizeOutboundContacts(record: Record<string, unknown>): NormalizedOutboundPayload["contacts"] {
+  const whatsapp = getWhatsAppPayload(record);
+  const rawContacts =
+    (Array.isArray(record.contacts) && record.contacts) ||
+    (Array.isArray(whatsapp.contacts) && whatsapp.contacts) ||
+    [];
+  const contacts: NormalizedOutboundPayload["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;
+}
+
+export function normalizeOutboundPayload(payload: unknown): NormalizedOutboundPayload {
+  if (!payload || typeof payload !== "object") {
+    return { text: "", mediaUrls: [], contacts: [] };
+  }
+  const record = payload as Record<string, unknown>;
+  const text = toTrimmedString(record.text) || toTrimmedString(record.body);
+
+  const mediaUrls = new Set<string>();
+  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),
+  };
+}
+