Send Media Message

Send images, videos, documents, or audio files to a WhatsApp recipient. The file is fetched from the public HTTPS URL you provide and delivered to that recipient.

Endpoint

POST /whatsapp/send-media/:instance

• :instance: The name of your WhatsApp instance.

Request Body

Parameter	Type	Required	Description
recipient	string	Yes	The recipient's WhatsApp number with country code (e.g., 254123456789) or the full sender address from a webhook (e.g., 123456789012345@lid or [email protected]). Send @lid addresses exactly as received; do not format them or remove the suffix.
mediatype	string	Yes	The type of media: image, video, document, or audio.
mimetype	string	Yes	The MIME type of the file (e.g., image/jpeg, video/mp4, application/pdf).
caption	string	No	An optional caption to display with the media message.
media	string	Yes	A public HTTPS URL to the media file.
fileName	string	No	A file name shown to the recipient (e.g., invoice.pdf). Recommended for documents.

The media URL must use HTTPS

media must be a publicly accessible URL that starts with https://. Local files, Base64 strings, and plain http:// URLs are not accepted.

Supported Media Types

mediatype	Typical use	Example mimetype
image	Photos	image/jpeg, image/png
video	Videos	video/mp4
document	Files such as PDFs	application/pdf
audio	Audio files	audio/mpeg, audio/ogg

Sending voice notes

To send a native WhatsApp voice note instead of an audio file, use the Send Audio Message endpoint with voiceNote: true.

Example Payload

{
  "recipient": "254123456789",
  "mediatype": "image",
  "mimetype": "image/jpeg",
  "caption": "Check out this beautiful photo!",
  "media": "https://example.com/image.jpg",
  "fileName": "photo.jpg"
}

Examples

cURL

curl -X POST https://api.chatbreez.com/whatsapp/send-media/{instance} \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "254123456789",
    "mediatype": "image",
    "mimetype": "image/jpeg",
    "caption": "Hello with an image!",
    "media": "https://example.com/image.jpg",
    "fileName": "image.jpg"
  }'

JavaScript

const axios = require('axios');

const sendMedia = async () => {
  try {
    const response = await axios.post('https://api.chatbreez.com/whatsapp/send-media/{instance}', {
      recipient: '254123456789',
      mediatype: 'image',
      mimetype: 'image/jpeg',
      caption: 'Hello with an image!',
      media: 'https://example.com/image.jpg',
      fileName: 'image.jpg'
    }, {
      headers: {
        'X-API-Key': 'your_api_key'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

sendMedia();

Python

import requests

url = "https://api.chatbreez.com/whatsapp/send-media/{instance}"

payload = {
    "recipient": "254123456789",
    "mediatype": "image",
    "mimetype": "image/jpeg",
    "caption": "Hello with an image!",
    "media": "https://example.com/image.jpg",
    "fileName": "image.jpg"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.chatbreez.com/whatsapp/send-media/{instance}"

	payload := map[string]interface{}{
		"recipient":  "254123456789",
		"mediatype":  "image",
		"mimetype":   "image/jpeg",
		"caption":    "Hello with an image!",
		"media":      "https://example.com/image.jpg",
		"fileName":   "image.jpg",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "your_api_key")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.chatbreez.com/whatsapp/send-media/{instance}";
        String json = """
            {
              "recipient": "254123456789",
              "mediatype": "image",
              "mimetype": "image/jpeg",
              "caption": "Hello with an image!",
              "media": "https://example.com/image.jpg",
              "fileName": "image.jpg"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-API-Key", "your_api_key")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$url = 'https://api.chatbreez.com/whatsapp/send-media/{instance}';

$payload = json_encode([
    'recipient' => '254123456789',
    'mediatype' => 'image',
    'mimetype' => 'image/jpeg',
    'caption' => 'Hello with an image!',
    'media' => 'https://example.com/image.jpg',
    'fileName' => 'image.jpg',
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key',
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Response

{
  "message": "Media message queued for delivery.",
  "messageId": "3EB0C767D097B7C7C030"
}

Keep the messageId if you need to reference the message later when investigating a delivery.

Common Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "media: Media URL must use HTTPS",
    "correlationId": "abc123-def456-ghi789"
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	The request body is invalid, the media URL is not HTTPS, or the recipient is not registered on WhatsApp.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Your account is deactivated. Contact support to reactivate it.
404	NOT_FOUND	The instance does not exist.
409	CONFLICT	The instance is not connected to WhatsApp. Reconnect it and try again.
502	UPSTREAM_ERROR	WhatsApp did not acknowledge the message. Try again shortly.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our side. Try again shortly.

Next Steps

• Send Text Messages
• Send Audio Messages — audio attachments and voice notes
• Send Location Messages — share a location pin
• Send Contact Messages — share contact cards
• Send Poll Messages — create polls with up to ten options
• Check Instance Status