Menghantar

Hantar SMS pukal dengan POST /v1/batches

POST/v1/batches

Hantar kepada sehingga 10,000 nombor dalam satu permintaan. Keseluruhan kos diambil dari saldo sekaligus.

Badan permintaan

  • toarray of stringspilihan

    Nombor untuk satu teks kongsi. Gunakan sama ada to dengan text, atau messages.

  • textstringpilihan

    Teks kongsi, diperlukan dengan to.

  • messagesarray of objectspilihan

    Satu {to, text} setiap penerima, untuk teks peribadi.

  • namestringpilihan

    Label untuk konsol, sehingga 100 aksara.

  • referencestringpilihan

    ID anda sendiri, sehingga 100 aksara, dikembalikan pada kumpulan dan setiap mesej.

  • send_atstringpilihan

    Masa ISO 8601, 2 minit hingga 45 hari ke hadapan.

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": []
}

Nombor yang diketepikan

Setiap nombor dibersihkan dan diharga secara berasingan. Nombor yang tidak boleh dihantar dikecualikan dari kumpulan, tidak dikenakan bayaran, dan disenaraikan dalam set_aside dengan sebab:

reasonMaksud
invalid_numberTidak boleh dibaca sebagai + dan 7 hingga 15 digit selepas pembersihan.
duplicateNombor sama muncul lebih awal dalam permintaan.
unsupported_countryNombor tersebut bukan milik negara berharga.
too_longTeks peribadinya memerlukan lebih daripada 10 segmen.
empty_textTeks peribadinya kosong.
suppressedNombor tersebut dalam senarai jangan-hantar anda.

Jika tiada nombor tinggal, permintaan gagal dengan kod sebab pertama (contohnya invalid_number) dan tiada apa dikenakan bayaran.

Teks peribadi setiap nombor

Gunakan messages untuk beri setiap penerima teks mereka sendiri: nama, masa, jumlah. Setiap teks dikira dan diharga secara berasingan, jadi kumpulan boleh campur mesej 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." }
    ]
  }'

Penjadualan

Dengan send_at, kumpulan dan mesejnya menunggu dalam status scheduled dan berpindah ke barisan pada minit tersebut. Kos diambil apabila permintaan diterima, jadi kumpulan terjadual sentiasa ada dana. Kumpulan terjadual boleh dibatalkan sehingga ia bermula.

POST/v1/batches/{id}/cancel

Membatalkan kumpulan terjadual: setiap mesej menjadi dibatalkan dan kos penuh dikembalikan ke saldo sebagai satu barian bayaran balik. Kumpulan yang telah bermula menjawab 409 not_cancelable.

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

Dapatkan dan senaraikan kumpulan

GET/v1/batches/{id}

Batch dengan kiraan status terkini. Poll untuk kemajuan, atau gunakan webhooks.

GET/v1/batches

Batch akaun, terbaru dahulu, dengan limit (1 hingga 100) dan starting_after (id bat_).

Medan batch

  • idstring

    bat_ diikuti oleh 12 aksara.

  • statusstring

    scheduled, queued, sending, completed atau canceled.

  • sourcestring

    api atau console.

  • encodingstring

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

  • recipientsinteger

    Nombor yang diterima dalam batch.

  • max_segmentsinteger

    Kiraan segmen terbesar dalam teks.

  • coststring

    Jumlah diambil dari saldo, USD.

  • refundedstring

    Jumlah dikembalikan setakat ini untuk mesej gagal atau dibatalkan.

  • countsobject

    Mesej mengikut status: scheduled, queued, sent, delivered, failed, canceled.

  • send_atstring or null

    Masa dijadualkan, jika ada.

  • completed_atstring or null

    Bila mesej terakhir mencapai status akhir.

Senarai lebih besar

Pisahkan senarai melebihi 10,000 nombor kepada beberapa permintaan, masing-masing dengan Idempotency-Key sendiri (contohnya id senarai dan nombor bahagian). Mesej diserahkan kepada rangkaian mengikut urutan sehingga 1,200 seminit setiap akaun, jadi kempen 50,000 nombor akan dihantar dalam masa kurang sejam. Konsol menerima 50,000 nombor setiap kempen dari tampalan atau fail CSV.

Hantar SMS pukal dengan POST /v1/batches | Dokumen BulkSMSAPI