Enviar Media - Whaapy API

Envía archivos multimedia a través de WhatsApp. Soporta imágenes, videos, audio, documentos y stickers.

Métodos de Envío

Hay dos formas de enviar media:

Con URL (link)
Con media_id

Proporciona una URL pública y Meta descargará el archivo:

{
  "to": "+5215512345678",
  "type": "image",
  "image": {
    "link": "https://example.com/imagen.jpg",
    "caption": "Descripción opcional"
  }
}

Primero sube el archivo con /media/v1, luego usa el ID:

{
  "to": "+5215512345678",
  "type": "image",
  "image": {
    "id": "123456789012345",
    "caption": "Descripción opcional"
  }
}

¿Cuándo usar cada método?

Método	Tamaño	Mejor para
`link`	< 5MB	URLs públicas de CDN, imágenes pequeñas
`id` (via `/media/v1`)	Cualquiera	Archivos grandes, URLs privadas, múltiples envíos

Compresión Automática de Imágenes: Si envías una imagen por URL que excede 5MB, Whaapy automáticamente la detecta, la descarga, la comprime con calidad progresiva, y la sube a Meta. No necesitas hacer nada adicional - el proceso es transparente.

Proxy Automático: Si Meta no puede descargar tu URL (error 131052), Whaapy automáticamente descarga el archivo y lo re-sube. Para archivos muy grandes que no se pueden comprimir, usa autoConvert: true para enviarlos como documento, o súbelos primero via /media/v1.

Imagen

Formatos soportados: JPEG, PNG, WebP
Tamaño máximo: 5 MB

Con URL

curl -X POST https://api.whaapy.com/messages/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5215512345678",
    "type": "image",
    "image": {
      "link": "https://example.com/producto.jpg",
      "caption": "¡Mira nuestro nuevo producto!"
    }
  }'

Con media_id

{
  "to": "+5215512345678",
  "type": "image",
  "image": {
    "id": "123456789012345",
    "caption": "Imagen subida previamente"
  }
}

Campos

image.link

string

URL pública de la imagen. Mutuamente excluyente con id.

image.id

string

ID de media obtenido de /media/v1. Mutuamente excluyente con link.

image.caption

string

Descripción opcional que aparece debajo de la imagen. Máximo 1024 caracteres.

Video

Formatos soportados: MP4, 3GPP
Tamaño máximo: 16 MB
Códecs recomendados: H.264 video, AAC audio

Para videos grandes (>5MB), siempre usa /media/v1 primero. El proxy automático tiene límites de tamaño.

Con URL

{
  "to": "+5215512345678",
  "type": "video",
  "video": {
    "link": "https://example.com/tutorial.mp4",
    "caption": "Tutorial de instalación"
  }
}

Con media_id (Recomendado)

{
  "to": "+5215512345678",
  "type": "video",
  "video": {
    "id": "123456789012345",
    "caption": "Video subido previamente"
  }
}

Campos

video.link

string

URL pública del video. Mutuamente excluyente con id.

video.id

string

ID de media obtenido de /media/v1. Mutuamente excluyente con link.

video.caption

string

Descripción opcional. Máximo 1024 caracteres.

Audio

Formatos soportados: AAC, MP3, OGG (Opus), AMR
Tamaño máximo: 16 MB

Los audios se muestran como notas de voz en WhatsApp si son formato OGG con códec Opus.

Ejemplo

curl -X POST https://api.whaapy.com/messages/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5215512345678",
    "type": "audio",
    "audio": {
      "link": "https://example.com/mensaje.mp3"
    }
  }'

Con media_id

{
  "to": "+5215512345678",
  "type": "audio",
  "audio": {
    "id": "123456789012345"
  }
}

Campos

audio.link

string

URL pública del audio.

audio.id

string

ID de media obtenido de /media/v1.

Los audios no soportan caption. Si necesitas agregar contexto, envía un mensaje de texto antes o después.

Documento

Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT
Tamaño máximo: 100 MB

Ejemplo

curl -X POST https://api.whaapy.com/messages/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5215512345678",
    "type": "document",
    "document": {
      "link": "https://example.com/factura.pdf",
      "filename": "factura-enero-2026.pdf",
      "caption": "Tu factura del mes de enero"
    }
  }'

Con media_id

{
  "to": "+5215512345678",
  "type": "document",
  "document": {
    "id": "123456789012345",
    "filename": "contrato.pdf",
    "caption": "Contrato firmado"
  }
}

Campos

document.link

string

URL pública del documento.

document.id

string

ID de media obtenido de /media/v1.

document.filename

string

required

Nombre del archivo que verá el usuario al descargar. Recomendado para mejor UX.

document.caption

string

Descripción opcional del documento.

Sticker

Formato soportado: WebP
Tamaño máximo: 500 KB
Dimensiones: 512x512 píxeles (recomendado)

Los stickers animados deben usar WebP animado y no exceder 500KB.

Ejemplo

{
  "to": "+5215512345678",
  "type": "sticker",
  "sticker": {
    "link": "https://example.com/sticker.webp"
  }
}

Con media_id

{
  "to": "+5215512345678",
  "type": "sticker",
  "sticker": {
    "id": "123456789012345"
  }
}

Campos

sticker.link

string

URL pública del sticker en formato WebP.

sticker.id

string

ID de media obtenido de /media/v1.

Los stickers no soportan caption. Son elementos visuales independientes.

Respuesta Exitosa

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "+5215512345678", "wa_id": "5215512345678" }
  ],
  "messages": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "wamid": "wamid.HBgLNTIxNTUx..." }
  ],
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "conversationId": "660e8400-e29b-41d4-a716-446655440001",
    "messageType": "image",
    "direction": "outbound",
    "status": "sent",
    "createdAt": "2026-01-22T10:30:00Z"
  }
}

Límites de Tamaño

Tipo	Formatos	Tamaño Máximo
`image`	JPEG, PNG, WebP	5 MB
`video`	MP4, 3GPP	16 MB
`audio`	AAC, MP3, OGG, AMR	16 MB
`document`	PDF, DOC, XLS, PPT, TXT	100 MB
`sticker`	WebP	500 KB

Errores Comunes

Media No Descargable (131052)

{
  "error": "media_download_failed",
  "message": "No se pudo descargar el archivo multimedia",
  "code": "131052"
}

Solución: Usa una URL pública o sube el archivo via /media/v1.

Tipo de Media No Soportado (131051)

{
  "error": "unsupported_media_type",
  "message": "El formato del archivo no es compatible",
  "code": "131051"
}

Solución: Convierte el archivo a un formato soportado.

Archivo Demasiado Grande (131053)

{
  "error": "file_too_large",
  "message": "El archivo excede el tamaño máximo permitido",
  "code": "131053"
}

Solución: Comprime el archivo o divídelo en partes más pequeñas.

Flujo Recomendado para Archivos Grandes

El media_id expira después de ~30 días. Puedes reutilizarlo para enviar el mismo archivo a múltiples destinatarios sin re-subirlo.

Conversión Automática (autoConvert)

Cuando un archivo excede el límite de tamaño para su tipo, puedes usar autoConvert: true para que Whaapy intente comprimir automáticamente y, si la compresión no es suficiente, envíe el archivo como documento.

autoConvert

boolean

default:"false"

Habilita compresión automática y conversión a documento como fallback

Comportamiento

Tipo	Límite	Con autoConvert
`image`	5 MB	Comprime con calidad progresiva (85% → 70% → 50%). Si sigue excediendo, envía como documento
`video`	16 MB	No comprime (muy costoso). Si excede, envía como documento directamente
`audio`	16 MB	Comprime a MP3 64kbps mono. Si sigue excediendo, envía como documento
`document`	100 MB	Sin cambios (ya tiene el límite más alto)

Ejemplo: Imagen Grande con autoConvert

{
  "to": "+5215512345678",
  "type": "image",
  "image": {
    "link": "https://example.com/foto-alta-resolucion.jpg",
    "caption": "Foto en alta resolución"
  },
  "autoConvert": true
}

Sin autoConvert: Si la imagen excede 5MB, recibirás error 413. Con autoConvert: true:

Whaapy intenta comprimir la imagen
Si la compresión es exitosa → se envía como imagen
Si la compresión no es suficiente → se envía como documento

Respuesta cuando se convierte a documento

{
  "messaging_product": "whatsapp",
  "messages": [{ "id": "..." }],
  "data": {
    "messageType": "document",
    "metadata": {
      "originalType": "image",
      "wasConverted": true,
      "reason": "Exceeded size limit after compression"
    }
  }
}

Cuando un archivo se envía como documento, el destinatario no verá una vista previa en la conversación. Deberá descargarlo para verlo.

Para mejor experiencia de usuario, comprime tus imágenes antes de enviarlas. Si usas Cloudinary o servicios similares, agrega transformaciones como q_auto,w_1920 para reducir el tamaño automáticamente.

Error de Tamaño (media_too_large)

Cuando un archivo excede el límite y autoConvert está deshabilitado:

{
  "error": "media_too_large",
  "message": "image exceeds 5MB limit (7.9MB)",
  "suggestion": "Use autoConvert:true to auto-compress, or send as document type",
  "limits": {
    "image": "5MB",
    "video": "16MB",
    "audio": "16MB",
    "document": "100MB"
  }
}

El error incluye los límites actuales de Meta WhatsApp Cloud API para tu referencia.

Control de IA (Opcional)

Puedes controlar el comportamiento del agente IA al enviar mensajes de media usando el campo ai:

ai.pause

boolean

Pausar la IA después de enviar este mensaje

ai.pauseDuration

number

Duración de la pausa en minutos (default: 5, máximo: 1440)

ai.disable

boolean

Desactivar la IA permanentemente en esta conversación

Ejemplo: Enviar Imagen y Pausar IA

{
  "to": "+5215512345678",
  "type": "image",
  "image": {
    "link": "https://example.com/producto.jpg",
    "caption": "Aquí está la foto que pediste"
  },
  "ai": { "pause": true, "pauseDuration": 30 }
}

Esto es útil cuando integras con sistemas externos (n8n, Zapier, CRMs) y necesitas evitar que la IA responda automáticamente. Ver Control de IA para más opciones.

Próximos Pasos

Subir Media

Endpoint para subir archivos grandes

Enviar Templates

Mensajes fuera de ventana 24h

Control de IA

Controla cuándo la IA responde

General

Mensajes

Conversaciones

Templates

Media

Contactos

Funnels

Agente IA

Webhooks

​Métodos de Envío

​¿Cuándo usar cada método?

​Imagen

​Con URL

​Con media_id

​Campos

​Video

​Con URL

​Con media_id (Recomendado)

​Campos

​Audio

​Ejemplo

​Con media_id

​Campos

​Documento

​Ejemplo

​Con media_id

​Campos

​Sticker

​Ejemplo

​Con media_id

​Campos

​Respuesta Exitosa

​Límites de Tamaño

​Errores Comunes

​Media No Descargable (131052)

​Tipo de Media No Soportado (131051)

​Archivo Demasiado Grande (131053)

​Flujo Recomendado para Archivos Grandes

​Conversión Automática (autoConvert)

​Comportamiento

​Ejemplo: Imagen Grande con autoConvert

​Respuesta cuando se convierte a documento

​Error de Tamaño (media_too_large)

​Control de IA (Opcional)

​Ejemplo: Enviar Imagen y Pausar IA

​Próximos Pasos

Subir Media

Enviar Templates

Control de IA

Métodos de Envío

¿Cuándo usar cada método?

Imagen

Con URL

Con media_id

Campos

Video

Con URL

Con media_id (Recomendado)

Campos

Audio

Ejemplo

Con media_id

Campos

Documento

Ejemplo

Con media_id

Campos

Sticker

Ejemplo

Con media_id

Campos

Respuesta Exitosa

Límites de Tamaño

Errores Comunes

Media No Descargable (131052)

Tipo de Media No Soportado (131051)

Archivo Demasiado Grande (131053)

Flujo Recomendado para Archivos Grandes

Conversión Automática (autoConvert)

Comportamiento

Ejemplo: Imagen Grande con autoConvert

Respuesta cuando se convierte a documento

Error de Tamaño (media_too_large)

Control de IA (Opcional)

Ejemplo: Enviar Imagen y Pausar IA

Próximos Pasos