> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Supporto per immagini e contenuti multimediali

Il canale WhatsApp viene eseguito tramite **Baileys Web**. Questo documento descrive le regole attuali di gestione dei media per invio, Gateway e risposte degli agenti.

## Obiettivi

* Inviare media con didascalie facoltative tramite `openclaw message send --media`.
* Consentire alle risposte automatiche dalla posta in arrivo web di includere media insieme al testo.
* Mantenere limiti per tipo ragionevoli e prevedibili.

## Superficie CLI

* `openclaw message send --media <path-or-url> [--message <caption>]`
  * `--media` facoltativo; la didascalia può essere vuota per invii solo media.
  * `--dry-run` stampa il payload risolto; `--json` emette `{ channel, to, messageId, mediaUrl, caption }`.

## Comportamento del canale WhatsApp Web

* Input: percorso file locale **oppure** URL HTTP(S).
* Flusso: carica in un Buffer, rileva il tipo di media e crea il payload corretto:
  * **Immagini:** ridimensiona e ricomprime in JPEG (lato massimo 2048 px) mirando 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 altro contenuto, fino a 100 MB, con nome file preservato quando disponibile.
* Riproduzione stile GIF di 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 le intestazioni, quindi l'estensione del file.
* La didascalia proviene da `--message` o `reply.text`; è consentita una didascalia vuota.
* Logging: non dettagliato mostra `↩️`/`✅`; dettagliato include dimensione e percorso/URL di origine.

## Pipeline di risposta automatica

* `getReplyFromConfig` restituisce `{ text?, mediaUrl?, mediaUrls? }`.
* Quando è presente un media, il mittente web risolve percorsi locali o URL usando la stessa pipeline di `openclaw message send`.
* Più voci media vengono inviate in sequenza se fornite.

## Media in ingresso verso i comandi

* Quando i messaggi web in ingresso includono media, OpenClaw li scarica in un file temporaneo ed espone variabili di templating:
  * `{{MediaUrl}}` pseudo-URL per il media in ingresso.
  * `{{MediaPath}}` percorso temporaneo locale scritto prima di eseguire il comando.
* Quando è abilitata una sandbox Docker per sessione, il media in ingresso viene copiato nell'area di lavoro della sandbox e `MediaPath`/`MediaUrl` vengono riscritti in un percorso relativo come `media/inbound/<filename>`.
* La comprensione dei media (se configurata tramite `tools.media.*` o `tools.media.models` condiviso) 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 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.
* Media troppo grandi o non leggibili → errore chiaro nei log e la risposta viene saltata.

**Limiti di comprensione dei media (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 media troppo grandi saltano la comprensione, ma le risposte procedono comunque 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 dimensione) e il flag nota vocale per l'audio.
* Assicurarsi che le risposte con più media si espandano in invii sequenziali.

## Correlati

* [Acquisizione fotocamera](/it/nodes/camera)
* [Comprensione dei media](/it/nodes/media-understanding)
* [Audio e note vocali](/it/nodes/audio)