Send Media Message

📸 Send WhatsApp Media Message API

Send images, videos, audio, or documents (PDFs, Word files, etc.) to any valid WhatsApp number using your connected session.
This endpoint is part of the Baileys REST Mongo API and is secured via Hybrid Authentication, supporting both x-api-key and JWT tokens.

Internally, it uses the Baileys WhatsApp Web library to deliver media messages and automatically triggers configured webhook events for delivery confirmations or errors.

🔗 Endpoint

POST https://api.walytic.com/api/whatsapp/:sessionId/send-media

🔐 Required Headers

📤 Required Fields (Request Body)

⚠️ The file URL must be publicly accessible (Walytic’s servers must be able to fetch it).
If uploading from your backend, use the /api/media/upload endpoint to generate a valid fileUrl.

🧩 Example Request (Node.js)

const axios = require("axios");

async function sendMediaMessage() {
  try {
    const response = await axios.post(
      "https://api.walytic.com/api/whatsapp/session-919876543210/send-media",
      {
        number: "919812345678",
        fileUrl: "https://cdn.walytic.com/uploads/invoice-1234.pdf",
        caption: "Here’s your invoice 📄"
      },
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
        }
      }
    );

    if (response.data.success) {
      console.log("✅ Media message sent successfully!");
      console.log(response.data);
    } else {
      console.log("❌ Error:", response.data.error);
    }
  } catch (error) {
    console.error("Request failed:", error.response?.data || error.message);
  }
}

sendMediaMessage();

🧾 Example Request (cURL)

$curl -X POST https://api.walytic.com/api/whatsapp/session-919876543210/send-media \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "number": "919812345678",
  "fileUrl": "https://cdn.walytic.com/uploads/invoice-1234.pdf",
  "caption": "Here’s your invoice 📄"
}'

📦 Example Response (✅ Success)

{
  "success": true,
  "message": "Media message sent successfully",
  "mediaType": "document",
  "data": {
    "messageId": "BAE6F8910AB94C13",
    "to": "919812345678",
    "sessionId": "session-919876543210",
    "fileUrl": "https://cdn.walytic.com/uploads/invoice-1234.pdf",
    "caption": "Here’s your invoice 📄",
    "timestamp": 1734902336
  }
}

❌ Example Response (Error)

{
  "success": false,
  "error": "Missing phone number or file URL"
}

or

{
  "success": false,
  "error": "Invalid or disconnected session"
}

📡 Webhook Events (for Media Message)

Once a media message is sent or delivered, your configured webhook URL will automatically receive updates.

✅ Media Message Sent Event

{
  "event": "media_message_sent",
  "sessionId": "session-919876543210",
  "to": "919812345678",
  "mediaType": "document",
  "fileUrl": "https://cdn.walytic.com/uploads/invoice-1234.pdf",
  "caption": "Here’s your invoice 📄",
  "status": "sent",
  "timestamp": 1734902336
}

📬 Media Message Delivered Event

{
  "event": "media_message_delivered",
  "sessionId": "session-919876543210",
  "to": "919812345678",
  "messageId": "BAE6F8910AB94C13",
  "status": "delivered",
  "timestamp": 1734902440
}

🔴 Media Message Failed Event

{
  "event": "media_message_failed",
  "sessionId": "session-919876543210",
  "to": "919812345678",
  "error": "Recipient not found or WhatsApp not connected",
  "timestamp": 1734902339
}

🧠 Internal Workflow (For Developers)

1. The request is received by
   controllers/whatsappController.js → sendMedia().

2. The system validates session ownership and quota.

3. The media file is fetched from fileUrl using Axios.

4. The Baileys socket sends the message using:

   sock.sendMessage(`${number}@s.whatsapp.net`, { image/video/document, caption });
   

5. Message metadata is stored in MongoDB (Message model).

6. Webhook (if configured) is triggered with real-time updates.

🔒 Authentication Flow

The Hybrid Auth middleware automatically validates both and attaches req.userId for quota tracking and session ownership.

⚙️ Notes

• Works only if the target WhatsApp session is connected (check /api/whatsapp/:sessionId/status).

• Supports images, videos, audio, and documents (PDF, DOCX, ZIP, etc.).

• File must be accessible via a public HTTPS URL.

• Captions are optional for images/videos/documents.

• Quota consumption: each media message counts as 1 message in your subscription usage.

• Delivery and read receipts are tracked automatically via Baileys.