Image and media support

Image & Media Support (2025-12-05)

The WhatsApp channel runs via Baileys Web. This document captures the current media handling rules for send, gateway, and agent replies.

Goals

• Send media with optional captions via
  text

  Copy

  openclaw message send --media
  .
• Allow auto-replies from the web inbox to include media alongside text.
• Keep per-type limits sane and predictable.

CLI Surface

• text

  Copy

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

    Copy

    --media
    optional; caption can be empty for media-only sends.
  • text

    Copy

    --dry-run
    prints the resolved payload;
    text

    Copy

    --json
    emits
    text

    Copy

    { channel, to, messageId, mediaUrl, caption }
    .

WhatsApp Web channel behavior

• Input: local file path or HTTP(S) URL.
• Flow: load into a Buffer, detect media kind, and build the correct payload:
  • Images: resize & recompress to JPEG (max side 2048px) targeting
    text

    Copy

    channels.whatsapp.mediaMaxMb
    (default: 50 MB).
  • Audio/Voice/Video: pass-through up to 16 MB; audio is sent as a voice note (
    text

    Copy

    ptt: true
    ).
  • Documents: anything else, up to 100 MB, with filename preserved when available.
• WhatsApp GIF-style playback: send an MP4 with
  text

  Copy

  gifPlayback: true
  (CLI:
  text

  Copy

  --gif-playback
  ) so mobile clients loop inline.
• MIME detection prefers magic bytes, then headers, then file extension.
• Caption comes from
  text

  Copy

  --message
  or
  text

  Copy

  reply.text
  ; empty caption is allowed.
• Logging: non-verbose shows
  text

  Copy

  ↩️
  /
  text

  Copy

  ✅
  ; verbose includes size and source path/URL.

Auto-Reply Pipeline

• text

  Copy

  getReplyFromConfig
  returns
  text

  Copy

  { text?, mediaUrl?, mediaUrls? }
  .
• When media is present, the web sender resolves local paths or URLs using the same pipeline as
  text

  Copy

  openclaw message send
  .
• Multiple media entries are sent sequentially if provided.

Inbound media to commands (Pi)

• When inbound web messages include media, OpenClaw downloads to a temp file and exposes templating variables:
  • text

    Copy

    {{MediaUrl}}
    pseudo-URL for the inbound media.
  • text

    Copy

    {{MediaPath}}
    local temp path written before running the command.
• When a per-session Docker sandbox is enabled, inbound media is copied into the sandbox workspace and
  text

  Copy

  MediaPath
  /
  text

  Copy

  MediaUrl
  are rewritten to a relative path like
  text

  Copy

  media/inbound/<filename>
  .
• Media understanding (if configured via
  text

  Copy

  tools.media.*
  or shared
  text

  Copy

  tools.media.models
  ) runs before templating and can insert
  text

  Copy

  [Image]
  ,
  text

  Copy

  [Audio]
  , and
  text

  Copy

  [Video]
  blocks into
  text

  Copy

  Body
  .
  • Audio sets
    text

    Copy

    {{Transcript}}
    and uses the transcript for command parsing so slash commands still work.
  • Video and image descriptions preserve any caption text for command parsing.
  • If the active primary image model already supports vision natively, OpenClaw skips the
    text

    Copy

    [Image]
    summary block and passes the original image to the model instead.
• By default only the first matching image/audio/video attachment is processed; set
  text

  Copy

  tools.media.<cap>.attachments
  to process multiple attachments.

Limits & Errors

Outbound send caps (WhatsApp web send)

• Images: up to
  text

  Copy

  channels.whatsapp.mediaMaxMb
  (default: 50 MB) after recompression.
• Audio/voice/video: 16 MB cap; documents: 100 MB cap.
• Oversize or unreadable media → clear error in logs and the reply is skipped.

Media understanding caps (transcription/description)

• Image default: 10 MB (
  text

  Copy

  tools.media.image.maxBytes
  ).
• Audio default: 20 MB (
  text

  Copy

  tools.media.audio.maxBytes
  ).
• Video default: 50 MB (
  text

  Copy

  tools.media.video.maxBytes
  ).
• Oversize media skips understanding, but replies still go through with the original body.

Notes for Tests

• Cover send + reply flows for image/audio/document cases.
• Validate recompression for images (size bound) and voice-note flag for audio.
• Ensure multi-media replies fan out as sequential sends.

Related

• Camera capture
• Media understanding
• Audio and voice notes