> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="instanceName" type="string" required>
  The name of your WhatsApp instance that you created
</ParamField>

### Request Body

<Note>
  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
</Note>

<ParamField body="number" type="string" required>
  The recipient's WhatsApp number in international format (without + symbol)

  Example: `5511999999999` for a Brazilian number
</ParamField>

<ParamField body="mediatype" type="string" required>
  The type of media being sent

  Options: `image`, `document`, `video`, `audio`
</ParamField>

<ParamField body="media" type="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...`
</ParamField>

<ParamField body="fileName" type="string" optional>
  The filename for the media (required for base64 documents)

  Example: `document.pdf`
</ParamField>

<ParamField body="caption" type="string" optional>
  A caption or description for the media
</ParamField>

<ParamField body="mimetype" type="string" optional>
  The MIME type of the media file

  Examples: `image/jpeg`, `video/mp4`, `application/pdf`
</ParamField>

<ParamField body="delay" type="integer" optional>
  Delay before sending the message in milliseconds

  Example: `1000` for 1 second delay
</ParamField>

<ParamField body="quoted" type="object" optional>
  Quote a previous message by providing its key and message object

  <expandable title="quoted properties">
    <ParamField body="quoted.key" type="object" required>
      <expandable title="key properties">
        <ParamField body="quoted.key.id" type="string" required>
          The message ID to quote
        </ParamField>

        <ParamField body="quoted.key.remoteJid" type="string" optional>
          The JID of the chat where the message was sent
        </ParamField>

        <ParamField body="quoted.key.fromMe" type="boolean" optional>
          Whether the quoted message was sent by you
        </ParamField>
      </expandable>
    </ParamField>

    <ParamField body="quoted.message" type="object" required>
      The original message object being quoted
    </ParamField>
  </expandable>
</ParamField>

<ParamField body="mentionsEveryOne" type="boolean" optional>
  Mention all participants in a group

  Default: `false`
</ParamField>

<ParamField body="mentioned" type="array" optional>
  Array of phone numbers to mention. Each number should be a numeric string.

  Example: `["5511999999999", "5511888888888"]`
</ParamField>

### Response

<ResponseField name="key" type="object">
  Message key information

  <expandable title="key properties">
    <ResponseField name="key.remoteJid" type="string">
      The JID of the recipient
    </ResponseField>

    <ResponseField name="key.fromMe" type="boolean">
      Always true for sent messages
    </ResponseField>

    <ResponseField name="key.id" type="string">
      Unique message identifier
    </ResponseField>
  </expandable>
</ResponseField>

<ResponseField name="message" type="object">
  The sent message object containing the media and metadata
</ResponseField>

<ResponseField name="messageTimestamp" type="string">
  Unix timestamp when the message was sent
</ResponseField>

<ResponseField name="status" type="string">
  Message status (e.g., "PENDING", "SENT")
</ResponseField>

### Code Examples

<CodeGroup>
  ```bash cURL - URL theme={null}
  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!"
    }'
  ```

  ```bash cURL - File Upload theme={null}
  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"
  ```

  ```javascript JavaScript - URL theme={null}
  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);
  ```

  ```javascript JavaScript - File Upload theme={null}
  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);
  ```

  ```python Python - URL theme={null}
  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())
  ```

  ```python Python - File Upload theme={null}
  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 PHP - URL theme={null}
  <?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;
  ?>
  ```
</CodeGroup>

### Advanced Examples

<Accordion title="Send image with URL">
  ```json theme={null}
  {
    "number": "5511999999999",
    "mediatype": "image",
    "media": "https://example.com/photo.jpg",
    "caption": "Beautiful sunset photo"
  }
  ```
</Accordion>

<Accordion title="Send PDF document with base64">
  ```json theme={null}
  {
    "number": "5511999999999",
    "mediatype": "document",
    "media": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC...",
    "fileName": "contract.pdf",
    "caption": "Here is the contract for review"
  }
  ```

  <Warning>
    When sending base64-encoded documents, you must provide the `fileName` parameter.
  </Warning>
</Accordion>

<Accordion title="Send video with mentions">
  ```json theme={null}
  {
    "number": "5511999999999-1234567890@g.us",
    "mediatype": "video",
    "media": "https://example.com/video.mp4",
    "caption": "Check this out @5511888888888!",
    "mentioned": ["5511888888888"]
  }
  ```
</Accordion>

## 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`

<Note>
  For audio messages that should appear as voice notes (PTT), use the [Send Audio](/api/messages/send-audio) endpoint instead.
</Note>

## Error Responses

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

<ResponseField name="status" type="number">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Error description
</ResponseField>

### 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         |