Gửi tin

Gửi SMS hàng loạt với POST /v1/batches

POST/v1/batches

Gửi tới tối đa 10,000 số trong một yêu cầu. Toàn bộ chi phí được trừ từ số dư ngay lập tức.

Nội dung yêu cầu

  • toarray of stringstùy chọn

    Số dùng chung một tin nhắn. Dùng to với text, hoặc messages.

  • textstringtùy chọn

    Tin nhắn dùng chung, bắt buộc khi dùng to.

  • messagesarray of objectstùy chọn

    Một {to, text} cho mỗi người nhận, dành cho tin nhắn cá nhân.

  • namestringtùy chọn

    Nhãn cho console, tối đa 100 ký tự.

  • referencestringtùy chọn

    ID riêng của bạn, tối đa 100 ký tự, được trả về trên lô và mỗi tin nhắn.

  • send_atstringtùy chọn

    Thời gian ISO 8601, từ 2 phút đến 45 ngày sau.

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

Số bị loại

Mỗi số được làm sạch và định giá riêng. Số không thể gửi bị loại khỏi lô, không bị tính phí, và liệt kê trong set_aside với lý do:

reasonÝ nghĩa
invalid_numberKhông đọc được dưới dạng + và 7 đến 15 chữ số sau khi làm sạch.
duplicateSố này đã xuất hiện trước đó trong yêu cầu.
unsupported_countrySố không thuộc quốc gia có giá.
too_longTin nhắn cá nhân cần nhiều hơn 10 segment.
empty_textTin nhắn cá nhân trống.
suppressedSố có trong danh sách không gửi của bạn.

Nếu không còn số nào, yêu cầu thất bại với mã lý do đầu tiên (ví dụ invalid_number) và không bị tính phí.

Tin nhắn cá nhân cho từng số

Dùng messages để gửi tin nhắn riêng cho từng người nhận: tên, thời gian, số tiền. Mỗi tin nhắn được đếm và định giá riêng, nên một lô có thể trộn tin nhắn một segment và hai segment.

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

Lập lịch

Với send_at, lô và tin nhắn sẽ chờ ở trạng thái scheduled và chuyển vào hàng đợi vào phút đó. Chi phí được trừ khi yêu cầu được chấp nhận, nên lô đã lên lịch luôn có đủ tiền. Có thể hủy lô đã lên lịch cho đến khi bắt đầu.

POST/v1/batches/{id}/cancel

Hủy một lô đã lên lịch: mọi tin nhắn chuyển thành canceled và toàn bộ chi phí được hoàn vào số dư dưới dạng một dòng hoàn tiền. Lô đã bắt đầu sẽ trả về 409 not_cancelable.

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

Truy xuất và liệt kê các lô

GET/v1/batches/{id}

Batch với số lượng trạng thái cập nhật theo thời gian thực. Bạn có thể kiểm tra tiến trình bằng cách poll hoặc sử dụng webhooks.

GET/v1/batches

Các batch của tài khoản, sắp xếp từ mới nhất trở đi, với giới hạn (từ 1 đến 100) và starting_after (một bat_ id).

Các trường của batch

  • idstring

    bat_ theo sau là 12 ký tự.

  • statusstring

    scheduled, queued, sending, completed hoặc canceled.

  • sourcestring

    api hoặc console.

  • encodingstring

    GSM-7, hoặc UCS-2 khi bất kỳ văn bản nào cần Unicode.

  • recipientsinteger

    Số điện thoại được chấp nhận vào batch.

  • max_segmentsinteger

    Số lượng segment lớn nhất trong các văn bản.

  • coststring

    Tổng số tiền được trừ từ số dư, USD.

  • refundedstring

    Tổng số tiền được hoàn trả cho đến nay cho các tin nhắn thất bại hoặc đã hủy.

  • countsobject

    Tin nhắn theo trạng thái: scheduled, queued, sent, delivered, failed, canceled.

  • send_atstring or null

    Thời gian đã lên lịch, nếu có.

  • completed_atstring or null

    Khi tin nhắn cuối cùng đạt trạng thái cuối cùng.

Danh sách lớn hơn

Chia danh sách trên 10,000 số thành nhiều yêu cầu, mỗi yêu cầu có Idempotency-Key riêng (ví dụ: id danh sách và số phần). Tin nhắn được chuyển đến mạng theo thứ tự với tốc độ tối đa 1,200 tin mỗi phút cho mỗi tài khoản, vì vậy một chiến dịch 50,000 số sẽ được gửi đi trong vòng chưa đầy một giờ. Console nhận 50,000 số cho mỗi chiến dịch từ một file paste hoặc CSV.

Gửi SMS hàng loạt với POST /v1/batches | Tài liệu BulkSMSAPI