Skip to main content
POST
/
api
/
message
/
media
/
:instance
Send 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 or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Sends a media file (image, video, document or audio) from a public URL. Supports message as a caption, replyTo (quote by ID), replyPrivate, mention / mentionAll (group chats only), delay (in seconds) to simulate real typing and, for audio, isVoice (PTT), duration and waveform. The server downloads the file, detects the mimeType when omitted and uploads it to the WhatsApp servers before sending.

​
Examples

​
Image by URL

Sends an image (mediaType: "image") downloaded from a public URL, with message used as the caption that appears below the photo in the 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!"
  }'

​
Voice audio (PTT)

When mediaType: "audio" and isVoice is omitted, the server defaults to true (voice/PTT message). To send as a “regular” audio (a music track, for example), pass 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
  }'

​
Document (PDF) with fileName

Sends a PDF as a document. fileName (Contract-2026.pdf) sets the name displayed in the attachment card and message appears as accompanying text. Without fileName, WhatsApp shows a generic name. 
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 with caption and delay

Sends an MP4 video with the caption “Check out this video!” and delay: 3, the server sends the “typing…” indicator for 3 seconds before firing the video, simulating real typing. 
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
  }'

​
Image in group with reply and mention

Sends an image in a group (@g.us), quoting a previous message via replyTo and mentioning a member via the mention array. @5511888888888 in the caption becomes clickable and triggers a notification for the tagged user. 
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"]
  }'

​
Success response

The messageType echoes the mediaType you sent (image, video, document or audio). The metadata resolved by the upload appears in mediaUrl (URL re-issued for mmg.whatsapp.net), mediaMimeType and mediaSize. For PTT audio, the server also returns mediaDuration when it can compute it.
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"
    }
  }
}
For mediaType: "document", fileName appears in the card. For mediaType: "audio" with isVoice: true, the message is delivered as PTT (waveform + microphone icon). For “regular” audio (a music track), use isVoice: false.

​
Path parameters

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
number
string
required
Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
mediaType
string
required
One of: image, video, document, audio. Determines how WhatsApp renders the message.
​
mediaUrl
string
required
Public URL of the file. The server downloads it and uploads it to the WhatsApp servers before sending. The URL must be publicly accessible (no authentication).
​
message
string
Media caption. For mediaType: "document", it appears as accompanying text. Optional for all types.
​
mimeType
string
File MIME type (e.g., image/jpeg, application/pdf). When omitted, the server detects it automatically from the download.
​
fileName
string
File name displayed in the card. Recommended for mediaType: "document", without it, WhatsApp shows a generic name.
​
isVoice
boolean
default:"true (for audio)"
Applies only to mediaType: "audio". When true, the message is delivered as PTT (voice message, with a waveform). When false, it is delivered as regular audio (a music track). When the field is omitted on audio, the server assumes true.
​
duration
uint32
Audio duration in seconds. Applies only to mediaType: "audio". Optional, when omitted, the server tries to detect it automatically.
​
waveform
byte[]
Pre-computed audio waveform (PTT). Optional, when omitted, the server automatically generates a default waveform. Applies only to mediaType: "audio" with isVoice: true.
​
delay
int
default:"0"
Time in seconds to wait before sending. During the interval, the server sends the “typing…” indicator to the recipient and fires “paused” before the actual send.
​
replyTo
string
ID of the message to be quoted (reply). The original message must belong to the same instance and have been saved in the database. Possible errors: reply_message_not_found, reply_message_instance_mismatch.
​
replyPrivate
boolean
default:"false"
When true and replyTo points to a message originating from a group, the reply is redirected to the original author’s private chat (keeping the quote). Ignored if the original message is not from a group.
​
mention
string[]
List of numbers (or JIDs) to mention. Group chats only (@g.us). To appear as a clickable link, include @5511... in message (caption). Without that, they become hidden mentions (notify only).
​
mentionAll
boolean
default:"false"
When true, mentions every group member (except the instance itself). Equivalent to @everyone. Group chats only.
​
source
string
default:"api"
Origin identifier for traceability (e.g., crm, bot-suporte, n8n). Saved on the message record in the database and propagated to webhooks. When omitted, defaults to "api".

​
Notes

  • delay is in seconds, not milliseconds. A value of 3 = 3 seconds of “typing”.
  • For mediaType: "audio", isVoice defaults to true automatically when the field is omitted. To send as a music track, you must explicitly send isVoice: false.
  • The mediaUrl must be publicly accessible. URLs with authentication, sessions or bot protection commonly fail with media_download_failed.
  • When mimeType is not provided, the server detects it from the first bytes of the download (net/http + sniff). In rare cases (atypical extensions), providing it manually avoids issues.
  • For BR numbers (starting with 55), the service automatically tries variations with and without the 9th digit.
  • mention and mentionAll are exclusive to groups. If sent to a DM/channel, the response is 400 Mentions are only supported in group chats.
  • The duration field (audio) is informational, whatsmeow still computes its own value from the file. Useful when the server cannot infer it.
  • The waveform field is optional and advisory: if omitted, the server generates a standard waveform for PTT.

​
Errors

HTTPInternal statusMessage
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
Error envelope: 
{
  "success": false,
  "error": { "message": "MediaURL is required" }
}