Pular para o conteúdo principal
POST
/
api
/
message
/
media
/
:instance
Enviar Mídia
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 ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

​
Descrição

Envia uma mídia (image, video, document ou audio) a partir de uma URL pública. Suporta message como legenda (caption), replyTo (citação por ID), replyPrivate, mention / mentionAll (apenas em grupos), delay (em segundos) para simular digitação real e, para áudio, isVoice (PTT), duration e waveform. O servidor faz o download, detecta o mimeType quando omitido e faz o upload nos servidores do WhatsApp antes do envio.

​
Exemplos

​
Imagem por URL

Envia uma imagem (mediaType: "image") baixada de uma URL pública, com message usado como legenda (caption) que aparece abaixo da foto no 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://exemplo.com/foto.jpg",
    "message":   "Confere essa foto!"
  }'

​
Áudio de voz (PTT)

Quando mediaType: "audio" e isVoice é omitido, o servidor assume true por padrão (mensagem de voz/PTT). Para enviar como áudio “regular” (faixa de música, por exemplo), passe 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://exemplo.com/audio.ogg",
    "isVoice":   true
  }'

​
Documento (PDF) com fileName

Envia um PDF como documento. O fileName (Contrato-2026.pdf) define o nome exibido no card do anexo e o message aparece como texto acompanhante. Sem fileName, o WhatsApp mostra um nome 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://exemplo.com/contrato.pdf",
    "fileName":  "Contrato-2026.pdf",
    "message":   "Segue o contrato anexo."
  }'

​
Vídeo com legenda e delay

Envia um vídeo MP4 com a legenda “Olha esse vídeo!” e delay: 3, o servidor envia o indicador de “digitando…” por 3 segundos antes de disparar o vídeo, simulando uma digitação 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://exemplo.com/video.mp4",
    "message":   "Olha esse vídeo!",
    "delay":     3
  }'

​
Imagem em grupo com reply e menção

Envia uma imagem em um grupo (@g.us) citando uma mensagem anterior via replyTo e mencionando um membro pelo array mention. O @5511888888888 na caption fica clicável, gerando notificação para o usuário marcado. 
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://exemplo.com/banner.jpg",
    "message":   "Olha só @5511888888888, ficou pronto!",
    "replyTo":   "3EB08FCF27E532F1B0F5",
    "mention":   ["5511888888888"]
  }'

​
Resposta de sucesso

O messageType ecoa o mediaType enviado (image, video, document ou audio). Os metadados resolvidos pelo upload aparecem em mediaUrl (URL re-enviada para mmg.whatsapp.net), mediaMimeType e mediaSize. Para áudios PTT, o servidor também devolve mediaDuration quando consegue calcular.
200 OK
{
  "success": true,
  "message": "Media message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":     "3EB08FCF27E532F1B0F5",
    "direction":     "outgoing",
    "messageType":   "image",
    "content":       "Confere essa foto!",
    "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", o fileName aparece no card. Para mediaType: "audio" com isVoice: true, a mensagem é entregue como PTT (forma de onda + ícone de microfone). Para áudios “regulares” (faixa de música), use isVoice: false.

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: $Instance_Name).

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
number
string
obrigatório
Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
mediaType
string
obrigatório
Um de: image, video, document, audio. Determina como o WhatsApp renderiza a mensagem.
​
mediaUrl
string
obrigatório
URL pública do arquivo. O servidor faz o download e o upload nos servidores do WhatsApp antes do envio. A URL precisa ser acessível publicamente (sem autenticação).
​
message
string
Legenda (caption) da mídia. Para mediaType: "document", aparece como texto acompanhante. Opcional para todos os tipos.
​
mimeType
string
MIME type do arquivo (ex.: image/jpeg, application/pdf). Quando omitido, o servidor detecta automaticamente a partir do download.
​
fileName
string
Nome do arquivo exibido no card. Recomendado para mediaType: "document", sem ele, o WhatsApp mostra um nome genérico.
​
isVoice
boolean
padrão:"true (para audio)"
Aplicável apenas a mediaType: "audio". Quando true, a mensagem é entregue como PTT (mensagem de voz, com forma de onda). Quando false, é entregue como áudio regular (faixa de música). Quando o campo é omitido em audio, o servidor assume true.
​
duration
uint32
Duração do áudio em segundos. Aplicável apenas a mediaType: "audio". Opcional, quando omitido, o servidor tenta detectar automaticamente.
​
waveform
byte[]
Forma de onda pré-computada do áudio (PTT). Opcional, quando omitida, o servidor gera automaticamente uma forma de onda padrão. Aplicável apenas a mediaType: "audio" com isVoice: true.
​
delay
int
padrão:"0"
Tempo em segundos para aguardar antes de enviar. Durante o intervalo, o servidor envia o indicador de “digitando…” ao destinatário e dispara o “paused” antes do envio real.
​
replyTo
string
ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco. Erros possíveis: reply_message_not_found, reply_message_instance_mismatch.
​
replyPrivate
boolean
padrão:"false"
Quando true e replyTo aponta para uma mensagem originária de um grupo, a resposta é redirecionada para o privado do autor original (mantendo a citação). Ignorado se a mensagem original não for de grupo.
​
mention
string[]
Lista de números (ou JIDs) a mencionar. Apenas em grupos (@g.us). Para que apareçam como link clicável, inclua @5511... na message (caption). Sem isso, viram menções ocultas (apenas notificam).
​
mentionAll
boolean
padrão:"false"
Quando true, menciona todos os membros do grupo (exceto a própria instância). Equivale ao @todos/@everyone. Apenas em grupos.
​
source
string
padrão:"api"
Identificador de origem para rastreabilidade (ex.: crm, bot-suporte, n8n). Salvo no registro da mensagem no banco e propagado para webhooks. Quando omitido, assume "api".

​
Notas

  • delay é em segundos, não milissegundos. Valor 3 = 3 segundos de “digitando”.
  • Para mediaType: "audio", isVoice assume true automaticamente quando o campo é omitido. Para enviar como faixa de música, é necessário enviar isVoice: false explicitamente.
  • A mediaUrl precisa ser publicamente acessível. URLs com autenticação, sessão ou proteção contra bots costumam falhar com media_download_failed.
  • Quando mimeType não é informado, o servidor detecta a partir dos primeiros bytes do download (net/http + sniff). Em casos raros (extensão atípica), informar manualmente evita problemas.
  • Para números BR (começando com 55), o serviço tenta automaticamente variações com e sem o 9º dígito.
  • mention e mentionAll são exclusivos a grupos. Se enviados para DM/canal, retorna 400 Mentions are only supported in group chats.
  • O campo duration (áudio) é informativo, whatsmeow ainda calcula seu próprio valor a partir do arquivo. Útil quando o servidor não consegue inferir.
  • O campo waveform é opcional e advisory: se omitido, o servidor gera uma forma de onda padronizada para PTT.

​
Erros

HTTPStatus internoMensagem
400—Instance name is required
400—Invalid request body: <detalhe>
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: <detalhe>
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
Envelope de erro: 
{
  "success": false,
  "error": { "message": "MediaURL is required" }
}