Hướng dẫn API SMSBAT RESTful

Hướng dẫn đầy đủ về SMSBAT RESTful API - mọi thứ bạn cần biết.

Cập nhật lần cuối: Ngày 29 tháng 8 năm 2025

SMSBAT RESTful API cho phép bạn gửi nhiều loại tin nhắn khác nhau: Viber-carousel, Viber-survey, Viber-promo (hình ảnh, video), trò chuyện doanh nghiệp trên Viber, tin nhắn OTP (Viber OTP, Flash Call) và các biến thể dự phòng của chúng.

Lưu ý: Đây là API HTTP hợp nhất cho tin nhắn gửi đi. Nếu bạn cần tích hợp với các bot gửi đến (Viber Bot / Telegram Bot), vui lòng tham khảo API Cascade.

1. Giao thức

Giao thức: HTTPS
Nội dung yêu cầu: Đối tượng JSON chứa một mảng thông báo.
Phương pháp:
GET để lấy dữ liệu (trạng thái tin nhắn, số dư, v.v.)
POST để tạo các đối tượng (ví dụ: bắt đầu phát sóng/gửi đi)
PATCH để sửa đổi đối tượng

2. Ủy quyền

Chúng tôi cung cấp một số phương thức ủy quyền để thuận tiện cho bạn: - Xác thực cơ bản HTTP (đăng nhập và mật khẩu từ bảng điều khiển của bạn). - Tiêu đề HTTP tùy chỉnh X-Authorization-Key chứa Mã thông báo API. - Trường mật khẩu Xác thực Cơ bản HTTP chứa Mã thông báo API (chuyển @ làm thông tin đăng nhập).

Mã thông báo API có thể được tạo trong Bảng điều khiển trong Hồ sơ người dùng.

Ví dụ về yêu cầu

Với xác thực cơ bản:

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

Với X-Authorization-Key:

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Gửi tin nhắn

Trong nền tảng SMSBAT, bất kỳ tin nhắn nào được gửi đi (dù chỉ một tin nhắn) đều được coi là "Phát sóng" (danh sách tin nhắn).

Điểm cuối - Phương thức: POST - URL: https://api.smsbat.com/bat/messagelist - Tiêu đề: Content-Type: application/json

Cấu trúc tải trọng cơ bản:

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Các trường bắt buộc cho mỗi đối tượng thư:

from: Tên alpha của người gửi đã được xác minh.
to: Số điện thoại người nhận (dạng E.164).
type: Kiểu thông báo enum.
text: Nội dung chính của tin nhắn (tùy chọn nếu loại không yêu cầu văn bản).

Các giá trị type được hỗ trợ: - tin nhắn - viber_service (hoặc viber_trans) - viber_promo - viber_carousel - viber_khảo sát - viber_otp - viber_session - flashcall_callback - cuộc gọi chớp nhoáng

Các trường chung tùy chọn:

customerMessageId: Chuỗi ID bên trong hệ thống của bạn (được sử dụng để theo dõi các cuộc gọi lại). Phải là duy nhất cho mỗi tin nhắn.
dtSend: ISO8601 Ngày/Thời gian gửi đi theo lịch trình trong tương lai.
dtExpire: ISO8601 Ngày/Giờ của thời hạn giao hàng.
ttl: Thời gian tồn tại tính bằng giây. (Nếu dtExpire không được cung cấp, API sẽ tính toán ánh xạ mặc định từ type).

TTL mặc định (Giây):

sms - 86400 (24h)
viber_trans /viber_service - 345600
viber_promo - 604800
viber_session - 604800

4. Định tuyến dự phòng (Cascading)

Bạn có thể chỉ định hàng dự phòng để đảm bảo gửi tin nhắn nếu kênh chính bị lỗi hoặc hết hạn.

Dự phòng kích hoạt khi nhà cung cấp từ chối tin nhắn chính hoặc khi TTL hết hạn. href="#__codelineno-3-1">{ "messages": [ { "from": "ALPHANAME", "to": "380500505051", "text": "test message", "type": "viber_service", "ttl": 60, "fallbacks": [ { "from": "ALPHANAME", "to": "380936670003", "text": "test sms fallback message2", "type": "sms" } ] } ] }

5. Tổng quan về các loại tin nhắn và dữ liệu tin nhắn

Các loại thông báo phức tạp yêu cầu cấu hình bổ sung được đưa vào thuộc tính messageData.

Khuyến mãi Viber 5.1 (`viber_promo`)

Chỉ hình ảnh

"messageData":{
  "img":"https://domain.com/image.png"
}

Văn bản + Nút

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Hình ảnh + Văn bản + Nút Kết hợp img, buttonText và buttonAction.

Tải trọng video:

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}

(Bạn cũng có thể kết hợp các thuộc tính Video với buttonText và buttonAction).

5.2 Giao dịch / Dịch vụ Viber (`viber_trans`, `viber_service`)

Nếu bạn có một mẫu đã được phê duyệt có chứa tệp đính kèm:

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

5.3 Băng chuyền Viber (`viber_carousel`)

Cần có mảng carousel.items bên trong messageData.

Hạn chế: - Chiều dài sản phẩm: từ 2 đến 5 sản phẩm - Tiêu đề: 2 đến 38 ký tự - imageUrl: Kích thước khuyến nghị JPEG/PNG 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Khảo sát / Danh sách Viber (`viber_survey`)

Tạo cuộc thăm dò tương tác trong chế độ xem trò chuyện.

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}

Thuộc tính text của tin nhắn đóng vai trò là tiêu đề khảo sát (Tối đa 85 ký tự). Bạn có thể chuyển từ 2 đến 5 tùy chọn, mỗi tùy chọn tối đa 50 ký tự.

5.5 Viber OTP (`viber_otp`)

Sử dụng các mẫu Viber bản địa hóa đã đăng ký trước trên toàn cầu.

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}

Các tham số mẫu (pin, business_platform_name) hoàn toàn phân biệt chữ hoa chữ thường. API hỗ trợ nhiều biến thể ngôn ngữ mã ISO khác nhau (EN, ES, RU, TR, UK, v.v.).

5.6 Cuộc gọi flash (`flashcall`)

Các chữ số cuối cùng của số quay số (mã được tạo) phải được chuyển qua tham số text. Nếu văn bản bị bỏ qua, mã sẽ được chọn ngẫu nhiên và bạn phải trích xuất nó từ nội dung Phản hồi 200 OK đồng bộ của API (tin nhắn/văn bản).

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}