Kirim Pesan dengan Device Rotator

Distribusi pesan ke beberapa device WhatsApp sekaligus untuk menghindari risiko banned. Sangat cocok untuk integrasi e-commerce, blast volume tinggi, atau bisnis yang butuh stabilitas pengiriman.

HTTP REQUEST

POST https://api.starsender.online/api/send/rotator

Header Parameters

Parameter	Required	Description
Authorization	true	User Token / API Key akun Anda. Berbeda dengan Device API Key. Dapatkan di menu Pengaturan → API Key Akun

Body Parameters

Parameter	Required	Description
mode	false	Mode distribusi: round_robin (default) atau batch
devices	true	Array of device dengan limit pesan per device
messages	true	Array of message yang akan dikirim

Mode Distribusi

Mode	Cara Kerja
round_robin	Pesan dibagi bergantian: msg 1 → Device A, msg 2 → Device B, msg 3 → Device A, dst. Direkomendasikan untuk distribusi merata.
batch	Device A diisi sampai limit habis, baru lanjut Device B, dst. Cocok untuk warming-up bertahap.

Object: device

Parameter	Required	Description
device_id	optional*	ID device (numeric). Lihat di menu Device.
device_key	optional*	Device API Key (string). Alternatif dari device_id.
limit	true	Jumlah maksimum pesan yang akan dikirim oleh device ini

*Salah satu dari device_id atau device_key wajib diisi.

Object: message

Parameter	Required	Description
to	true	Nomor tujuan (format 08xxx atau 628xxx)
messageType	false	text (default) atau media
body	false	Isi pesan
file	false	URL media (jika messageType=media)
delay	false	Delay sebelum kirim (detik)
schedule	false	Jadwal pengiriman dalam unix milliseconds

Implementasi dengan PHP

kirim-rotator.php

<?php

$payload = [
  "mode" => "round_robin",
  "devices" => [
    ["device_id" => 1641, "limit" => 50],
    ["device_id" => 42800, "limit" => 50],
    ["device_id" => 53921, "limit" => 50],
  ],
  "messages" => [
    [
      "to" => "08123456789",
      "body" => "Halo Andi, terima kasih sudah order!",
      "delay" => 30,
    ],
    [
      "to" => "08987654321",
      "body" => "Halo Budi, ini bukti transfer Anda",
      "messageType" => "media",
      "file" => "https://example.com/invoice.jpg",
      "delay" => 30,
    ],
  ],
];

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.starsender.online/api/send/rotator',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: YOUR_USER_API_KEY',
  ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Implementasi dengan Node.js

kirim-rotator.js

const axios = require('axios');

const payload = {
  mode: 'round_robin',
  devices: [
    { device_id: 1641, limit: 50 },
    { device_id: 42800, limit: 50 },
    { device_id: 53921, limit: 50 },
  ],
  messages: [
    {
      to: '08123456789',
      body: 'Halo Andi, terima kasih sudah order!',
      delay: 30,
    },
    {
      to: '08987654321',
      body: 'Halo Budi, ini bukti transfer Anda',
      messageType: 'media',
      file: 'https://example.com/invoice.jpg',
      delay: 30,
    },
  ],
};

axios.post('https://api.starsender.online/api/send/rotator', payload, {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'YOUR_USER_API_KEY',
  },
})
.then(res => console.log(res.data))
.catch(err => console.error(err.response.data));

Implementasi dengan cURL

kirim-rotator.sh

curl -X POST "https://api.starsender.online/api/send/rotator" \
  -H "Authorization: YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "round_robin",
    "devices": [
      {"device_id": 1641, "limit": 50},
      {"device_id": 42800, "limit": 50}
    ],
    "messages": [
      {"to": "08123456789", "body": "Halo Andi"},
      {"to": "08987654321", "body": "Halo Budi"}
    ]
  }'

Respon API (Sukses)

{
    "success": true,
    "message": "Distributed 2 messages to 2 devices via round_robin mode",
    "data": {
        "mode": "round_robin",
        "total_messages": 2,
        "distribution": [
            {
                "device_id": 1641,
                "device_name": "server wa",
                "count": 1,
                "limit": 50
            },
            {
                "device_id": 42800,
                "device_name": "marketing 1",
                "count": 1,
                "limit": 50
            }
        ],
        "messages": [
            {
                "message_id": 265612345,
                "to": "628123456789",
                "device_id": 1641,
                "device_name": "server wa"
            },
            {
                "message_id": 265612346,
                "to": "628987654321",
                "device_id": 42800,
                "device_name": "marketing 1"
            }
        ]
    }
}

Respon API (Error)

Authorization gagal

{
    "success": false,
    "message": "Invalid API Key",
    "data": {}
}

Device tidak ditemukan / bukan milik user

{
    "success": false,
    "message": "Device not found or not owned by user: 9999",
    "data": {}
}

Device disconnected

{
    "success": false,
    "message": "Device server wa (id=1641) is not connected",
    "data": {}
}

Pesan melebihi total kapasitas

{
    "success": false,
    "message": "Messages (200) exceed total capacity (150). Add more devices or increase limits.",
    "data": {
        "total_messages": 200,
        "total_capacity": 150
    }
}

Tips Best Practice

1. Limit per device: Set 50-100 pesan/device/hari untuk akun normal. Akun baru: 10-20.
2. Delay antar pesan: Selalu set field delay minimal 30 detik untuk hindari WhatsApp anti-spam.
3. Variasi pesan: Untuk mencegah deteksi template, variasikan isi pesan dengan random text seperti (Halo|Hi|Hai) atau personalisasi {nama}.
4. Multi-device: Pakai minimal 3 device untuk distribusi optimal. Lebih banyak device = risiko banned lebih kecil.
5. Validasi nomor: Pastikan format nomor tujuan benar (08xxx atau 628xxx).
6. Schedule: Pakai field schedule (unix millis) untuk kirim pesan di waktu tertentu.

Use Case: Integrasi E-commerce (Scalev/Shopify)

Saat ada order baru di platform e-commerce Anda, panggil endpoint ini untuk kirim konfirmasi otomatis ke customer dengan distribusi multi-device:

// Webhook receiver: trigger saat ada order baru
$customers_to_notify = [
  ["nomor" => "08111222333", "nama" => "Andi", "produk" => "Kemeja Batik"],
  ["nomor" => "08111222334", "nama" => "Budi", "produk" => "Sepatu Casual"],
  // ... bisa ratusan
];

$messages = [];
foreach ($customers_to_notify as $c) {
    $messages[] = [
        "to" => $c["nomor"],
        "body" => "Halo {$c['nama']}, terima kasih sudah order {$c['produk']}! Pesanan akan diproses 1x24 jam.",
        "delay" => 30,
    ];
}

$payload = [
    "mode" => "round_robin",
    "devices" => [
        ["device_id" => 1641, "limit" => 100],
        ["device_id" => 42800, "limit" => 100],
        ["device_id" => 53921, "limit" => 100],
    ],
    "messages" => $messages,
];

// Kirim via API dengan Authorization User Token

FAQ

Q: Apa bedanya endpoint ini dengan /api/send biasa? A: /api/send kirim 1 pesan via 1 device (pakai Device API Key). Endpoint /api/send/rotator kirim banyak pesan terdistribusi ke beberapa device sekaligus (pakai User API Key).

Q: Apakah field delay & schedule masih jalan? A: Ya. Setiap pesan tetap di-process oleh sistem antrian StarSender, jadi field delay (detik) dan schedule (unix millis) tetap berfungsi.

Q: Maksimum berapa pesan per request? A: Tidak ada batas teknis di endpoint, tapi disarankan max 500 pesan per request untuk hindari timeout. Untuk volume lebih besar, split jadi beberapa batch.

Q: Bagaimana cara cek status pengiriman per pesan? A: Response berisi message_id per pesan. Pakai endpoint GET /api/messages/:id untuk cek status pengiriman individual.

Q: Apakah pesan yang gagal akan di-retry? A: Ya, sistem antrian StarSender akan retry pesan gagal hingga 3 kali. Pesan yang tetap gagal akan tampil di menu Pesan Keluar → List Pesan dengan status failed.