> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de medios

> Subir y enviar medios, entender los límites de tamaño y las conversiones, y descargar medios de los mensajes entrantes.

## Límites

| Tipo | Máximo por defecto |
| - | - |
| Imagen | 20 MB |
| Documento (`/send/file`) | 50 MB |
| Vídeo | 100 MB |
| Medios descargados (entrantes) | 500 MB |

El límite de cuerpo de petición HTTP es igual al límite de vídeo (100 MB), por lo que ninguna carga puede excederla. Consulta los valores en vivo con `GET /app/info` (`max_image_size`, `max_file_size`, `max_video_size`). Estos límites están compilados por defecto; no hay ninguna variable de entorno para ellos.

## Dos maneras de proporcionar medios

Cada endpoint de medios acepta un archivo multiparte o una URL que GOWA obtiene del servidor:

```bash theme={null}
# upload
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image=@photo.jpg

# URL
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image_url=https://example.com/photo.jpg
```

Enviar uno u otro, no ambos. Las URLs de medios remotos deben usar HTTP o HTTPS y resolver con direcciones públicas. GOWA bloquea loopback, privados, enlaces-locales y otros destinos reservados, incluyendo redireccionamientos. Sube archivos locales como datos de varias partes en lugar de usar una URL interna.

## Procesando

GOWA necesita FFmpeg y libwebp en el host (ambos están en la imagen Docker).

| Opción | Endpoint | Efecto |
| - | - | - |
| `compress` | imagen (por defecto `true`), vídeo (por defecto `false`) | Volver a codificar antes de enviar. |
| `hd` | imagen, vídeo | Send in HD without upscaling: images up to 2560 px on the long edge; video as H.264 max at 1280×1280. Overrides `compress`. |
| `view_once` | imagen, vídeo | El destinatario puede abrirlo una vez. |
| `gif_playback` | vídeo | Reproducir como un GIF en bucle. |
| `ptt` | audio | Enviar como nota de voz (push-to-talk). Convertido con FFmpeg. |
| (automático) | pegatina | JPG, PNG, WebP o GIF convertidos en una WebP de 512×512. WebP animada debe cumplir con los límites de las etiquetas de WhatsApp. |

`/send/file` envía documentos sin conversión.

El procesamiento de imágenes comprueba las dimensiones de la cabecera antes de decodificar. La ventaja más larga aceptada es de 32.768 píxeles. Las imágenes no JPEG tienen un presupuesto de 40 millones de píxeles. Los JPEG tienen un techo de 80 millones de píxeles más un presupuesto de memoria decodificación de 320 MiB, por lo que algunos JPEG grandes progresivos o CMYK son rechazados por debajo del cierre de píxeles. Los envíos de imágenes originales pueden omitir miniaturas cuando la decodificación excede el presupuesto. Las imágenes interactivas de carrusel tienen límites separados, límites más pequeños en [Mensajes interactivos](https://gowa-docs.mintlify.site/es/examples/interactive-messages.md).

## Media entrante

Con `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (por defecto), GOWA descarga medios de mensajes entrantes a `statics/media/` y pone la ruta relativa en la carga útil del webhook:

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

Obtén en `http://<host>:3000/statics/media/<file>`. Establece `WHATSAPP_IGNORE_STATUS_MEDIA=true` para omitir los medios de las actualizaciones de estado.

Con la descarga automática, el payload lleva una URL de WhatsApp CDN en su lugar. Descarga a través de GOWA, que descifra el archivo:

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download?phone=628987654321@s.whatsapp.net"
```

WhatsApp mantiene los medios en sus servidores durante un tiempo limitado. Descarga lo que necesitas rápidamente.

En GOWA `main` después de v9.9.0, las descargas explícitas y reenvíos pueden pedir al teléfono que vuelva a cargar los medios caducados. El teléfono debe estar en línea y todavía tener el archivo. GOWA espera hasta 30 segundos para una respuesta. Esto también se aplica a las acciones MCP `download_media` y `forward`, y a [Chatwoot history imports](https://gowa-docs.mintlify.site/es/integrations/chatwoot.md#importar-historial).

## Almacenamiento y limpieza

Las rutas son relativas al directorio de procesos, normalmente `src/` de origen o `/app` en Docker. Compone monta los directorios `storages/` y `statics/` en `/app`.

| Ruta | Contenido |
| - | - |
| `statics/media/` | Webhook descargado y descargas explícitas, incluyendo subdirectorios de chat/fechas. |
| `storages/<timestamp>-<uuid>[.<extension>]` | Copias extra guardadas por el manejador de imágenes cuando las descargas automáticas están habilitadas. |
| `storages/scheduled/` | Adjuntos conservados por envíos programados. Permita que el planificador los gestione. |
| `storages/history-*.json` | Volcados de historial, independientemente de las descargas de medios. |

No hay ajustes de retención de medios basados en la edad o punto final de limpieza. Una imagen puede tener copias en `storages/` y `statics/media/`. Nunca elimine todo el directorio `storages/` para recuperar espacio multimedia.

Pausa GOWA y otros escritores, haz una copia de seguridad de los archivos requeridos, luego previsualiza los archivos para eliminarlos. Estos ejemplos de GNU se ejecutan desde el directorio de implementación y seleccionan archivos al menos 31 días completos.

```bash theme={null}
find ./statics/media -type f -mtime +30 -print
find ./storages -maxdepth 1 -type f -mtime +30 \
  -name '[0-9]*-????????-????-????-????-????????????*' -print
```

Después de revisar cada ruta, reemplaza `-print` con `-delete` en los mismos comandos. Preservar archivos de base de datos, `-wal` y `-shm` de SQLite, archivos adjuntos programados y archivos personalizados. Reiniciar GOWA después. Las rutas eliminadas y las URL estáticas dejan de funcionar, y la eliminación de medios no limpia el historial de chat.

`WHATSAPP_AUTO_DOWNLOAD_MEDIA=false` detiene las futuras descargas automáticas y las copias adicionales de imágenes. No elimina archivos antiguos ni impide las descargas explícitas mediante REST o MCP. Consulta la [guía completa de almacenamiento y limpieza de archivos multimedia](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/media-storage.md).

`/statics` sigue siendo público. Almacenados HTML, SVG, scripts y otros documentos se sirven como archivos adjuntos con `application/octet-stream` y `nosniff`. Los bytes de imágenes soportados bajo rutas de previsualización de imágenes pueden renderizarse en línea. Estas protecciones de contenido no restringen quién puede descargar un archivo. Proteja los medios sensibles en el proxy inverso.

## Solución de problemas

| Problema | Fijar |
| - | - |
| `413` o error de límite de cuerpo | El archivo excede los 100 MB; envía un enlace en su lugar. |
| La nota de voz falla o reproduce como un archivo | Instala FFmpeg; establece `ptt=true`. |
| Fallo en la conversión del Sticker | Instala las herramientas libwebp (`cwebp`, `dwebp`, `webpmux`). |
| Fallo en los medios URL | La URL debe ser pública, devolver el archivo directamente (sin página HTML) y ajustarse al límite de tamaño. |


## Related topics

- [Manejo de errores](https://gowa-docs.mintlify.site/es/advanced/error-handling.md)
- [Descargar medios de un mensaje de boletín de noticias](https://gowa-docs.mintlify.site/es/api-reference/newsletter/descargar-medios-de-un-mensaje-de-boletín-de-noticias.md)
- [Descargar medios del mensaje](https://gowa-docs.mintlify.site/es/api-reference/message/descargar-medios-del-mensaje.md)
- [Canales de WhatsApp](https://gowa-docs.mintlify.site/es/examples/newsletters.md)
- [Referencia de configuración](https://gowa-docs.mintlify.site/es/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.