Send Media Message
POST
/messages/media
media_file) or via URL (media_url). The file is validated for extension and size based on the media type. Files are stored locally and the URL is sent to WhatsApp Cloud API.messages:sendRequest Body (multipart/form-data)
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
phone | string | Yes | min:10, max:15 | Recipient phone number with country code |
media_type | string | Yes | in: image, document, video, audio | Type of media to send |
media_url | url | Conditional | Required if no media_file | URL of the media file |
media_file | file | Conditional | Required if no media_url | Direct file upload |
caption | string | No | max:1024 | Caption text for the media (not supported for audio) |
filename | string | No | max:255 | Display filename (used for documents) |
contact_id | integer | No | Existing contact ID |
Contact Auto-Creation Fields (optional)
| Field | Type | Description |
|---|---|---|
contact.firstname | string | First name for new contact |
contact.lastname | string | Last name for new contact |
contact.email | Email for new contact | |
contact.country | string | Country for new contact |
contact.assigned_id | integer | Staff assignment for new contact |
contact.groups | string | Comma-separated group IDs |
Media Type Constraints
| Type | Allowed Extensions | Max Size |
|---|---|---|
image | jpg, jpeg, png, webp | 5 MB |
document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv | 100 MB |
video | mp4, 3gp | 16 MB |
audio | mp3, ogg, amr, aac, opus | 16 MB |
Response Fields
| Field | Type | Description |
|---|---|---|
message_id | string | WhatsApp message ID |
contact_id | integer | Contact ID |
phone | string | Cleaned phone number |
media_type | string | Type of media sent |
media_url | string | URL where media is stored |
caption | string|null | Caption text |
filename | string|null | Display filename |
status | string | Message status (sent) |
sent_at | string | ISO 8601 send timestamp |
chat_id | integer | Internal chat interaction ID |
chat_message_id | integer | Internal chat message record ID |
Common Error Responses (All Send Endpoints)
| Status | Error Code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Invalid or missing API token |
| 403 | INSUFFICIENT_SCOPE | Token missing messages:send scope |
| 403 | FEATURE_LIMIT_EXCEEDED | Contact limit or conversation limit reached |
| 403 | CONTACT_OPTED_OUT | Contact has opted out of receiving messages |
| 404 | NOT_FOUND | Contact not found (when contact_id provided) |
| 422 | VALIDATION_ERROR | Request validation failed or missing config for auto-contact creation |
| 422 | WHATSAPP_NOT_CONFIGURED | WhatsApp not configured for this account |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests |
| 500 | MESSAGE_SEND_FAILED | Failed to send via WhatsApp API |
| 500 | INTERNAL_ERROR | Unexpected server error |
Additional Error Responses
| Status | Error Code | Description |
|---|---|---|
| 422 | INVALID_MEDIA_TYPE | Invalid media type or failed to download from URL |
| 422 | (inline) | Invalid file extension or file size exceeds limit |
Request
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/messages/media' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data'Response Response Example
{}Modified at 2026-02-25 01:06:20