Jump to section

Send Media

Send images, videos, audio, and documents via the API.

POST

/api/v1/messages/media

Use plain phone numbers in to (same as text messages). The API normalizes the number to a WhatsApp chat id internally.

Media Request Parameters

Parameter	Type	Required	Description
`to`	string	Yes	Recipient phone number with country code (e.g., `260971000000`)
`file`	file	Yes	Media file to upload (max 20 MB)
`caption`	string	No	Optional caption text for supported media
`send_as_document`	boolean	No	When true, sends media as a document attachment

Request Overview

POST /api/v1/messages/media
Content-Type: multipart/form-data

to=260971000000
caption=Invoice attached
send_as_document=1
file=@/path/to/invoice.pdf

Examples and Response

Make sure to format your request as multipart/form-data.

Success Response (201)

Wait for the upload to complete before closing the connection.

Code Example

$response = Http::withToken('YOUR_API_KEY')
    ->attach('file', file_get_contents('/path/to/invoice.pdf'), 'invoice.pdf')
    ->post('https://wapi.michotech.me/api/v1/messages/media', [
        'to' => '260971000000',
        'caption' => 'Invoice attached',
        'send_as_document' => '1',
    ]);

curl https://wapi.michotech.me/api/v1/messages/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "to=260971000000" \
  -F "caption=Invoice attached" \
  -F "send_as_document=1" \
  -F "file=@/path/to/invoice.pdf;type=application/pdf"

const form = new FormData();
form.append('to', '260971000000');
form.append('caption', 'Invoice attached');
form.append('send_as_document', '1');
form.append('file', fileInput.files[0]);

const response = await fetch('https://wapi.michotech.me/api/v1/messages/media', {
    method: 'POST',
    headers: { Authorization: 'Bearer YOUR_API_KEY' },
    body: form
});

import requests

with open('/path/to/invoice.pdf', 'rb') as f:
    response = requests.post(
        'https://wapi.michotech.me/api/v1/messages/media',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        data={
            'to': '260971000000',
            'caption': 'Invoice attached',
            'send_as_document': '1'
        },
        files={'file': ('invoice.pdf', f, 'application/pdf')}
    )

Success Response (201)

{
  "data": {
    "message_id": "3EB0A0B4F3...",
    "status": "sent",
    "chat_id": "260971000000@c.us",
    "type": "document",
    "created_at": "2026-03-08T10:30:00+00:00"
  }
}

Error Responses

{
  "message": "The file field is required.",
  "errors": {
    "file": ["The file field is required."]
  }
}

{
  "error": {
    "code": "SESSION_NOT_CONNECTED",
    "message": "WhatsApp session is not connected.",
    "status": 422
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthenticated or invalid API key.",
    "status": 401
  }
}