การส่ง

ส่ง SMS จำนวนมากด้วย POST /v1/batches

POST/v1/batches

ส่งถึงหมายเลขสูงสุด 10,000 หมายเลขในหนึ่งคำขอ ต้นทุนทั้งหมดจะถูกหักจากยอดเงินทันที

เนื้อหาคำขอ

  • toarray of stringsไม่จำเป็น

    หมายเลขสำหรับข้อความร่วมหนึ่งฉบับ ใช้ to กับ text หรือ messages

  • textstringไม่จำเป็น

    ข้อความร่วม จำเป็นเมื่อใช้ to

  • messagesarray of objectsไม่จำเป็น

    หนึ่ง {to, text} ต่อผู้รับ สำหรับข้อความส่วนตัว

  • namestringไม่จำเป็น

    ป้ายกำกับสำหรับคอนโซล สูงสุด 100 ตัวอักษร

  • referencestringไม่จำเป็น

    id ของคุณเอง สูงสุด 100 ตัวอักษร ส่งคืนในแบทช์และทุกข้อความ

  • send_atstringไม่จำเป็น

    เวลา ISO 8601 ล่วงหน้า 2 นาทีถึง 45 วัน

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

หมายเลขที่ถูกกันไว้

แต่ละหมายเลขจะถูกทำความสะอาดและคิดราคาแยกกัน หมายเลขที่ไม่สามารถส่งได้จะถูกแยกออกจากแบทช์ ไม่ถูกคิดเงิน และระบุใน set_aside พร้อมเหตุผล:

reasonความหมาย
invalid_numberไม่สามารถอ่านเป็น + และตัวเลข 7 ถึง 15 หลักหลังทำความสะอาด
duplicateหมายเลขเดียวกันปรากฏก่อนหน้าในคำขอ
unsupported_countryหมายเลขไม่อยู่ในประเทศที่คิดราคา
too_longข้อความส่วนตัวของมันต้องการมากกว่า 10 segments
empty_textข้อความส่วนตัวของมันว่างเปล่า
suppressedหมายเลขอยู่ในรายชื่อไม่ส่งของคุณ

หากไม่มีหมายเลขเหลือ คำขอจะล้มเหลวด้วยรหัสของเหตุผลแรก (เช่น invalid_number) และไม่มีการคิดเงิน

ข้อความส่วนตัวต่อหมายเลข

ใช้ messages เพื่อให้ข้อความส่วนตัวแก่ผู้รับแต่ละราย: ชื่อ เวลา จำนวนเงิน แต่ละข้อความจะถูกนับและคิดราคาแยกกัน ดังนั้นแบทช์สามารถผสมข้อความหนึ่ง segment และสอง segments

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

การกำหนดเวลา

ด้วย send_at แบทช์และข้อความของมันจะรอในสถานะ scheduled และย้ายไปยังคิวในนาทีนั้น ต้นทุนจะถูกหักเมื่อคำขอได้รับการยอมรับ ดังนั้นแบทช์ที่กำหนดเวลาจะมีเงินทุนเสมอ แบทช์ที่กำหนดเวลาสามารถยกเลิกได้จนกว่าจะเริ่ม

POST/v1/batches/{id}/cancel

ยกเลิกแบทช์ที่กำหนดเวลา: ทุกข้อความจะถูกยกเลิกและต้นทุนเต็มจำนวนจะกลับคืนสู่ยอดเงินเป็นหนึ่งรายการคืนเงิน แบทช์ที่เริ่มแล้วจะตอบ 409 not_cancelable

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

ดึงข้อมูลและแสดงรายการแบทช์

GET/v1/batches/{id}

ชุดข้อความพร้อมจำนวนตามสถานะแบบเรียลไทม์ สามารถโพลเพื่อตรวจสอบความคืบหน้า หรือใช้เว็บฮุค

GET/v1/batches

ชุดข้อความของบัญชี เรียงจากใหม่สุด พร้อมจำกัดจำนวน (1 ถึง 100) และ starting_after (รหัส bat_)

ฟิลด์ของชุดข้อความ

  • idstring

    bat_ ตามด้วยตัวอักษร 12 ตัว

  • statusstring

    scheduled, queued, sending, completed หรือ canceled

  • sourcestring

    api หรือ console

  • encodingstring

    GSM-7 หรือ UCS-2 เมื่อข้อความต้องการยูนิโค้ด

  • recipientsinteger

    หมายเลขที่รับเข้าในชุดข้อความ

  • max_segmentsinteger

    จำนวนส่วนที่มากที่สุดในข้อความ

  • coststring

    ยอดที่หักจากยอดเงิน, USD

  • refundedstring

    ยอดที่คืนแล้วสำหรับข้อความที่ล้มเหลวหรือยกเลิก

  • countsobject

    ข้อความตามสถานะ: scheduled, queued, sent, delivered, failed, canceled

  • send_atstring or null

    เวลาที่กำหนดส่ง (ถ้ามี)

  • completed_atstring or null

    เมื่อข้อความสุดท้ายถึงสถานะสุดท้าย

รายการขนาดใหญ่

แบ่งรายการที่มีมากกว่า 10,000 หมายเลขเป็นหลายคำขอ แต่ละคำขอมี Idempotency-Key ของตัวเอง (เช่น รหัสรายการและหมายเลขส่วน) ข้อความจะถูกส่งไปยังเครือข่ายตามลำดับสูงสุด 1,200 ข้อความต่อนาทีต่อบัญชี ดังนั้นแคมเปญ 50,000 หมายเลขจะถูกส่งภายในไม่ถึงหนึ่งชั่วโมง คอนโซลรับได้ 50,000 หมายเลขต่อแคมเปญจากการวางหรือไฟล์ CSV

ส่ง SMS จำนวนมากด้วย POST /v1/batches | BulkSMSAPI Docs