Gửi tin

Gửi SMS với POST /v1/messages

POST/v1/messages

Gửi một tin nhắn tới một số. Chi phí được trừ từ số dư khi yêu cầu được chấp nhận.

Nội dung yêu cầu

  • tostringbắt buộc

    Số điện thoại định dạng quốc tế, ví dụ +14155550123. Khoảng trắng, gạch ngang, ngoặc và tiền tố 00 sẽ được làm sạch.

  • textstringbắt buộc

    Nội dung tin nhắn. Tối đa 10 segments; xem phần Văn bản và segments.

  • referencestringtùy chọn

    ID riêng của bạn, tối đa 100 ký tự. Sẽ xuất hiện trong đối tượng tin nhắn và mọi webhook.

  • send_atstringtùy chọn

    Thời gian gửi theo chuẩn ISO 8601, từ 2 phút đến 45 ngày sau. Nếu không có, tin nhắn sẽ được xếp hàng ngay lập tức.

Thêm tiêu đề Idempotency-Key để đảm bảo an toàn khi thử lại: xem Tính bất biến.

curl https://bulksmsapi.cc/v1/messages \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "text": "Your Northwind code is 482913. It expires in 10 minutes.",
    "reference": "login-7781"
  }'
202 AcceptedJSON
{
  "id": "msg_8F3K2Q9TZ1MX",
  "object": "message",
  "batch_id": "bat_4M7Q1X0PK2RS",
  "to": "+14155550123",
  "country": "US",
  "text": "Your Northwind code is 482913. It expires in 10 minutes.",
  "segments": 1,
  "price": "0.00507",
  "currency": "USD",
  "status": "queued",
  "error": null,
  "reference": "login-7781",
  "created_at": "2026-11-07T09:30:12.418Z",
  "sent_at": null,
  "done_at": null
}

Đối tượng tin nhắn

Các trường

  • idstring

    ID tin nhắn, msg_ theo sau là 12 ký tự.

  • objectstring

    Luôn là message.

  • batch_idstring

    Batch mà tin nhắn thuộc về (một tin nhắn đơn lẻ cũng có batch riêng).

  • tostring

    Số điện thoại định dạng E.164, sau khi làm sạch.

  • countrystring

    Mã ISO 3166 của quốc gia được tính giá.

  • textstring

    Văn bản đã gửi, các trường merge đã được điền.

  • segmentsinteger

    Số segments SMS mà văn bản sử dụng.

  • pricestring

    Giá tin nhắn này bằng USD, 5 chữ số thập phân (giá mỗi segment nhân với số segments).

  • currencystring

    Luôn là USD.

  • statusstring

    scheduled, queued, sent, delivered, failed hoặc canceled.

  • errorobject or null

    Với tin nhắn failed hoặc canceled: mã và thông báo lỗi.

  • referencestring or null

    Tham chiếu riêng của bạn từ yêu cầu.

  • created_atstring

    Thời điểm yêu cầu được chấp nhận (ISO 8601, UTC).

  • sent_atstring or null

    Thời điểm tin nhắn được chuyển tới mạng.

  • done_atstring or null

    Thời điểm trạng thái cuối (delivered, failed hoặc canceled) được thiết lập.

Lấy thông tin tin nhắn

GET/v1/messages/{id}

Một tin nhắn theo ID msg_ của nó. Tin nhắn từ tài khoản khác sẽ trả về 404.

curl https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

Danh sách tin nhắn

GET/v1/messages

Tin nhắn của tài khoản, mới nhất trước.

Tham số truy vấn

  • batch_idstringtùy chọn

    Chỉ tin nhắn thuộc lô bat_ này.

  • statusstringtùy chọn

    scheduled, queued, sent, delivered, failed hoặc canceled.

  • limitintegertùy chọn

    1 đến 100, mặc định 20.

  • starting_afterstringtùy chọn

    Một msg_ id: trang bắt đầu sau id này. Dùng id cuối cùng của trang trước.

curl "https://bulksmsapi.cc/v1/messages?status=failed&limit=50" \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"
200 OKJSON
{
  "object": "list",
  "data": [ { "id": "msg_8F3K2Q9TZ1MX", "object": "message", "status": "failed", "...": "..." } ],
  "has_more": false
}
Gửi SMS với POST /v1/messages | Tài liệu BulkSMSAPI