Send Bulk Message

Bulk WhatsApp Message Upload API

This API allows you to send or schedule bulk WhatsApp messages using an Excel (.xlsx) or CSV (.csv) file.
Each row in the file represents one message, and can contain the recipient’s WhatsApp number, text message, and optional media URL (image, video, document).

It supports:

✅ Per-message delay settings
✅ Batch controls
✅ Scheduling future campaigns

Internally, it uses the Baileys WhatsApp Web API for message delivery.

🔗 Endpoint

POST https://api.walytic.com/api/bulk/:sessionId/upload

📮 Request Type

POST (multipart/form-data)

🔐 Required Headers

Header	Type	Required	Description
`x-api-key`	`String`	✅ Yes	Your Walytic API Key (from dashboard).
`Content-Type`	`String`	✅ Yes	Must be `multipart/form-data`.

🧾 Form Data Fields

Field	Type	Required	Description
`file`	`File`	✅ Yes	Excel or CSV file containing the bulk message data.
`campaignName`	`String`	Optional	Name for the campaign (default: `'Untitled Campaign'`).
`bulkMessage`	`String`	Optional	Default message if no `message` column is present in file.
`delaySettings`	`JSON`	Optional	Delay configuration between messages. Example: `{"delayEveryCount":5,"delayEverySec":30,"delayBeforeFrom":2,"delayBeforeTo":5}`
`scheduledTime`	`String`	Optional	ISO date-time for scheduling campaign (e.g. `2025-10-10T15:30:00`).

🧩 Example Excel / CSV Format

number	message	mediaUrl
919876543210	Hello from Walytic!	https://example.com/image.jpg
919812345678	Get 20% off today!
919898989898	Happy Diwali 🎉	https://example.com/diwali.png

🧑‍💻 Example Node.js Integration

const fs = require("fs");
const axios = require("axios");
const FormData = require("form-data");

async function uploadBulkCampaign() {
  const formData = new FormData();
  formData.append("file", fs.createReadStream("./contacts.xlsx"));
  formData.append("campaignName", "Diwali Campaign");
  formData.append("bulkMessage", "Happy Diwali from Walytic!");
  formData.append(
    "delaySettings",
    JSON.stringify({
      delayEveryCount: 5,
      delayEverySec: 20,
      delayBeforeFrom: 1,
      delayBeforeTo: 3,
    })
  );
  // Optional scheduling
  // formData.append("scheduledTime", "2025-10-10T15:30:00");

  try {
    const response = await axios.post(
      "https://api.walytic.com/api/bulk/919876543210/upload",
      formData,
      {
        headers: {
          ...formData.getHeaders(),
          "x-api-key": "YOUR_API_KEY",
        },
      }
    );
    console.log("✅ Campaign Uploaded:", response.data);
  } catch (error) {
    console.error("❌ Upload Failed:", error.response?.data || error.message);
  }
}

uploadBulkCampaign();

🧾 Example Request (cURL)

$curl -X POST https://api.walytic.com/api/bulk/919876543210/upload \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@contacts.csv" \
-F "campaignName=Diwali Campaign" \
-F "bulkMessage=Happy Diwali from Walytic!" \
-F 'delaySettings={"delayEveryCount":5,"delayEverySec":20,"delayBeforeFrom":1,"delayBeforeTo":3}'

✅ Example Response (Success)

{
  "success": true,
  "campaignId": "66f9e7bcd31e2b11a63e1b99",
  "message": "Campaign uploaded successfully and queued for processing."
}

❌ Example Response (Error)

{
  "error": "Failed to process file",
  "details": "Invalid file format or unreadable content"
}

⏰ Example Delay Configuration

Field	Description
`delayEveryCount`	Number of messages after which delay applies (e.g. every 5 messages).
`delayEverySec`	Duration (in seconds) of each batch delay.
`delayBeforeFrom`	Minimum random delay (in seconds) before each message.
`delayBeforeTo`	Maximum random delay (in seconds) before each message.

Example: A delay configuration of
{"delayEveryCount":5,"delayEverySec":20,"delayBeforeFrom":1,"delayBeforeTo":3}
means: every 5 messages, pause 20 seconds, and randomly wait 1–3 seconds between individual sends.

🕒 Example Response (Scheduled Campaign)

{
  "success": true,
  "campaignId": "66fa001a8b16f7e12cbd55e3",
  "message": "Campaign scheduled for 2025-10-10T15:30:00"
}

📊 Fetch All Campaigns for a Session

Endpoint:

GET https://api.walytic.com/api/bulk/:sessionId/all

Description:
Fetch all campaigns created under a specific WhatsApp session.

📥 Example Request

$curl -X GET https://api.walytic.com/api/bulk/919876543210/all \
-H "x-api-key: YOUR_API_KEY"

📦 Example Response

[
  {
    "_id": "66f9e7bcd31e2b11a63e1b99",
    "name": "Diwali Campaign",
    "status": "completed",
    "total": 200,
    "delivered": 198,
    "createdAt": "2025-10-09T10:00:00Z"
  },
  {
    "_id": "66fa001a8b16f7e12cbd55e3",
    "name": "New Year Offer",
    "status": "scheduled",
    "total": 500,
    "delivered": 0,
    "createdAt": "2025-10-10T12:00:00Z"
  }
]

⚙️ How It Works Internally (For Developers)

The uploaded file is parsed (using xlsx or csv-parser).
Each row is converted into a message job with number, message, and media (if provided).
Jobs are queued and sent through Baileys sockets.
Delay settings are applied between batches and messages.
Webhooks are triggered per message for:
- message_sent
- message_failed
- campaign_completed
All campaign details are stored in MongoDB.

📡 Example Webhook Events

✅ Message Sent

{
  "event": "message_sent",
  "campaignId": "66f9e7bcd31e2b11a63e1b99",
  "to": "919876543210",
  "status": "sent",
  "timestamp": 1734925401
}

🎯 Campaign Completed

{
  "event": "campaign_completed",
  "campaignId": "66f9e7bcd31e2b11a63e1b99",
  "status": "completed",
  "delivered": 198,
  "failed": 2
}

🧭 Example Use Cases

✅ Marketing campaigns
✅ Customer engagement workflows
✅ Product announcements
✅ Festival greetings automation
✅ Scheduled reminders / alerts