Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(wwebjs): decode the filename derived from a media URL

Yudhi Armyndharis7e6b8b4db4e1
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 77aee3b7b..a4b450f46 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -1880,7 +1880,7 @@ Send a document/file (by URL or base64). Uses `SendMediaMessageDto`; `filename`
{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }
```
-**Engine differences:** Baileys always sends a document as a document, while whatsapp-web.js deliberately keeps normal mimetype classification for `status@broadcast` and broadcast lists — the library returns `null` for document-mode sends to those recipients, so forcing the flag there would turn a working send into a failure. For URL-based sends without an explicit `filename`, whatsapp-web.js derives the URL basename; Baileys falls back to the literal `file`.
+**Engine differences:** Baileys always sends a document as a document, while whatsapp-web.js deliberately keeps normal mimetype classification for `status@broadcast` and broadcast lists; the library returns `null` for document-mode sends to those recipients, so forcing the flag there would turn a working send into a failure. For URL-based sends without an explicit `filename`, whatsapp-web.js derives the URL basename, percent-decoded; Baileys falls back to the literal `file`.
**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable)
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
index 0a11d0d14..1359ea7e1 100644
--- a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
+++ b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
@@ -570,6 +570,21 @@ describe('loadRemoteMedia — routes through the SSRF-pinned media fetch', () =>
expect(undiciFetch).not.toHaveBeenCalled();
});
+ it('names the file after the percent-decoded URL basename', async () => {
+ (undiciFetch as jest.Mock).mockResolvedValue(fakeResponse([1], { 'content-type': 'application/pdf' }));
+
+ const name = async (url: string): Promise<string | undefined> =>
+ (await loadRemoteMedia(url, undefined)).filename ?? undefined;
+
+ expect(await name('https://8.8.8.8/files/Laporan%20Bulanan%20Sept.pdf')).toBe('Laporan Bulanan Sept.pdf');
+ // A malformed escape keeps the raw name instead of failing the send.
+ expect(await name('https://8.8.8.8/files/x%zz.pdf')).toBe('x%zz.pdf');
+ expect(await name('https://8.8.8.8/files/r%E0%A4.pdf')).toBe('r%E0%A4.pdf');
+ // A decoded separator cannot put a path into the label.
+ expect(await name('https://8.8.8.8/files/a%2Fb%5Cc.pdf')).toBe('a_b_c.pdf');
+ expect(await name('https://8.8.8.8/')).toBeUndefined();
+ });
+
it('honors the SSRF_ALLOWED_HOSTS escape-hatch for trusted internal media stores', async () => {
process.env.SSRF_ALLOWED_HOSTS = 'minio';
(undiciFetch as jest.Mock).mockResolvedValue(fakeResponse([1], { 'content-type': 'image/png' }));
diff --git a/src/engine/adapters/wwebjs-messaging.ts b/src/engine/adapters/wwebjs-messaging.ts
index 110e1fe7c..6945cfa9a 100644
--- a/src/engine/adapters/wwebjs-messaging.ts
+++ b/src/engine/adapters/wwebjs-messaging.ts
@@ -91,7 +91,14 @@ export async function loadRemoteMedia(url: string, sessionProxyUrl: string | und
// `sessionProxyUrl` routes the fetch through this session's egress proxy (#1626); the browser's
// own requests already ride Chromium's --proxy-server, this one is made by the gateway itself.
const { data, mimetype } = await loadRemoteMediaBuffer(url, sessionProxyUrl);
- const filename = new URL(url).pathname.split('/').pop() || undefined;
+ // The pathname keeps its percent-encoding, and the recipient would see `Laporan%20Bulanan.pdf`. A
+ // malformed escape keeps the raw name, and a decoded slash is replaced so the label stays one name.
+ let filename = new URL(url).pathname.split('/').pop() || undefined;
+ try {
+ filename = filename && decodeURIComponent(filename).replace(/[/\\]/g, '_');
+ } catch {
+ // URIError: keep the raw basename.
+ }
return new MessageMedia(mimetype || 'application/octet-stream', data.toString('base64'), filename);
}