Supporto per immagini e contenuti multimediali

Il canale WhatsApp funziona tramite Baileys Web. Questo documento descrive le regole attuali di gestione dei contenuti multimediali per invii, Gateway e risposte degli agenti.

# Obiettivi

• Inviare contenuti multimediali con didascalie opzionali tramite openclaw message send --media.
• Consentire alle risposte automatiche dalla casella in arrivo web di includere contenuti multimediali insieme al testo.
• Mantenere limiti per tipo sensati e prevedibili.

# Superficie CLI

• openclaw message send --media <path-or-url> [--message <caption>]
  • --media è opzionale; la didascalia può essere vuota per invii di soli contenuti multimediali.
  • --dry-run stampa il payload risolto; --json emette { channel, to, messageId, mediaUrl, caption }.

# Comportamento del canale WhatsApp Web

• Input: percorso di file locale oppure URL HTTP(S).
• Flusso: carica in un Buffer, rileva il tipo di contenuto multimediale e costruisce il payload corretto:
  • Immagini: ridimensionamento e ricompressione in JPEG (lato massimo 2048 px) puntando a channels.whatsapp.mediaMaxMb (predefinito: 50 MB).
  • Audio/voce/video: pass-through fino a 16 MB; l'audio viene inviato come nota vocale (ptt: true).
  • Documenti: qualsiasi altra cosa, fino a 100 MB, con nome file preservato quando disponibile.
• Riproduzione in stile GIF su WhatsApp: invia un MP4 con gifPlayback: true (CLI: --gif-playback) così i client mobili lo riproducono in loop inline.
• Il rilevamento MIME preferisce i magic byte, poi gli header, poi l'estensione del file.
• La didascalia viene da --message o reply.text; è consentita una didascalia vuota.
• Logging: la modalità non dettagliata mostra ↩️/✅; quella dettagliata include dimensione e percorso/URL di origine.

# Pipeline di risposta automatica

• getReplyFromConfig restituisce { text?, mediaUrl?, mediaUrls? }.
• Quando sono presenti contenuti multimediali, il mittente web risolve percorsi locali o URL usando la stessa pipeline di openclaw message send.
• Se fornite, più voci multimediali vengono inviate in sequenza.

# Contenuti multimediali in ingresso verso i comandi (Pi)

• Quando i messaggi web in ingresso includono contenuti multimediali, OpenClaw li scarica in un file temporaneo ed espone variabili di templating:
  • pseudo-URL {{MediaUrl}} per il contenuto multimediale in ingresso.
  • percorso temporaneo locale {{MediaPath}} scritto prima di eseguire il comando.
• Quando è abilitata una sandbox Docker per sessione, i contenuti multimediali in ingresso vengono copiati nello spazio di lavoro della sandbox e MediaPath/MediaUrl vengono riscritti in un percorso relativo come media/inbound/<filename>.
• La comprensione dei contenuti multimediali (se configurata tramite tools.media.* o tools.media.models condivisi) viene eseguita prima del templating e può inserire blocchi [Image], [Audio] e [Video] in Body.
  • L'audio imposta {{Transcript}} e usa la trascrizione per il parsing dei comandi, così i comandi slash continuano a funzionare.
  • Le descrizioni di video e immagini preservano eventuale testo della didascalia per il parsing dei comandi.
  • Se il modello di immagine primario attivo supporta già nativamente la visione, OpenClaw salta il blocco di riepilogo [Image] e passa invece l'immagine originale al modello.
• Per impostazione predefinita viene elaborato solo il primo allegato immagine/audio/video corrispondente; imposta tools.media.<cap>.attachments per elaborare più allegati.

# Limiti ed errori

Limiti di invio in uscita (invio web WhatsApp)

• Immagini: fino a channels.whatsapp.mediaMaxMb (predefinito: 50 MB) dopo la ricompressione.
• Audio/voce/video: limite di 16 MB; documenti: limite di 100 MB.
• Contenuti multimediali troppo grandi o illeggibili → errore chiaro nei log e la risposta viene saltata.

Limiti di comprensione dei contenuti multimediali (trascrizione/descrizione)

• Immagine predefinita: 10 MB (tools.media.image.maxBytes).
• Audio predefinito: 20 MB (tools.media.audio.maxBytes).
• Video predefinito: 50 MB (tools.media.video.maxBytes).
• I contenuti multimediali troppo grandi saltano la comprensione, ma le risposte vengono comunque inviate con il corpo originale.

# Note per i test

• Coprire i flussi di invio e risposta per i casi immagine/audio/documento.
• Convalidare la ricompressione per le immagini (limite di dimensione) e il flag di nota vocale per l'audio.
• Assicurare che le risposte con più contenuti multimediali si espandano in invii sequenziali.

# Correlati

• Acquisizione fotocamera
• Comprensione dei contenuti multimediali
• Audio e note vocali