Pagsusumite

Magpadala ng bulk SMS gamit ang POST /v1/batches

POST/v1/batches

Magpadala sa hanggang 10,000 numero sa isang request. Ang buong halaga ay kinuha mula sa balance nang sabay-sabay.

Request body

  • toarray of stringsopsyonal

    Mga numero para sa isang shared text. Gamitin ang alinman sa to kasama ang text, o messages.

  • textstringopsyonal

    Ang shared text, kinakailangan kasama ang to.

  • messagesarray of objectsopsyonal

    Isang {to, text} bawat tatanggap, para sa personal na mga text.

  • namestringopsyonal

    Isang label para sa console, hanggang 100 karakter.

  • referencestringopsyonal

    Ang iyong sariling id, hanggang 100 karakter, ibinalik sa batch at bawat mensahe.

  • send_atstringopsyonal

    Oras sa ISO 8601, 2 minuto hanggang 45 araw sa hinaharap.

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

Mga numerong itinabi

Bawat numero ay nilinis at pinresyo nang mag-isa. Ang mga numerong hindi maipapadala ay hindi kasama sa batch, hindi sisingilin, at nakalista sa set_aside na may dahilan:

reasonKahulugan
invalid_numberHindi mabasa bilang + at 7 hanggang 15 digit pagkatapos linisin.
duplicateAng parehong numero ay lumabas na mas maaga sa request.
unsupported_countryAng numero ay hindi kabilang sa isang priced country.
too_longAng personal na text nito ay nangangailangan ng higit sa 10 segment.
empty_textAng personal na text nito ay walang laman.
suppressedAng numero ay nasa iyong do-not-send list.

Kung walang natirang numero, ang request ay magfa-fail sa code ng unang dahilan (halimbawa invalid_number) at walang sisingilin.

Personal na text bawat numero

Gamitin ang messages para bigyan ang bawat tatanggap ng kanilang sariling text: mga pangalan, oras, halaga. Ang bawat text ay binibilang at pinpresyo nang mag-isa, kaya ang isang batch ay maaaring maghalo ng one-segment at two-segment na mga mensahe.

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." }
    ]
  }'

Pag-iiskedyul

Sa send_at ang batch at mga mensahe nito ay naghihintay sa status na scheduled at lilipat sa queue sa minutong iyon. Ang halaga ay kinukuha kapag ang request ay tinanggap, kaya ang isang scheduled batch ay laging may pondo nito. Ang isang scheduled batch ay maaaring kanselahin hanggang sa ito ay magsimula.

POST/v1/batches/{id}/cancel

Kinakansela ang isang scheduled batch: ang bawat mensahe ay magiging canceled at ang buong halaga ay babalik sa balance bilang isang refund line. Ang isang batch na nagsimula na ay magsasagot ng 409 not_cancelable.

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

Kunin at ilista ang mga batch

GET/v1/batches/{id}

Ang batch na may live counts bawat status. Subaybayan ito para sa progreso, o gumamit ng webhooks.

GET/v1/batches

Mga batch ng account, pinakabago muna, may limit (1 hanggang 100) at starting_after (isang bat_ id).

Mga field ng batch

  • idstring

    bat_ na sinusundan ng 12 karakter.

  • statusstring

    scheduled, queued, sending, completed o canceled.

  • sourcestring

    api o console.

  • encodingstring

    GSM-7, o UCS-2 kapag kailangan ng Unicode ang anumang text.

  • recipientsinteger

    Mga numerong tinanggap sa batch.

  • max_segmentsinteger

    Pinakamalaking segment count sa mga text.

  • coststring

    Kabuuang kinuha mula sa balance, USD.

  • refundedstring

    Kabuuang ibinalik para sa mga nabigo o nakanselang mensahe.

  • countsobject

    Mga mensahe bawat status: scheduled, queued, sent, delivered, failed, canceled.

  • send_atstring or null

    Scheduled time, kung meron.

  • completed_atstring or null

    Nang maabot ng huling mensahe ang final status.

Mas malalaking listahan

Hatiin ang mga listahan na may higit sa 10,000 numero sa ilang request, bawat isa ay may sariling Idempotency-Key (halimbawa, ang list id at part number). Ang mga mensahe ay ipapasa sa network nang sunud-sunod hanggang 1,200 kada minuto bawat account, kaya ang isang 50,000-number campaign ay magsisimula sa loob ng isang oras. Ang console ay tumatanggap ng 50,000 numero kada campaign mula sa paste o CSV file.

Magpadala ng bulk SMS gamit ang POST /v1/batches | BulkSMSAPI Docs