Send Media Message

Send images, videos, documents, or audio files to WhatsApp contacts via Evolution API

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:

1. URL: Provide a direct link to the media file
2. Base64: Provide the base64-encoded media content
3. 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 sent

Options: 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 file

Examples: image/jpeg, video/mp4, application/pdf

delay · integer

Delay before sending the message in milliseconds

Example: 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 group

Default: 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 - URL

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!"
  }'

curl -X POST https://your-api-url.com/message/sendMedia/my-instance \
  -H "apikey: YOUR_API_KEY" \
  -F "number=5511999999999" \
  -F "mediatype=image" \
  -F "caption=Check out this image!" \
  -F "file=@/path/to/image.jpg"

const response = await fetch('https://your-api-url.com/message/sendMedia/my-instance', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    number: '5511999999999',
    mediatype: 'image',
    media: 'https://example.com/image.jpg',
    caption: 'Check out this image!'
  })
});

const data = await response.json();
console.log(data);

const formData = new FormData();
formData.append('number', '5511999999999');
formData.append('mediatype', 'image');
formData.append('caption', 'Check out this image!');
formData.append('file', fileInput.files[0]);

const response = await fetch('https://your-api-url.com/message/sendMedia/my-instance', {
  method: 'POST',
  headers: {
    'apikey': 'YOUR_API_KEY'
  },
  body: formData
});

const data = await response.json();
console.log(data);

import requests

url = 'https://your-api-url.com/message/sendMedia/my-instance'
headers = {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY'
}
payload = {
    'number': '5511999999999',
    'mediatype': 'image',
    'media': 'https://example.com/image.jpg',
    'caption': 'Check out this image!'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

import requests

url = 'https://your-api-url.com/message/sendMedia/my-instance'
headers = {
    'apikey': 'YOUR_API_KEY'
}
data = {
    'number': '5511999999999',
    'mediatype': 'image',
    'caption': 'Check out this image!'
}
files = {
    'file': open('/path/to/image.jpg', 'rb')
}

response = requests.post(url, data=data, files=files, headers=headers)
print(response.json())

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://your-api-url.com/message/sendMedia/my-instance',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode([
    'number' => '5511999999999',
    'mediatype' => 'image',
    'media' => 'https://example.com/image.jpg',
    'caption' => 'Check out this image!'
  ]),
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'apikey: YOUR_API_KEY'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

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": "[e-mail]",
  "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