Enviar media - RyzeAPI

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 o un string base64. La fuente se puede indicar en mediaUrl (que acepta tanto la URL como el base64 de la media) o en el campo mediaBase64, envía uno u otro, nunca ambos. 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 (cuando es URL) o decodifica el base64, 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!"
  }'

Imagen por base64

En lugar de una URL, envía el contenido de la media en base64. Puedes poner el base64 en el propio mediaUrl (con o sin el prefijo data URI data:image/jpeg;base64,) o en el campo dedicado mediaBase64. Como no hay URL para inferir el nombre/tipo, se recomienda indicar mimeType (y fileName, para documentos).

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",
    "mediaBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "mimeType":    "image/jpeg",
    "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

Fuente de la media: una URL pública del archivo o el base64 de la media (con data URI data:<mime>;base64,... o base64 crudo). Cuando es una URL, debe ser accesible públicamente (sin autenticación) y el servidor la descarga. Debes indicar mediaUrl o mediaBase64 (nunca ambos).

mediaBase64

string

Base64 de la media (alternativa a mediaUrl), con data URI data:<mime>;base64,... o base64 crudo. No se puede usar junto con mediaUrl, envía uno u otro. Como no hay URL, se recomienda indicar mimeType (y fileName para documentos).

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 media puede venir por URL o base64. Usa mediaUrl (que acepta URL o base64) o mediaBase64, enviar ambos retorna 400 use either mediaUrl or mediaBase64, not both; no enviar ninguno retorna 400 mediaUrl or mediaBase64 is required.
Cuando mediaUrl es una URL, debe ser accesible públicamente. URLs con autenticación, sesiones o protección anti-bot comúnmente fallan con media_download_failed.
Para envíos en base64, se recomienda indicar mimeType (no hay URL para inferir el tipo). El base64 acepta data URI (data:<mime>;base64,...) o base64 crudo.
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

HTTP	Status interno	Mensaje
400	,	`Instance name is required`
400	,	`Invalid request body: <detail>`
400	,	`Number is required`
400	,	`MediaType is required`
400	,	`mediaUrl or mediaBase64 is required`
400	,	`use either mediaUrl or mediaBase64, not both`
400	,	`MediaType must be one of: image, video, document, audio`
400	`invalid_number`	`Invalid phone number format: <detail>`
400	`mentions_not_supported`	`Mentions are only supported in group chats`
400	`media_download_failed`	`Failed to download media: <reason>`
400	`media_input_invalid`	`Failed to resolve media: <reason>`
400	`media_validation_failed`	`Invalid media file: <reason>`
400	`unsupported_media_type`	`Unsupported media type: <mime>`
500	`media_upload_failed`	`Failed to upload media to WhatsApp servers`
500	`send_failed`	`Failed to send message: <reason>`
404	,	`Instance not found`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

{
  "success": false,
  "error": { "message": "mediaUrl or mediaBase64 is required" }
}

​Descripción

​Ejemplos

​Imagen por URL

​Imagen por base64

​Audio de voz (PTT)

​Documento (PDF) con fileName

​Video con subtítulo y delay

​Imagen en grupo con respuesta y mención

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Imagen por URL

Imagen por base64

Audio de voz (PTT)

Documento (PDF) con `fileName`

Video con subtítulo y delay

Imagen en grupo con respuesta y mención

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores