Enviar Media

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

Proxy Automático: Si Meta no puede descargar tu URL (error 131052), Whaapy automáticamente descarga el archivo y lo re-sube. Esto tiene límite de 5MB. Para archivos más grandes, usa /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.

General

Mensajes

Media

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

Próximos Pasos

Subir Media

Enviar Templates

General

Mensajes

Media

​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

​Próximos Pasos

Subir Media

Enviar Templates

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

Próximos Pasos