Bỏ qua

Gửi tin nhắn

Gửi tin nhắn qua API SMSBAT bằng điểm cuối /bat/mesagelist.

Điểm cuối

POST /bat/messagelist

Cấu trúc yêu cầu

Nội dung yêu cầu là một mảng JSON chứa các đối tượng thông báo:

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

Thông số

Tham số bắt buộc

Tham số Loại Mô tả
từ chuỗi ID người gửi chữ và số
đến chuỗi Số điện thoại người nhận ở định dạng E.164 (ví dụ: +380XXXXXXXXX)
loại chuỗi Loại tin nhắn: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
văn bản chuỗi Nội dung tin nhắn (bắt buộc đối với hầu hết các loại, tùy chọn đối với một số loại)

Tham số tùy chọn

Tham số Loại Mô tả
customerMessageId chuỗi Mã định danh nội bộ của bạn để theo dõi
ttl số nguyên Thời gian tồn tại tính bằng giây
dữ liệu tin nhắn đối tượng Cấu hình theo loại cụ thể (thay đổi tùy theo loại thông báo)

Xác thực

Chọn một trong ba phương thức xác thực:

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

Phản hồi

Phản hồi thành công

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Trường phản hồi

Lĩnh vực Loại Mô tả
danh sách tin nhắn số nguyên Mã định danh duy nhất cho danh sách tin nhắn
messageId chuỗi Mã định danh duy nhất cho mỗi tin nhắn
trạng thái chuỗi Trạng thái tin nhắn: được chấp nhận, bị từ chối, không thành công
bộ phận số nguyên Số phần tin nhắn (đối với SMS)
customerMessageId chuỗi Mã định danh nội bộ của bạn (nếu được cung cấp)
đến chuỗi Số điện thoại người nhận

Loại tin nhắn

tin nhắn

Tin nhắn văn bản đơn giản:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

Khuyến mãi Viber

Thông điệp quảng cáo với đa phương tiện:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Giao dịch Viber

Thông báo giao dịch:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

Viber OTP

Thông báo mật khẩu một lần:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Xử lý lỗi

Mã trạng thái HTTP

Mã Mô tả
200 Yêu cầu thành công
400 Yêu cầu không hợp lệ - tham số không hợp lệ
401 Không được phép - xác thực không thành công
429 Quá nhiều yêu cầu - vượt quá giới hạn tốc độ
500 Lỗi máy chủ nội bộ

Phản hồi lỗi

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

Các phương pháp hay nhất

Định dạng số điện thoại

Luôn sử dụng định dạng E.164 cho số điện thoại:

  • ✅ Đúng: +380XXXXXXXXX
  • ❌ Sai: 380XXXXXXXXX, 0XXXXXXXXX

Nội dung tin nhắn

  • Giữ SMS dưới 160 ký tự để tránh nhiều phần
  • Sử dụng bảng mã UTF-8 cho ký tự quốc tế
  • Kiểm tra ký tự đặc biệt trước khi gửi số lượng lớn

TTL (Thời gian tồn tại)

  • Đặt TTL thích hợp cho các tin nhắn nhạy cảm với thời gian
  • Tin nhắn OTP: 300-600 giây (5-10 phút)
  • Tin nhắn khuyến mãi: 3600-86400 giây (1-24 giờ)

ID tin nhắn của khách hàng

  • Sử dụng số nhận dạng duy nhất cho mỗi tin nhắn
  • Giúp theo dõi và gỡ lỗi
  • Hữu ích cho việc tương quan với các bản ghi trong hệ thống của bạn

Giới hạn tỷ lệ

Liên hệ với người quản lý tài khoản của bạn để biết thông tin về:

  • Tin nhắn mỗi giây
  • Tin nhắn mỗi ngày
  • Kết nối đồng thời

Các bước tiếp theo