Enviar Mídia - RyzeAPI

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 ou de uma string base64. A origem pode ser informada em mediaUrl (que aceita tanto a URL quanto o base64 da mídia) ou no campo mediaBase64, envie um ou outro, nunca os dois. 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 (quando URL) ou decodifica o base64, 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!"
  }'

Imagem por base64

Em vez de uma URL, envie o conteúdo da mídia em base64. Você pode colocar o base64 no próprio mediaUrl (com ou sem prefixo data URI data:image/jpeg;base64,) ou no campo dedicado mediaBase64. Como não há URL para inferir o nome/tipo, recomenda-se informar mimeType (e 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":     "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

Origem da mídia: uma URL pública do arquivo ou o base64 da mídia (com data URI data:<mime>;base64,... ou base64 cru). Quando é URL, precisa ser acessível publicamente (sem autenticação) e o servidor faz o download. Obrigatório informar mediaUrl ou mediaBase64 (nunca os dois).

mediaBase64

string

Base64 da mídia (alternativa ao mediaUrl), com data URI data:<mime>;base64,... ou base64 cru. Não pode ser usado junto com mediaUrl, envie um ou outro. Como não há URL, recomenda-se informar mimeType (e fileName para documentos).

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 mídia pode vir por URL ou base64. Use mediaUrl (que aceita URL ou base64) ou mediaBase64, enviar os dois retorna 400 use either mediaUrl or mediaBase64, not both; não enviar nenhum retorna 400 mediaUrl or mediaBase64 is required.
Quando mediaUrl é uma URL, precisa ser publicamente acessível. URLs com autenticação, sessão ou proteção contra bots costumam falhar com media_download_failed.
Para envio em base64, informar mimeType é recomendado (não há URL para inferir o tipo). O base64 aceita data URI (data:<mime>;base64,...) ou base64 cru.
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

HTTP	Status interno	Mensagem
400	,	`Instance name is required`
400	,	`Invalid request body: <detalhe>`
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: <detalhe>`
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`

Envelope de erro:

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

​Descrição

​Exemplos

​Imagem por URL

​Imagem por base64

​Áudio de voz (PTT)

​Documento (PDF) com fileName

​Vídeo com legenda e delay

​Imagem em grupo com reply e menção

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

Imagem por URL

Imagem por base64

Áudio de voz (PTT)

Documento (PDF) com `fileName`

Vídeo com legenda e delay

Imagem em grupo com reply e menção

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros