WhatsApp Media Support

Kennst du das? Du willst nur kurz ein Bild oder ein PDF über einen Bot verschicken, aber die API macht Probleme, weil das Format nicht passt oder die Datei zu groß ist. Besonders bei WhatsApp ist das Handling von Anhängen oft zeitfressend, weil du dich normalerweise selbst um Kompression, MIME-Types und unterschiedliche Limits kümmern musst.

Wir haben den WhatsApp Channel (Baileys Web) so gebaut, dass er dir diese Arbeit abnimmt. Egal ob du lokale Dateien oder URLs verwendest, das System erkennt den Medientyp und optimiert den Payload automatisch für den Versand.

Voraussetzungen

• WhatsApp Channel (Baileys Web)
• OpenClaw CLI

Schnellstart

In nur 5 Minuten schickst du dein erstes Bild oder Dokument über die CLI. Der Befehl ist direkt und braucht keine komplizierte Konfiguration.

openclaw message send --media <path-or-url> [--message <caption>]

Für Tests und Automatisierungen gibt es zwei hilfreiche Flags:

• --dry-run: Zeigt dir den berechneten Payload an, ohne die Nachricht wirklich zu senden.
• --json: Gibt das Ergebnis als JSON-Objekt zurück (enthält channel, to, messageId, mediaUrl und caption).

Wenn du ein MP4 als GIF-Ersatz senden möchtest, das auf dem Smartphone direkt in Dauerschleife läuft, füge einfach --gif-playback hinzu.

Media Handling & Limits

Das System verarbeitet Medien je nach Typ unterschiedlich, um die Zustellung zu garantieren:

• Bilder: Werden automatisch auf maximal 2048px (längste Seite) verkleinert und als JPEG rekomprimiert. Das Ziel ist eine Größe unter 5 MB, absolut gedeckelt bei 6 MB.
• Audio: Wird standardmäßig als Voice Note (ptt: true) gesendet. Das Limit liegt hier bei 16 MB.
• Video: Pass-through bis maximal 16 MB.
• Dokumente: Alle anderen Dateitypen werden bis zu einer Größe von 100 MB unterstützt, wobei der ursprüngliche Dateiname erhalten bleibt.

Inbound Media & Automation

Wenn Nutzer Medien an deinen Bot senden, schreibt OpenClaw diese in temporäre Dateien. Du kannst in deinen Commands auf folgende Variablen zugreifen:

• {{MediaUrl}}: Eine Pseudo-URL für das empfangene Medium.
• {{MediaPath}}: Der lokale Pfad zur temporären Datei.

Falls du eine Docker Sandbox nutzt, kopiert das System die Dateien automatisch in den Workspace und passt die Pfade auf media/inbound/<filename> an. Bei aktiviertem Media Understanding (über tools.media.*) werden Audios automatisch transkribiert ({{Transcript}}) oder Bildinhalte beschrieben, bevor sie an deine Command-Logik übergeben werden.

Fehlerbehebung

Hier sind die Lösungen für Probleme, die beim Medienversand auftreten können:

• Media wird übersprungen: Wenn eine Datei das Limit (z. B. 6 MB für Bilder oder 100 MB für Dokumente) überschreitet oder nicht lesbar ist, wird ein Fehler im Log ausgegeben und die Antwort wird ohne den Anhang gesendet.
• Kein Media Understanding: Wenn ein Bild größer als 10 MB oder ein Video größer als 50 MB ist, wird die automatische Beschreibung/Transkription übersprungen. Die Nachricht selbst wird aber weiterhin verarbeitet.
• Fehlerhafte MIME-Types: Das System prüft zuerst die Magic Bytes der Datei, dann die HTTP-Header und zuletzt die Dateiendung. Stelle sicher, dass die Quelldatei nicht beschädigt ist.

Benötigst du Hilfe bei der Konfiguration deiner Media-Tools? Nutze den AI Setup Assistant.

Nächste Schritte

• WhatsApp Channel Setup
• Command Templating & Variables
• Docker Sandbox Configuration
• Auto-Reply Configuration