Mengirim

Kirim SMS massal dengan POST /v1/batches

POST/v1/batches

Kirim ke maksimal 10.000 nomor dalam satu permintaan. Seluruh biaya langsung dipotong dari saldo.

Bodi permintaan

  • toarray of stringsopsional

    Nomor untuk satu teks bersama. Gunakan to dengan text, atau messages.

  • textstringopsional

    Teks bersama, wajib jika menggunakan to.

  • messagesarray of objectsopsional

    Satu {to, text} per penerima, untuk teks personal.

  • namestringopsional

    Label untuk konsol, maksimal 100 karakter.

  • referencestringopsional

    ID Anda sendiri, maksimal 100 karakter, dikembalikan pada batch dan setiap pesan.

  • send_atstringopsional

    Waktu ISO 8601, 2 menit sampai 45 hari ke depan.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-0412" \
  -d '{
    "name": "Spring sale",
    "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    "to": [
      "+14155550123",
      "+447400123456",
      "+4915123456789"
    ]
  }'
202 AcceptedJSON
{
  "id": "bat_6TQ2W8M1ZK4N",
  "object": "batch",
  "name": "Spring sale",
  "status": "queued",
  "source": "api",
  "encoding": "GSM-7",
  "recipients": 3,
  "max_segments": 1,
  "cost": "0.02741",
  "refunded": "0.00000",
  "currency": "USD",
  "counts": { "scheduled": 0, "queued": 3, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
  "send_at": null,
  "reference": null,
  "created_at": "2026-11-07T09:31:40.102Z",
  "completed_at": null,
  "set_aside": []
}

Nomor yang disisihkan

Setiap nomor dibersihkan dan diharga sendiri. Nomor yang tidak bisa dikirim dikeluarkan dari batch, tidak dikenakan biaya, dan dicantumkan di set_aside dengan alasan:

reasonArti
invalid_numberTidak terbaca sebagai + dan 7 sampai 15 digit setelah pembersihan.
duplicateNomor yang sama muncul sebelumnya dalam permintaan.
unsupported_countryNomor tidak termasuk negara yang memiliki harga.
too_longTeks personalnya membutuhkan lebih dari 10 segmen.
empty_textTeks personalnya kosong.
suppressedNomor ada dalam daftar do-not-send Anda.

Jika tidak ada nomor yang tersisa, permintaan gagal dengan kode alasan pertama (contoh invalid_number) dan tidak ada yang dikenakan biaya.

Teks personal per nomor

Gunakan messages untuk memberikan teks personal ke setiap penerima: nama, waktu, jumlah. Setiap teks dihitung dan diharga sendiri, sehingga batch bisa mencampur pesan satu segmen dan dua segmen.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminders, 14 May",
    "send_at": "2026-05-13T16:00:00Z",
    "messages": [
      { "to": "+14155550123", "text": "Hi Ana, your dental check-up is tomorrow at 09:30." },
      { "to": "+14155550178", "text": "Hi Sam, your dental check-up is tomorrow at 11:00." }
    ]
  }'

Penjadwalan

Dengan send_at, batch dan pesannya menunggu dalam status scheduled dan pindah ke antrian pada menit tersebut. Biaya dipotong saat permintaan diterima, jadi batch terjadwal selalu memiliki dananya. Batch terjadwal bisa dibatalkan sampai mulai dikirim.

POST/v1/batches/{id}/cancel

Membatalkan batch terjadwal: setiap pesan menjadi canceled dan seluruh biaya dikembalikan ke saldo sebagai satu baris refund. Batch yang sudah mulai mengembalikan 409 not_cancelable.

curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

Ambil dan daftar batch

GET/v1/batches/{id}

Batch dengan jumlah live per status. Poll untuk memantau progres, atau gunakan webhooks.

GET/v1/batches

Batch dari akun, yang terbaru pertama, dengan limit (1 hingga 100) dan starting_after (id bat_).

Kolom batch

  • idstring

    bat_ diikuti oleh 12 karakter.

  • statusstring

    scheduled, queued, sending, completed, atau canceled.

  • sourcestring

    api atau console.

  • encodingstring

    GSM-7, atau UCS-2 jika teks memerlukan Unicode.

  • recipientsinteger

    Nomor yang diterima ke dalam batch.

  • max_segmentsinteger

    Jumlah segmen terbesar di antara teks.

  • coststring

    Total yang diambil dari saldo, USD.

  • refundedstring

    Total yang dikembalikan sejauh ini untuk pesan yang gagal atau dibatalkan.

  • countsobject

    Pesan per status: scheduled, queued, sent, delivered, failed, canceled.

  • send_atstring or null

    Waktu terjadwal, jika ada.

  • completed_atstring or null

    Ketika pesan terakhir mencapai status akhir.

Daftar lebih besar

Pisahkan daftar lebih dari 10.000 nomor menjadi beberapa permintaan, masing-masing dengan Idempotency-Key sendiri (misalnya id daftar dan nomor bagian). Pesan diserahkan ke jaringan secara berurutan hingga 1.200 per menit per akun, sehingga kampanye 50.000 nomor akan selesai dalam waktu kurang dari satu jam. Console menerima 50.000 nomor per kampanye dari tempel atau file CSV.

Kirim SMS massal dengan POST /v1/batches | BulkSMSAPI Docs