openclaw-threema 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.6.6 (2026-05-04)
+
+### Added
+- **Idempotency Cache for Webhook Replay Protection**: Implements replay-attack protection against Threema webhook retries.
+  - New message-ID deduplication mechanism with configurable TTL (24h) and cache size (500 entries max).
+  - Automatic pruning of expired entries during check.
+  - Disk persistence via `~/.openclaw/extensions/threema/.idempotency-cache/messageids.json` to survive plugin reloads.
+  - Throttled writes (max 1 per 5 seconds) to prevent excessive I/O.
+  - Prevents duplicate processing when Threema Gateway retries a failed webhook delivery.
+  - Solves the issue where Plugin reloads during `npm publish` + temporary 5xx errors could cause the same message to be processed twice.
+
+## 0.6.5 (2026-05-04)
+
+### Added
+- **Voice-Reply Function**: Threema plugin now supports sending voice notes (audio messages).
+  - New `sendVoiceNote(toId, audioBuffer, mimeType, caption)` method on ThreemaClient for E2E encrypted voice messages.
+  - When agent reply contains `audioAsVoice: true` with a `mediaUrl` (e.g., TTS or Whisper output), the plugin automatically sends it as a voice message instead of text.
+  - Audio detection works in both text-inbound and file-inbound reply pipelines.
+  - Fallback to text mode when audio file not found or when E2E mode is disabled (voice notes require E2E).
+  - Supports multiple audio MIME types: audio/aac, audio/mpeg, audio/wav, audio/ogg, audio/m4a, audio/webm.
+  - Error handling: logs errors and gracefully falls back to text delivery if voice send fails.
+
 ## 0.6.4 (2026-05-04)
 
 ### Fixed

package/dist/index.js

@@ -157,10 +157,12 @@ function composeBodyForAgent(userText, cfg) {
 }
 // Allowed base directory for local media files (exfiltration protection)
 const MEDIA_ALLOWED_BASE = path.join(process.env.HOME || "/tmp", ".openclaw", "media");
+// Extension state directory for persistent caches
+const EXTENSION_STATE_DIR = path.join(process.env.HOME || "/tmp", ".openclaw", "extensions", "threema");
 // Message-ID dedup cache (replay protection): messageId -> timestamp
 const seenMsgIds = new Map();
-const MSG_ID_TTL_MS = 15 * 60 * 1000; // 15 minutes
-const MSG_ID_CACHE_MAX = 5000;
+const MSG_ID_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const MSG_ID_CACHE_MAX = 500;
 // Audio MIME types that should be transcribed
 const AUDIO_MIME_TYPES = [
     "audio/aac",
@@ -327,6 +329,79 @@ class ThreemaClient {
         const decrypted = nacl.secretbox.open(encryptedBlob, nonce, key);
         return decrypted || null;
     }
+    /**
+     * Send a voice note message (audio file with voice message rendering type).
+     * Type 0x17 file message with j=1 (media rendering) and audio MIME type.
+     * Suitable for Whisper transcriptions or agent-generated TTS audio.
+     */
+    async sendVoiceNote(to, audioBuffer, mimeType = "audio/aac", caption) {
+        if (!this.privateKey) {
+            throw new Error("E2E mode requires privateKey configuration");
+        }
+        const recipientPubKey = await this.getPublicKey(to);
+        // Generate random symmetric key for file encryption
+        const fileKey = nacl.randomBytes(32);
+        // Threema FILE_NONCE: 23 zero bytes + 0x01
+        const fileNonce = new Uint8Array(24);
+        fileNonce[23] = 0x01;
+        // Encrypt the audio with secretbox
+        const encryptedAudio = nacl.secretbox(new Uint8Array(audioBuffer), fileNonce, fileKey);
+        // Upload encrypted blob
+        const blobId = await this.uploadBlob(encryptedAudio);
+        // Create file message JSON for voice note
+        // j=1 marks it as media (voice message bubble in UI)
+        const fileMsg = {
+            b: blobId,
+            k: bytesToHex(fileKey),
+            m: mimeType,
+            n: `voice.${this.getMimeExtension(mimeType)}`,
+            s: audioBuffer.length,
+            j: 1, // 1 = render as media (voice message bubble)
+            i: 1, // deprecated but needed for older clients
+        };
+        if (caption) {
+            fileMsg.d = caption;
+        }
+        const fileMsgJson = JSON.stringify(fileMsg);
+        const fileMsgBytes = decodeUTF8(fileMsgJson);
+        // Create E2E payload (type 0x17 = file message)
+        const payload = buildE2EPayload(0x17, fileMsgBytes);
+        // Generate nonce and encrypt with NaCl box
+        const nonce = nacl.randomBytes(24);
+        const box = nacl.box(payload, nonce, recipientPubKey, this.privateKey);
+        const params = new URLSearchParams({
+            from: this.gatewayId,
+            to,
+            nonce: bytesToHex(nonce),
+            box: bytesToHex(box),
+            secret: this.secretKey,
+        });
+        const url = `${THREEMA_API_BASE}/send_e2e`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        if (!res.ok) {
+            // Don't log response body (may contain secrets)
+            throw new Error(`Threema E2E API error ${res.status}`);
+        }
+        return res.text();
+    }
+    /**
+     * Get file extension for MIME type
+     */
+    getMimeExtension(mimeType) {
+        const mimeMap = {
+            "audio/aac": "aac",
+            "audio/mpeg": "mp3",
+            "audio/wav": "wav",
+            "audio/ogg": "ogg",
+            "audio/m4a": "m4a",
+            "audio/webm": "webm",
+        };
+        return mimeMap[mimeType.toLowerCase()] || "m4a";
+    }
     /**
      * Send a text message (Basic mode - server-side encryption)
      */
@@ -481,15 +556,85 @@ function buildE2EPayload(type, inner) {
  * Check if a message ID has been seen recently (replay protection)
  * Returns true if duplicate (should be ignored)
  */
+// Idempotency cache directory
+const CACHE_DIR = path.join(EXTENSION_STATE_DIR, ".idempotency-cache");
+const CACHE_FILE = path.join(CACHE_DIR, "messageids.json");
+let lastCacheSave = 0;
+const CACHE_SAVE_THROTTLE_MS = 5000; // Max 1 write per 5 sec
+/**
+ * Load idempotency cache from disk if available and fresh
+ */
+function loadIdempotencyCache() {
+    try {
+        if (!fs.existsSync(CACHE_FILE))
+            return;
+        const data = fs.readFileSync(CACHE_FILE, "utf-8");
+        const parsed = JSON.parse(data);
+        if (!parsed || typeof parsed !== "object")
+            return;
+        const now = Date.now();
+        for (const [id, ts] of Object.entries(parsed)) {
+            const timestamp = Number(ts);
+            // Only load entries that are still within TTL
+            if (!isNaN(timestamp) && now - timestamp < MSG_ID_TTL_MS) {
+                seenMsgIds.set(id, timestamp);
+            }
+        }
+    }
+    catch (err) {
+        // Silently skip if cache file is corrupted or unreadable
+        // Next write will overwrite it
+    }
+}
+/**
+ * Save idempotency cache to disk (throttled)
+ */
+function saveIdempotencyCache() {
+    const now = Date.now();
+    if (now - lastCacheSave < CACHE_SAVE_THROTTLE_MS) {
+        return; // Skip this write, within throttle window
+    }
+    lastCacheSave = now;
+    try {
+        if (!fs.existsSync(CACHE_DIR)) {
+            fs.mkdirSync(CACHE_DIR, { recursive: true });
+        }
+        const obj = {};
+        for (const [id, ts] of seenMsgIds) {
+            obj[id] = ts;
+        }
+        fs.writeFileSync(CACHE_FILE, JSON.stringify(obj, null, 2), "utf-8");
+    }
+    catch (err) {
+        // Silently skip if write fails; in-memory cache is still valid
+    }
+}
+/**
+ * Check if message has been seen before (idempotency check)
+ * Returns true if duplicate (should skip), false if new (should process)
+ */
 function isDuplicateMsgId(messageId) {
     const now = Date.now();
-    // Cleanup old entries if cache is too large
-    if (seenMsgIds.size > MSG_ID_CACHE_MAX) {
+    // Prune entries older than TTL
+    for (const [id, ts] of seenMsgIds) {
+        if (now - ts > MSG_ID_TTL_MS) {
+            seenMsgIds.delete(id);
+        }
+    }
+    // If cache is still too large, evict oldest entries
+    if (seenMsgIds.size >= MSG_ID_CACHE_MAX) {
+        // Find and remove the oldest entry
+        let oldest = messageId;
+        let oldestTs = now;
         for (const [id, ts] of seenMsgIds) {
-            if (now - ts > MSG_ID_TTL_MS) {
-                seenMsgIds.delete(id);
+            if (ts < oldestTs) {
+                oldest = id;
+                oldestTs = ts;
             }
         }
+        if (oldest !== messageId) {
+            seenMsgIds.delete(oldest);
+        }
     }
     // Check if seen
     const seenAt = seenMsgIds.get(messageId);
@@ -498,6 +643,7 @@ function isDuplicateMsgId(messageId) {
     }
     // Mark as seen
     seenMsgIds.set(messageId, now);
+    saveIdempotencyCache(); // Throttled write
     return false;
 }
 /**
@@ -1369,10 +1515,13 @@ const threemaChannel = {
 // ============================================================================
 export const id = "threema";
 export const name = "Threema Gateway";
-export const version = "0.6.0";
+export const version = "0.6.6";
 export const description = "Threema messaging channel via Threema Gateway API (E2E encrypted, with media support)";
 export default function register(api) {
     try {
+        // Load idempotency cache from disk (if available)
+        loadIdempotencyCache();
+        api.logger?.debug?.("Threema: idempotency cache loaded from disk");
         const config = api.config;
         const threemaCfg = getThreemaConfig(config);
         const runtime = api.runtime;
@@ -1554,40 +1703,89 @@ export default function register(api) {
                                     cfg: currentCfg,
                                     dispatcherOptions: {
                                         deliver: async (payload) => {
-                                            const text = payload.text ?? payload.body;
-                                            if (!text)
-                                                return;
-                                            // Chunk long replies if needed
-                                            const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
-                                            if (text.length <= limit) {
-                                                if (replyClient.isE2EEnabled) {
-                                                    await replyClient.sendE2E(from, text);
+                                            // Check if reply contains audio that should be sent as voice note
+                                            const isAudioAsVoice = payload.audioAsVoice === true && payload.mediaUrl;
+                                            if (isAudioAsVoice && payload.mediaUrl) {
+                                                // Send as voice note
+                                                try {
+                                                    if (replyClient.isE2EEnabled) {
+                                                        // Load audio from mediaUrl and send via sendVoiceNote
+                                                        const audioPath = payload.mediaUrl;
+                                                        if (fs.existsSync(audioPath)) {
+                                                            const audioBuffer = fs.readFileSync(audioPath);
+                                                            const mimeType = payload.mediaMimeType ?? "audio/aac";
+                                                            const caption = payload.text ?? payload.body ?? undefined;
+                                                            await replyClient.sendVoiceNote(from, audioBuffer, mimeType, caption);
+                                                        }
+                                                        else {
+                                                            api.logger?.warn?.(`Threema: audio file not found at ${audioPath}, falling back to text`);
+                                                            // Fallback to text if audio file not found
+                                                            const text = payload.text ?? payload.body;
+                                                            if (text) {
+                                                                await replyClient.sendE2E(from, text);
+                                                            }
+                                                        }
+                                                    }
+                                                    else {
+                                                        // Voice notes only work in E2E mode; fallback to text in basic mode
+                                                        api.logger?.info?.(`Threema: voice notes require E2E mode, sending text instead`);
+                                                        const text = payload.text ?? payload.body;
+                                                        if (text) {
+                                                            await replyClient.sendSimple(from, text);
+                                                        }
+                                                    }
                                                 }
-                                                else {
-                                                    await replyClient.sendSimple(from, text);
+                                                catch (audioErr) {
+                                                    api.logger?.error?.(`Threema: error sending voice note: ${audioErr.message}`);
+                                                    // Fallback to text on error
+                                                    const text = payload.text ?? payload.body;
+                                                    if (text) {
+                                                        if (replyClient.isE2EEnabled) {
+                                                            await replyClient.sendE2E(from, text);
+                                                        }
+                                                        else {
+                                                            await replyClient.sendSimple(from, text);
+                                                        }
+                                                    }
                                                 }
                                             }
                                             else {
-                                                // Split into chunks at newline boundaries
-                                                const chunks = [];
-                                                let remaining = text;
-                                                while (remaining.length > 0) {
-                                                    if (remaining.length <= limit) {
-                                                        chunks.push(remaining);
-                                                        break;
-                                                    }
-                                                    let splitIdx = remaining.lastIndexOf("\n", limit);
-                                                    if (splitIdx <= 0)
-                                                        splitIdx = limit;
-                                                    chunks.push(remaining.slice(0, splitIdx));
-                                                    remaining = remaining.slice(splitIdx).replace(/^\n/, "");
-                                                }
-                                                for (const chunk of chunks) {
+                                                // Send as text (existing logic)
+                                                const text = payload.text ?? payload.body;
+                                                if (!text)
+                                                    return;
+                                                // Chunk long replies if needed
+                                                const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
+                                                if (text.length <= limit) {
                                                     if (replyClient.isE2EEnabled) {
-                                                        await replyClient.sendE2E(from, chunk);
+                                                        await replyClient.sendE2E(from, text);
                                                     }
                                                     else {
-                                                        await replyClient.sendSimple(from, chunk);
+                                                        await replyClient.sendSimple(from, text);
+                                                    }
+                                                }
+                                                else {
+                                                    // Split into chunks at newline boundaries
+                                                    const chunks = [];
+                                                    let remaining = text;
+                                                    while (remaining.length > 0) {
+                                                        if (remaining.length <= limit) {
+                                                            chunks.push(remaining);
+                                                            break;
+                                                        }
+                                                        let splitIdx = remaining.lastIndexOf("\n", limit);
+                                                        if (splitIdx <= 0)
+                                                            splitIdx = limit;
+                                                        chunks.push(remaining.slice(0, splitIdx));
+                                                        remaining = remaining.slice(splitIdx).replace(/^\n/, "");
+                                                    }
+                                                    for (const chunk of chunks) {
+                                                        if (replyClient.isE2EEnabled) {
+                                                            await replyClient.sendE2E(from, chunk);
+                                                        }
+                                                        else {
+                                                            await replyClient.sendSimple(from, chunk);
+                                                        }
                                                     }
                                                 }
                                             }
@@ -1730,38 +1928,87 @@ export default function register(api) {
                                     cfg: currentCfg,
                                     dispatcherOptions: {
                                         deliver: async (payload) => {
-                                            const text = payload.text ?? payload.body;
-                                            if (!text)
-                                                return;
-                                            const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
-                                            if (text.length <= limit) {
-                                                if (replyClient.isE2EEnabled) {
-                                                    await replyClient.sendE2E(from, text);
+                                            // Check if reply contains audio that should be sent as voice note
+                                            const isAudioAsVoice = payload.audioAsVoice === true && payload.mediaUrl;
+                                            if (isAudioAsVoice && payload.mediaUrl) {
+                                                // Send as voice note
+                                                try {
+                                                    if (replyClient.isE2EEnabled) {
+                                                        // Load audio from mediaUrl and send via sendVoiceNote
+                                                        const audioPath = payload.mediaUrl;
+                                                        if (fs.existsSync(audioPath)) {
+                                                            const audioBuffer = fs.readFileSync(audioPath);
+                                                            const mimeType = payload.mediaMimeType ?? "audio/aac";
+                                                            const caption = payload.text ?? payload.body ?? undefined;
+                                                            await replyClient.sendVoiceNote(from, audioBuffer, mimeType, caption);
+                                                        }
+                                                        else {
+                                                            api.logger?.warn?.(`Threema: audio file not found at ${audioPath}, falling back to text`);
+                                                            // Fallback to text if audio file not found
+                                                            const text = payload.text ?? payload.body;
+                                                            if (text) {
+                                                                await replyClient.sendE2E(from, text);
+                                                            }
+                                                        }
+                                                    }
+                                                    else {
+                                                        // Voice notes only work in E2E mode; fallback to text in basic mode
+                                                        api.logger?.info?.(`Threema: voice notes require E2E mode, sending text instead`);
+                                                        const text = payload.text ?? payload.body;
+                                                        if (text) {
+                                                            await replyClient.sendSimple(from, text);
+                                                        }
+                                                    }
                                                 }
-                                                else {
-                                                    await replyClient.sendSimple(from, text);
+                                                catch (audioErr) {
+                                                    api.logger?.error?.(`Threema: error sending voice note: ${audioErr.message}`);
+                                                    // Fallback to text on error
+                                                    const text = payload.text ?? payload.body;
+                                                    if (text) {
+                                                        if (replyClient.isE2EEnabled) {
+                                                            await replyClient.sendE2E(from, text);
+                                                        }
+                                                        else {
+                                                            await replyClient.sendSimple(from, text);
+                                                        }
+                                                    }
                                                 }
                                             }
                                             else {
-                                                const chunks = [];
-                                                let remaining = text;
-                                                while (remaining.length > 0) {
-                                                    if (remaining.length <= limit) {
-                                                        chunks.push(remaining);
-                                                        break;
-                                                    }
-                                                    let splitIdx = remaining.lastIndexOf("\n", limit);
-                                                    if (splitIdx <= 0)
-                                                        splitIdx = limit;
-                                                    chunks.push(remaining.slice(0, splitIdx));
-                                                    remaining = remaining.slice(splitIdx).replace(/^\n/, "");
-                                                }
-                                                for (const chunk of chunks) {
+                                                // Send as text (existing logic)
+                                                const text = payload.text ?? payload.body;
+                                                if (!text)
+                                                    return;
+                                                const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
+                                                if (text.length <= limit) {
                                                     if (replyClient.isE2EEnabled) {
-                                                        await replyClient.sendE2E(from, chunk);
+                                                        await replyClient.sendE2E(from, text);
                                                     }
                                                     else {
-                                                        await replyClient.sendSimple(from, chunk);
+                                                        await replyClient.sendSimple(from, text);
+                                                    }
+                                                }
+                                                else {
+                                                    const chunks = [];
+                                                    let remaining = text;
+                                                    while (remaining.length > 0) {
+                                                        if (remaining.length <= limit) {
+                                                            chunks.push(remaining);
+                                                            break;
+                                                        }
+                                                        let splitIdx = remaining.lastIndexOf("\n", limit);
+                                                        if (splitIdx <= 0)
+                                                            splitIdx = limit;
+                                                        chunks.push(remaining.slice(0, splitIdx));
+                                                        remaining = remaining.slice(splitIdx).replace(/^\n/, "");
+                                                    }
+                                                    for (const chunk of chunks) {
+                                                        if (replyClient.isE2EEnabled) {
+                                                            await replyClient.sendE2E(from, chunk);
+                                                        }
+                                                        else {
+                                                            await replyClient.sendSimple(from, chunk);
+                                                        }
                                                     }
                                                 }
                                             }

package/index.ts

@@ -311,10 +311,18 @@ const MEDIA_ALLOWED_BASE = path.join(
   "media"
 );
 
+// Extension state directory for persistent caches
+const EXTENSION_STATE_DIR = path.join(
+  process.env.HOME || "/tmp",
+  ".openclaw",
+  "extensions",
+  "threema"
+);
+
 // Message-ID dedup cache (replay protection): messageId -> timestamp
 const seenMsgIds = new Map<string, number>();
-const MSG_ID_TTL_MS = 15 * 60 * 1000; // 15 minutes
-const MSG_ID_CACHE_MAX = 5000;
+const MSG_ID_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const MSG_ID_CACHE_MAX = 500;
 
 // Audio MIME types that should be transcribed
 const AUDIO_MIME_TYPES = [
@@ -525,6 +533,98 @@ class ThreemaClient {
     return decrypted || null;
   }
 
+  /**
+   * Send a voice note message (audio file with voice message rendering type).
+   * Type 0x17 file message with j=1 (media rendering) and audio MIME type.
+   * Suitable for Whisper transcriptions or agent-generated TTS audio.
+   */
+  async sendVoiceNote(
+    to: string,
+    audioBuffer: Buffer,
+    mimeType: string = "audio/aac",
+    caption?: string
+  ): Promise<string> {
+    if (!this.privateKey) {
+      throw new Error("E2E mode requires privateKey configuration");
+    }
+
+    const recipientPubKey = await this.getPublicKey(to);
+
+    // Generate random symmetric key for file encryption
+    const fileKey = nacl.randomBytes(32);
+    // Threema FILE_NONCE: 23 zero bytes + 0x01
+    const fileNonce = new Uint8Array(24);
+    fileNonce[23] = 0x01;
+
+    // Encrypt the audio with secretbox
+    const encryptedAudio = nacl.secretbox(new Uint8Array(audioBuffer), fileNonce, fileKey);
+
+    // Upload encrypted blob
+    const blobId = await this.uploadBlob(encryptedAudio);
+
+    // Create file message JSON for voice note
+    // j=1 marks it as media (voice message bubble in UI)
+    const fileMsg: ThreemaFileMessage = {
+      b: blobId,
+      k: bytesToHex(fileKey),
+      m: mimeType,
+      n: `voice.${this.getMimeExtension(mimeType)}`,
+      s: audioBuffer.length,
+      j: 1,  // 1 = render as media (voice message bubble)
+      i: 1,  // deprecated but needed for older clients
+    };
+    if (caption) {
+      fileMsg.d = caption;
+    }
+
+    const fileMsgJson = JSON.stringify(fileMsg);
+    const fileMsgBytes = decodeUTF8(fileMsgJson);
+
+    // Create E2E payload (type 0x17 = file message)
+    const payload = buildE2EPayload(0x17, fileMsgBytes);
+
+    // Generate nonce and encrypt with NaCl box
+    const nonce = nacl.randomBytes(24);
+    const box = nacl.box(payload, nonce, recipientPubKey, this.privateKey);
+
+    const params = new URLSearchParams({
+      from: this.gatewayId,
+      to,
+      nonce: bytesToHex(nonce),
+      box: bytesToHex(box),
+      secret: this.secretKey,
+    });
+
+    const url = `${THREEMA_API_BASE}/send_e2e`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+
+    if (!res.ok) {
+      // Don't log response body (may contain secrets)
+      throw new Error(`Threema E2E API error ${res.status}`);
+    }
+
+    return res.text();
+  }
+
+  /**
+   * Get file extension for MIME type
+   */
+  private getMimeExtension(mimeType: string): string {
+    const mimeMap: Record<string, string> = {
+      "audio/aac": "aac",
+      "audio/mpeg": "mp3",
+      "audio/wav": "wav",
+      "audio/ogg": "ogg",
+      "audio/m4a": "m4a",
+      "audio/webm": "webm",
+    };
+    return mimeMap[mimeType.toLowerCase()] || "m4a";
+  }
+
   /**
    * Send a text message (Basic mode - server-side encryption)
    */
@@ -718,16 +818,89 @@ function buildE2EPayload(type: number, inner: Uint8Array): Uint8Array {
  * Check if a message ID has been seen recently (replay protection)
  * Returns true if duplicate (should be ignored)
  */
+// Idempotency cache directory
+const CACHE_DIR = path.join(EXTENSION_STATE_DIR, ".idempotency-cache");
+const CACHE_FILE = path.join(CACHE_DIR, "messageids.json");
+let lastCacheSave = 0;
+const CACHE_SAVE_THROTTLE_MS = 5000; // Max 1 write per 5 sec
+
+/**
+ * Load idempotency cache from disk if available and fresh
+ */
+function loadIdempotencyCache(): void {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return;
+    
+    const data = fs.readFileSync(CACHE_FILE, "utf-8");
+    const parsed = JSON.parse(data);
+    if (!parsed || typeof parsed !== "object") return;
+    
+    const now = Date.now();
+    for (const [id, ts] of Object.entries(parsed)) {
+      const timestamp = Number(ts);
+      // Only load entries that are still within TTL
+      if (!isNaN(timestamp) && now - timestamp < MSG_ID_TTL_MS) {
+        seenMsgIds.set(id, timestamp);
+      }
+    }
+  } catch (err: any) {
+    // Silently skip if cache file is corrupted or unreadable
+    // Next write will overwrite it
+  }
+}
+
+/**
+ * Save idempotency cache to disk (throttled)
+ */
+function saveIdempotencyCache(): void {
+  const now = Date.now();
+  if (now - lastCacheSave < CACHE_SAVE_THROTTLE_MS) {
+    return; // Skip this write, within throttle window
+  }
+  lastCacheSave = now;
+  
+  try {
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+    const obj: Record<string, number> = {};
+    for (const [id, ts] of seenMsgIds) {
+      obj[id] = ts;
+    }
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(obj, null, 2), "utf-8");
+  } catch (err: any) {
+    // Silently skip if write fails; in-memory cache is still valid
+  }
+}
+
+/**
+ * Check if message has been seen before (idempotency check)
+ * Returns true if duplicate (should skip), false if new (should process)
+ */
 function isDuplicateMsgId(messageId: string): boolean {
   const now = Date.now();
   
-  // Cleanup old entries if cache is too large
-  if (seenMsgIds.size > MSG_ID_CACHE_MAX) {
+  // Prune entries older than TTL
+  for (const [id, ts] of seenMsgIds) {
+    if (now - ts > MSG_ID_TTL_MS) {
+      seenMsgIds.delete(id);
+    }
+  }
+  
+  // If cache is still too large, evict oldest entries
+  if (seenMsgIds.size >= MSG_ID_CACHE_MAX) {
+    // Find and remove the oldest entry
+    let oldest = messageId;
+    let oldestTs = now;
     for (const [id, ts] of seenMsgIds) {
-      if (now - ts > MSG_ID_TTL_MS) {
-        seenMsgIds.delete(id);
+      if (ts < oldestTs) {
+        oldest = id;
+        oldestTs = ts;
       }
     }
+    if (oldest !== messageId) {
+      seenMsgIds.delete(oldest);
+    }
   }
   
   // Check if seen
@@ -738,6 +911,7 @@ function isDuplicateMsgId(messageId: string): boolean {
   
   // Mark as seen
   seenMsgIds.set(messageId, now);
+  saveIdempotencyCache(); // Throttled write
   return false;
 }
 
@@ -1780,12 +1954,16 @@ const threemaChannel = {
 
 export const id = "threema";
 export const name = "Threema Gateway";
-export const version = "0.6.0";
+export const version = "0.6.6";
 export const description =
   "Threema messaging channel via Threema Gateway API (E2E encrypted, with media support)";
 
 export default function register(api: any) {
   try {
+    // Load idempotency cache from disk (if available)
+    loadIdempotencyCache();
+    api.logger?.debug?.("Threema: idempotency cache loaded from disk");
+
     const config = api.config as OpenClawConfig;
     const threemaCfg = getThreemaConfig(config);
     const runtime = api.runtime;
@@ -2000,35 +2178,80 @@ export default function register(api: any) {
                   cfg: currentCfg,
                   dispatcherOptions: {
                     deliver: async (payload: any) => {
-                      const text = payload.text ?? payload.body;
-                      if (!text) return;
-                      // Chunk long replies if needed
-                      const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
-                      if (text.length <= limit) {
-                        if (replyClient.isE2EEnabled) {
-                          await replyClient.sendE2E(from, text);
-                        } else {
-                          await replyClient.sendSimple(from, text);
-                        }
-                      } else {
-                        // Split into chunks at newline boundaries
-                        const chunks: string[] = [];
-                        let remaining = text;
-                        while (remaining.length > 0) {
-                          if (remaining.length <= limit) {
-                            chunks.push(remaining);
-                            break;
+                      // Check if reply contains audio that should be sent as voice note
+                      const isAudioAsVoice = payload.audioAsVoice === true && payload.mediaUrl;
+                      
+                      if (isAudioAsVoice && payload.mediaUrl) {
+                        // Send as voice note
+                        try {
+                          if (replyClient.isE2EEnabled) {
+                            // Load audio from mediaUrl and send via sendVoiceNote
+                            const audioPath = payload.mediaUrl;
+                            if (fs.existsSync(audioPath)) {
+                              const audioBuffer = fs.readFileSync(audioPath);
+                              const mimeType = payload.mediaMimeType ?? "audio/aac";
+                              const caption = payload.text ?? payload.body ?? undefined;
+                              await replyClient.sendVoiceNote(from, audioBuffer, mimeType, caption);
+                            } else {
+                              api.logger?.warn?.(`Threema: audio file not found at ${audioPath}, falling back to text`);
+                              // Fallback to text if audio file not found
+                              const text = payload.text ?? payload.body;
+                              if (text) {
+                                await replyClient.sendE2E(from, text);
+                              }
+                            }
+                          } else {
+                            // Voice notes only work in E2E mode; fallback to text in basic mode
+                            api.logger?.info?.(`Threema: voice notes require E2E mode, sending text instead`);
+                            const text = payload.text ?? payload.body;
+                            if (text) {
+                              await replyClient.sendSimple(from, text);
+                            }
+                          }
+                        } catch (audioErr: any) {
+                          api.logger?.error?.(`Threema: error sending voice note: ${audioErr.message}`);
+                          // Fallback to text on error
+                          const text = payload.text ?? payload.body;
+                          if (text) {
+                            if (replyClient.isE2EEnabled) {
+                              await replyClient.sendE2E(from, text);
+                            } else {
+                              await replyClient.sendSimple(from, text);
+                            }
                           }
-                          let splitIdx = remaining.lastIndexOf("\n", limit);
-                          if (splitIdx <= 0) splitIdx = limit;
-                          chunks.push(remaining.slice(0, splitIdx));
-                          remaining = remaining.slice(splitIdx).replace(/^\n/, "");
                         }
-                        for (const chunk of chunks) {
+                      } else {
+                        // Send as text (existing logic)
+                        const text = payload.text ?? payload.body;
+                        if (!text) return;
+                        // Chunk long replies if needed
+                        const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
+                        if (text.length <= limit) {
                           if (replyClient.isE2EEnabled) {
-                            await replyClient.sendE2E(from, chunk);
+                            await replyClient.sendE2E(from, text);
                           } else {
-                            await replyClient.sendSimple(from, chunk);
+                            await replyClient.sendSimple(from, text);
+                          }
+                        } else {
+                          // Split into chunks at newline boundaries
+                          const chunks: string[] = [];
+                          let remaining = text;
+                          while (remaining.length > 0) {
+                            if (remaining.length <= limit) {
+                              chunks.push(remaining);
+                              break;
+                            }
+                            let splitIdx = remaining.lastIndexOf("\n", limit);
+                            if (splitIdx <= 0) splitIdx = limit;
+                            chunks.push(remaining.slice(0, splitIdx));
+                            remaining = remaining.slice(splitIdx).replace(/^\n/, "");
+                          }
+                          for (const chunk of chunks) {
+                            if (replyClient.isE2EEnabled) {
+                              await replyClient.sendE2E(from, chunk);
+                            } else {
+                              await replyClient.sendSimple(from, chunk);
+                            }
                           }
                         }
                       }
@@ -2179,33 +2402,78 @@ export default function register(api: any) {
                   cfg: currentCfg,
                   dispatcherOptions: {
                     deliver: async (payload: any) => {
-                      const text = payload.text ?? payload.body;
-                      if (!text) return;
-                      const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
-                      if (text.length <= limit) {
-                        if (replyClient.isE2EEnabled) {
-                          await replyClient.sendE2E(from, text);
-                        } else {
-                          await replyClient.sendSimple(from, text);
-                        }
-                      } else {
-                        const chunks: string[] = [];
-                        let remaining = text;
-                        while (remaining.length > 0) {
-                          if (remaining.length <= limit) {
-                            chunks.push(remaining);
-                            break;
+                      // Check if reply contains audio that should be sent as voice note
+                      const isAudioAsVoice = payload.audioAsVoice === true && payload.mediaUrl;
+                      
+                      if (isAudioAsVoice && payload.mediaUrl) {
+                        // Send as voice note
+                        try {
+                          if (replyClient.isE2EEnabled) {
+                            // Load audio from mediaUrl and send via sendVoiceNote
+                            const audioPath = payload.mediaUrl;
+                            if (fs.existsSync(audioPath)) {
+                              const audioBuffer = fs.readFileSync(audioPath);
+                              const mimeType = payload.mediaMimeType ?? "audio/aac";
+                              const caption = payload.text ?? payload.body ?? undefined;
+                              await replyClient.sendVoiceNote(from, audioBuffer, mimeType, caption);
+                            } else {
+                              api.logger?.warn?.(`Threema: audio file not found at ${audioPath}, falling back to text`);
+                              // Fallback to text if audio file not found
+                              const text = payload.text ?? payload.body;
+                              if (text) {
+                                await replyClient.sendE2E(from, text);
+                              }
+                            }
+                          } else {
+                            // Voice notes only work in E2E mode; fallback to text in basic mode
+                            api.logger?.info?.(`Threema: voice notes require E2E mode, sending text instead`);
+                            const text = payload.text ?? payload.body;
+                            if (text) {
+                              await replyClient.sendSimple(from, text);
+                            }
+                          }
+                        } catch (audioErr: any) {
+                          api.logger?.error?.(`Threema: error sending voice note: ${audioErr.message}`);
+                          // Fallback to text on error
+                          const text = payload.text ?? payload.body;
+                          if (text) {
+                            if (replyClient.isE2EEnabled) {
+                              await replyClient.sendE2E(from, text);
+                            } else {
+                              await replyClient.sendSimple(from, text);
+                            }
                           }
-                          let splitIdx = remaining.lastIndexOf("\n", limit);
-                          if (splitIdx <= 0) splitIdx = limit;
-                          chunks.push(remaining.slice(0, splitIdx));
-                          remaining = remaining.slice(splitIdx).replace(/^\n/, "");
                         }
-                        for (const chunk of chunks) {
+                      } else {
+                        // Send as text (existing logic)
+                        const text = payload.text ?? payload.body;
+                        if (!text) return;
+                        const limit = getThreemaConfig(currentCfg)?.textChunkLimit ?? 3500;
+                        if (text.length <= limit) {
                           if (replyClient.isE2EEnabled) {
-                            await replyClient.sendE2E(from, chunk);
+                            await replyClient.sendE2E(from, text);
                           } else {
-                            await replyClient.sendSimple(from, chunk);
+                            await replyClient.sendSimple(from, text);
+                          }
+                        } else {
+                          const chunks: string[] = [];
+                          let remaining = text;
+                          while (remaining.length > 0) {
+                            if (remaining.length <= limit) {
+                              chunks.push(remaining);
+                              break;
+                            }
+                            let splitIdx = remaining.lastIndexOf("\n", limit);
+                            if (splitIdx <= 0) splitIdx = limit;
+                            chunks.push(remaining.slice(0, splitIdx));
+                            remaining = remaining.slice(splitIdx).replace(/^\n/, "");
+                          }
+                          for (const chunk of chunks) {
+                            if (replyClient.isE2EEnabled) {
+                              await replyClient.sendE2E(from, chunk);
+                            } else {
+                              await replyClient.sendSimple(from, chunk);
+                            }
                           }
                         }
                       }

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "threema",
   "name": "Threema Gateway",
   "description": "Threema messaging channel via Threema Gateway API (E2E encrypted)",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "channels": [
     "threema"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-threema",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Threema Gateway channel plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",