Saltar al contenido principal
POST
/
api
/
message
/
media
/
:instance
Enviar media
curl --request POST \
  --url https://api.example.com/api/message/media/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "mediaType": "<string>",
  "mediaUrl": "<string>",
  "message": "<string>",
  "mimeType": "<string>",
  "fileName": "<string>",
  "isVoice": true,
  "duration": {},
  "waveform": [
    {}
  ],
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "mention": [
    "<string>"
  ],
  "mentionAll": true,
  "source": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

​
Descripción

Envía un archivo de media (image, video, document o audio) desde una URL pública. Soporta message como subtítulo, replyTo (cita por ID), replyPrivate, mention / mentionAll (solo chats de grupo), delay (en segundos) para simular tipeo real y, para audio, isVoice (PTT), duration y waveform. El servidor descarga el archivo, detecta el mimeType cuando se omite y lo sube a los servidores de WhatsApp antes de enviar.

​
Ejemplos

​
Imagen por URL

Envía una imagen (mediaType: "image") descargada desde una URL pública, con message usado como el subtítulo que aparece bajo la foto en el chat. 
curl -X POST "https://ryzeapi.cloud/api/message/media/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "5511999999999",
    "mediaType": "image",
    "mediaUrl":  "https://example.com/photo.jpg",
    "message":   "Check out this photo!"
  }'

​
Audio de voz (PTT)

Cuando mediaType: "audio" e isVoice se omite, el servidor asume true por defecto (mensaje de voz/PTT). Para enviar como audio “regular” (una pista musical, por ejemplo), pasa isVoice: false. 
curl -X POST "https://ryzeapi.cloud/api/message/media/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "5511999999999",
    "mediaType": "audio",
    "mediaUrl":  "https://example.com/audio.ogg",
    "isVoice":   true
  }'

​
Documento (PDF) con fileName

Envía un PDF como documento. fileName (Contract-2026.pdf) define el nombre mostrado en la tarjeta de adjunto y message aparece como texto acompañante. Sin fileName, WhatsApp muestra un nombre genérico. 
curl -X POST "https://ryzeapi.cloud/api/message/media/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "5511999999999",
    "mediaType": "document",
    "mediaUrl":  "https://example.com/contract.pdf",
    "fileName":  "Contract-2026.pdf",
    "message":   "Here is the attached contract."
  }'

​
Video con subtítulo y delay

Envía un video MP4 con el subtítulo “Check out this video!” y delay: 3, el servidor envía el indicador “escribiendo…” durante 3 segundos antes de disparar el video, simulando tipeo real. 
curl -X POST "https://ryzeapi.cloud/api/message/media/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "5511999999999",
    "mediaType": "video",
    "mediaUrl":  "https://example.com/video.mp4",
    "message":   "Check out this video!",
    "delay":     3
  }'

​
Imagen en grupo con respuesta y mención

Envía una imagen en un grupo (@g.us), citando un mensaje anterior vía replyTo y mencionando a un miembro vía el array mention. @5511888888888 en el subtítulo se vuelve clicable y dispara una notificación para el usuario etiquetado. 
curl -X POST "https://ryzeapi.cloud/api/message/media/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "120363406289005073@g.us",
    "mediaType": "image",
    "mediaUrl":  "https://example.com/banner.jpg",
    "message":   "Check it out @5511888888888, it is ready!",
    "replyTo":   "3EB08FCF27E532F1B0F5",
    "mention":   ["5511888888888"]
  }'

​
Respuesta exitosa

El messageType refleja el mediaType que enviaste (image, video, document o audio). Los metadatos resueltos por el upload aparecen en mediaUrl (URL re-emitida para mmg.whatsapp.net), mediaMimeType y mediaSize. Para audio PTT, el servidor también retorna mediaDuration cuando puede calcularla.
200 OK
{
  "success": true,
  "message": "Media message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":     "3EB08FCF27E532F1B0F5",
    "direction":     "outgoing",
    "messageType":   "image",
    "content":       "Check out this photo!",
    "source":        "api",
    "timestamp":     "2026-04-30T14:30:00Z",
    "mediaUrl":      "https://mmg.whatsapp.net/v/t62.7118-24/...",
    "mediaMimeType": "image/jpeg",
    "mediaSize":     184320,
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}
Para mediaType: "document", fileName aparece en la tarjeta. Para mediaType: "audio" con isVoice: true, el mensaje se entrega como PTT (waveform + ícono de micrófono). Para audio “regular” (una pista musical), usa isVoice: false.

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia (p. ej., $Instance_Name).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
number
string
requerido
Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
mediaType
string
requerido
Uno de: image, video, document, audio. Determina cómo WhatsApp renderiza el mensaje.
​
mediaUrl
string
requerido
URL pública del archivo. El servidor la descarga y la sube a los servidores de WhatsApp antes de enviar. La URL debe ser accesible públicamente (sin autenticación).
​
message
string
Subtítulo de la media. Para mediaType: "document", aparece como texto acompañante. Opcional para todos los tipos.
​
mimeType
string
Tipo MIME del archivo (p. ej., image/jpeg, application/pdf). Cuando se omite, el servidor lo detecta automáticamente desde la descarga.
​
fileName
string
Nombre del archivo mostrado en la tarjeta. Recomendado para mediaType: "document", sin él, WhatsApp muestra un nombre genérico.
​
isVoice
boolean
predeterminado:"true (for audio)"
Aplica solo a mediaType: "audio". Cuando es true, el mensaje se entrega como PTT (mensaje de voz, con waveform). Cuando es false, se entrega como audio regular (una pista musical). Cuando el campo se omite en audio, el servidor asume true.
​
duration
uint32
Duración del audio en segundos. Aplica solo a mediaType: "audio". Opcional, cuando se omite, el servidor intenta detectarla automáticamente.
​
waveform
byte[]
Waveform de audio precomputada (PTT). Opcional, cuando se omite, el servidor genera automáticamente una waveform default. Aplica solo a mediaType: "audio" con isVoice: true.
​
delay
int
predeterminado:"0"
Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” al destinatario y dispara “pausado” antes del envío real.
​
replyTo
string
ID del mensaje a citar (respuesta). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos. Posibles errores: reply_message_not_found, reply_message_instance_mismatch.
​
replyPrivate
boolean
predeterminado:"false"
Cuando es true y replyTo apunta a un mensaje originado en un grupo, la respuesta se redirige al chat privado del autor original (manteniendo la cita). Ignorado si el mensaje original no es de un grupo.
​
mention
string[]
Lista de números (o JIDs) a mencionar. Solo en chats de grupo (@g.us). Para aparecer como enlace clicable, incluye @5511... en message (subtítulo). Sin eso, se vuelven menciones ocultas (solo notifican).
​
mentionAll
boolean
predeterminado:"false"
Cuando es true, menciona a todos los miembros del grupo (excepto la propia instancia). Equivalente a @everyone. Solo en chats de grupo.
​
source
string
predeterminado:"api"
Identificador de origen para trazabilidad (p. ej., crm, bot-suporte, n8n). Guardado en el registro del mensaje en la base de datos y propagado a los webhooks. Cuando se omite, el default es "api".

​
Notas

  • delay es en segundos, no milisegundos. Un valor de 3 = 3 segundos de “escribiendo”.
  • Para mediaType: "audio", isVoice asume true automáticamente cuando el campo se omite. Para enviar como pista musical, debes enviar explícitamente isVoice: false.
  • La mediaUrl debe ser accesible públicamente. URLs con autenticación, sesiones o protección anti-bot comúnmente fallan con media_download_failed.
  • Cuando mimeType no se proporciona, el servidor lo detecta desde los primeros bytes de la descarga (net/http + sniff). En casos raros (extensiones atípicas), proporcionarlo manualmente evita problemas.
  • Para números BR (que comienzan con 55), el servicio prueba automáticamente variaciones con y sin el 9° dígito.
  • mention y mentionAll son exclusivos de grupos. Si se envían a un DM/canal, la respuesta es 400 Mentions are only supported in group chats.
  • El campo duration (audio) es informativo, whatsmeow aún calcula su propio valor desde el archivo. Útil cuando el servidor no puede inferirlo.
  • El campo waveform es opcional y consultivo: si se omite, el servidor genera una waveform estándar para PTT.

​
Errores

HTTPStatus internoMensaje
400—Instance name is required
400—Invalid request body: <detail>
400—Number is required
400—MediaType is required
400—MediaURL is required
400—MediaType must be one of: image, video, document, audio
400invalid_numberInvalid phone number format: <detail>
400mentions_not_supportedMentions are only supported in group chats
400media_download_failedFailed to download media: <reason>
400media_validation_failedInvalid media file: <reason>
400unsupported_media_typeUnsupported media type: <mime>
500media_upload_failedFailed to upload media to WhatsApp servers
500send_failedFailed to send message: <reason>
404—Instance not found
503disconnectedInstance is not connected to WhatsApp
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "MediaURL is required" }
}