Send Media Message

Send a media message (image, video, audio, and document) via WhatsApp

📌

Important | 24-Hour Customer (Service Window)
Media messages are subject to Meta's customer service window policy. You can only send free-form text messages within 24 hours of the customer's last message to your business. This window starts or refreshes whenever the customer messages or calls you. After this 24-hour window expires, the message will not be delivered. Use approved template messages for communication beyond the 24-hour window.

Required Scope

messages:send

Merge Fields

You can use merge fields in the message text that will be replaced with actual contact data:

@{contact_first_name} — Contact's first name

@{contact_last_name} — Contact's last name

@{contact_email} — Contact's email

@{contact_phone} — Contact's phone number

Auto-Contact Creation

If no contact_id is provided and the phone number doesn't match an existing contact:

A new contact is auto-created with the phone number

Requires default lead status, source, and assignee configured in Application settings

Subject to the tenant's contact limit (returns FEATURE_LIMIT_EXCEEDED if exceeded)

Media Type Constraints

Images: Max 5MB (JPEG, PNG, WebP)

Videos: Max 16MB (MP4, 3GPP)

Audio: Max 16MB (MP3, AAC, AMR, OGG)

Documents: Max 100MB (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT)

Media can be provided as a direct file upload 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.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

Example

{
    "success": true,
    "data": {
        "message_id": "string",
        "contact_id": 0,
        "phone": "string",
        "media_type": "string",
        "media_url": "string",
        "caption": "string",
        "filename": "string",
        "status": "string",
        "sent_at": "string",
        "chat_id": 0,
        "chat_message_id": 0
    },
    "meta": {
        "request_id": "string",
        "timestamp": "string"
    }
}

🟠401UNAUTHORIZED

🟠403INSUFFICIENT_SCOPE

🟠403FEATURE_LIMIT_EXCEEDED

🟠404NOT_FOUND

🟠422VALIDATION_ERROR

🟠422WHATSAPP_NOT_CONFIGURED

🟠429RATE_LIMIT_EXCEEDED

🔴500INTERNAL_ERROR

🔴500MESSAGE_SEND_FAILED

Send Media Message

Send a media message (image, video, audio, and document) via WhatsApp#

Required Scope#

Merge Fields#

Auto-Contact Creation#

Media Type Constraints#