Send Media Message

Send media files including images, videos, documents, and audio to WhatsApp contacts or groups. You can send media via URL, base64, or file upload.

Endpoint

POST /message/sendMedia/:instanceName

Path Parameters

instanceName

string

required

The name of your WhatsApp instance that you created

Request Body

This endpoint supports three methods for sending media:

URL: Provide a direct link to the media file
Base64: Provide the base64-encoded media content
File Upload: Use multipart/form-data to upload a file

number

string

required

The recipient’s WhatsApp number in international format (without + symbol)Example: 5511999999999 for a Brazilian number

mediatype

string

required

The type of media being sentOptions: image, document, video, audio

media

string

required

The media content as a URL or base64 string (not required when using file upload)Examples:

URL: https://example.com/image.jpg
Base64: data:image/jpeg;base64,/9j/4AAQSkZJRg...

fileName

string

The filename for the media (required for base64 documents)Example: document.pdf

caption

string

A caption or description for the media

mimetype

string

The MIME type of the media fileExamples: image/jpeg, video/mp4, application/pdf

delay

integer

Delay before sending the message in millisecondsExample: 1000 for 1 second delay

quoted

object

Quote a previous message by providing its key and message object

mentionsEveryOne

boolean

Mention all participants in a groupDefault: false

mentioned

array

Array of phone numbers to mention. Each number should be a numeric string.Example: ["5511999999999", "5511888888888"]

Response

key

object

Message key information

message

object

The sent message object containing the media and metadata

messageTimestamp

string

Unix timestamp when the message was sent

status

string

Message status (e.g., “PENDING”, “SENT”)

Code Examples

curl -X POST https://your-api-url.com/message/sendMedia/my-instance \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{
    "number": "5511999999999",
    "mediatype": "image",
    "media": "https://example.com/image.jpg",
    "caption": "Check out this image!"
  }'

Advanced Examples

Send image with URL

{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://example.com/photo.jpg",
  "caption": "Beautiful sunset photo"
}

Send PDF document with base64

{
  "number": "5511999999999",
  "mediatype": "document",
  "media": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC...",
  "fileName": "contract.pdf",
  "caption": "Here is the contract for review"
}

When sending base64-encoded documents, you must provide the fileName parameter.

Send video with mentions

{
  "number": "[email protected]",
  "mediatype": "video",
  "media": "https://example.com/video.mp4",
  "caption": "Check this out @5511888888888!",
  "mentioned": ["5511888888888"]
}

Media Type Guidelines

Image

Supported formats: JPG, PNG, GIF, WEBP
Recommended size: Under 5MB
MIME types: image/jpeg, image/png, image/gif, image/webp

Video

Supported formats: MP4, 3GP, AVI, MOV
Recommended size: Under 16MB
MIME types: video/mp4, video/3gpp, video/avi, video/quicktime

Document

Supported formats: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, ZIP
Recommended size: Under 100MB
MIME types: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document

Audio

Supported formats: MP3, OGG, WAV, AAC
Recommended size: Under 16MB
MIME types: audio/mpeg, audio/ogg, audio/wav, audio/aac

For audio messages that should appear as voice notes (PTT), use the Send Audio endpoint instead.

Error Responses

Ensure the media URL is publicly accessible or the base64 string is properly formatted. Invalid media will result in a 400 Bad Request error.

status

number

HTTP status code

message

string

Error description

Common Errors

Status Code	Error Message	Solution
400	”Owned media must be a url or base64”	Provide valid URL or base64 string
400	”For base64 the file name must be informed”	Add `fileName` when sending base64 documents
401	Unauthorized	Check your API key
404	Not Found	Verify instance exists and is connected
500	Internal Server Error	Check server logs or contact support

Overview

Instance Management

Messaging

Chats

Groups

Contacts

Labels

Settings

Proxy

Send Media Message