Handling Media on WhatsApp with OpenClaw

Sending media through automated channels is usually a headache. You often deal with weird encoding issues, strict file size limits, or cryptic API errors that don’t tell you why an image failed to upload. I’ve spent too much time trying to figure out why a simple JPEG won’t send, only to realize the platform has hidden rules about dimensions or headers.

I want to show you how OpenClaw handles this through the WhatsApp Baileys Web channel. It automates the messy parts like recompression and MIME detection so you can focus on the actual content.

What You’ll Need

• The WhatsApp channel (running via Baileys Web).
• Local file paths or HTTP(S) URLs for your media.
• Media files that fit within the platform limits.
• Optional: Docker sandbox enabled for inbound media processing.

Quick Start

You can send media directly from the CLI. The system handles the buffer loading and detects the media type for you.

1. Send an image with a caption

Run this command to send a local file:

openclaw message send --media ./photo.jpg --message "Here is the photo"

2. Send a looping GIF

If you have an MP4 file and want it to play like a GIF on mobile clients, use the playback flag:

openclaw message send --media ./clip.mp4 --gif-playback

3. Check the payload before sending

If you want to see what OpenClaw is doing without actually sending the message, use these flags:

openclaw message send --media ./doc.pdf --dry-run --json

4. Use media in auto-replies

When you configure getReplyFromConfig, you can return mediaUrl or mediaUrls. The system resolves these paths or URLs and sends them sequentially.

How it Works

I like that the system is smart about how it treats different files. When you send an image, it automatically resizes and recompresses it to a JPEG with a maximum side of 2048px. It targets the agents.defaults.mediaMaxMb setting (usually 5MB) and caps everything at 6MB.

For audio, the system sends it as a voice note by default (ptt: true). If you are dealing with inbound messages, OpenClaw downloads the media to a temp file and gives you two variables to use in your templates:

• {{MediaUrl}}: A pseudo-URL for the inbound media.
• {{MediaPath}}: The local temp path where the file is stored.

If you have a Docker sandbox enabled, these files are copied into the sandbox workspace automatically.

Troubleshooting

If your media isn’t sending or being processed, check these common limit issues:

• Outbound Images: Files are capped at 6MB after recompression. If the file is still too large or unreadable, the logs will show an error and skip the reply.
• Audio and Video: These have a 16MB cap for outbound sends.
• Documents: Anything that isn’t an image, audio, or video is treated as a document and can be up to 100MB.
• Media Understanding: If you use tools to describe images or transcribe audio, there are different caps. Images skip understanding at 10MB, audio at 20MB, and video at 50MB. The message still goes through, but the “understanding” part is skipped.

Need more help with your configuration? Talk to the AI Setup Assistant.

What’s Next

• Media Understanding Configuration
• CLI Reference
• Docker Sandbox Setup
• Auto-Reply Logic