Khả năng tương thích API GMS

SMSBAT hỗ trợ lớp tương thích với GMS API. Điều này cho phép bạn di chuyển trực tiếp các tích hợp hiện có được thiết kế cho GMS sang SMSBAT mà không cần phải sửa đổi lược đồ định tuyến tin nhắn, cấu trúc tải trọng hoặc trình nghe gọi lại.

Cài đặt kết nối

Để định tuyến các yêu cầu thông qua SMSBAT, hãy cập nhật URL cơ sở và thông tin xác thực trong tích hợp của bạn:

URL cơ sở: https://restapi.smsbat.com
Điểm cuối: POST /api/GMSMessage/send_message
Định dạng yêu cầu: application/json
Xác thực: Xác thực cơ bản HTTP (sử dụng thông tin xác thực API SMSBAT của bạn)

Tham số yêu cầu

API tương thích GMS chấp nhận một đối tượng JSON có các tham số cấp cao nhất sau:

Tham số	Loại	Bắt buộc	Mô tả
`số_điện thoại`	chuỗi	Có	Số điện thoại của người nhận ở định dạng quốc tế (ví dụ: `380501234567`).
`thẻ`	chuỗi	Có	Tên người gửi đã đăng ký/tên alpha.
`kênh`	mảng	Có	Danh sách các kênh để thử, theo thứ tự ưu tiên. Các giá trị được hỗ trợ: `viber`, `sms`, `push`. Ví dụ: `["viber", "sms"]`.
`tùy chọn kênh`	đối tượng	Có	Bản đồ chứa các tùy chọn cho từng kênh đang hoạt động (xem bên dưới).
`thêm_id`	chuỗi	Không	ID tin nhắn nội bộ phía khách hàng của bạn.
`gọi lại_url`	chuỗi	Không	URL điểm cuối trên hệ thống của bạn để nhận lệnh gọi lại trạng thái giao hàng.
`mã_phân chia`	chuỗi	Không	Mã định danh mã phân chia tùy chọn (mặc định là `main`).

Cài đặt tùy chọn kênh

Đối tượng channel_options chứa các cấu hình dành riêng cho kênh.

Tin nhắn ViberViber có tính năng dự phòng SMSTin nhắn SMSKhảo sát ViberBăng chuyền ViberTin nhắn đẩy

Được sử dụng khi viber được liệt kê trong mảng channels.

Tham số	Loại	Bắt buộc	Mô tả
`văn bản`	chuỗi	Có	Nội dung tin nhắn.
`ttl`	số nguyên	Có	Thời gian tồn tại tính bằng giây.
`img`	chuỗi	Không	URL HTTPS công khai của hình ảnh để hiển thị.
`chú thích`	chuỗi	Không	Nhãn văn bản nút.
`hành động`	chuỗi	Không	URL đích khi nút được nhấp vào.
`tùy chọn khảo sát`	mảng	Không	Mảng chuỗi (2 đến 5 mục) để hiển thị dưới dạng tùy chọn khảo sát.
`băng chuyền_items`	mảng	Không	Mảng đối tượng trượt sẽ hiển thị dưới dạng băng chuyền Viber (xem cấu trúc trong tab).

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

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Cho phép nhắn tin Viber với tính năng dự phòng SMS tự động nếu việc gửi Viber không thành công trong TTL.

Ví dụ về yêu cầu dự phòng:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Được sử dụng khi sms được liệt kê trong mảng channels.

Tham số	Loại	Bắt buộc	Mô tả
`văn bản`	chuỗi	Có	Nội dung tin nhắn.
`alpha_name`	chuỗi	Có	Tên alpha của người gửi.
`ttl`	số nguyên	Có	Thời gian tồn tại tính bằng giây.
`ctr`	boolean	Không	Bật theo dõi nhấp chuột CTR trên các liên kết trong văn bản (`true`/`false`).

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

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Được sử dụng để tạo các cuộc thăm dò và khảo sát trên Viber.

Cảnh

Cấu hình khảo sát Viber phải có từ 2 đến 5 tùy chọn bên trong survey_options.

Ví dụ về yêu cầu khảo sát:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Được sử dụng để gửi thẻ slide hình ảnh có thể vuốt được. Mỗi slide đều hỗ trợ hình ảnh, tiêu đề và nút.

Ví dụ về yêu cầu băng chuyền:

href="#__codelineno-4-1">{ "phone_number": "380501234567", "tag": "MySender", "channels": ["viber"], "channel_options": { "viber": { "text": "Choose an offer", "ttl": 60, "carousel_items": [ { "title": "Offer 1", "image_url": "https://www.example.com/offer-1.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-1", "secondary_label": "More", "secondary_url": "https://www.example.com/offers" }, { "title": "Offer 2", "image_url": "https://www.example.com/offer-2.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-2" } ] } } }

Được sử dụng khi push được liệt kê trong mảng channels.

Tham số	Loại	Bắt buộc	Mô tả
`tiêu đề`	chuỗi	Có	Văn bản tiêu đề của thông báo đẩy.
`văn bản`	chuỗi	Có	Nội dung tin nhắn.
`ttl`	số nguyên	Có	Thời gian tồn tại tính bằng giây.
`img`	chuỗi	Không	URL HTTPS công khai của hình ảnh để hiển thị.
`chú thích`	chuỗi	Không	Nhãn văn bản nút.
`hành động`	chuỗi	Không	URL đích khi nút được nhấp vào.
`ctr`	boolean	Không	Bật theo dõi nhấp chuột.

Ví dụ về yêu cầu đẩy:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Định dạng phản hồi

Điểm cuối trả về phản hồi ở định dạng JSON với mã trạng thái HTTP 200 OK.

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

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Phản hồi lỗi

Nếu xác thực hoặc xử lý không thành công, một phản hồi lỗi có ErrorCode không rỗng và ErrorText chi tiết sẽ được trả về.

Kênh/Tùy chọn không được hỗ trợSố tùy chọn khảo sát không hợp lệTên Alpha chưa đăng kýLỗi xử lý nội bộ

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Định dạng phân phối cuộc gọi lại

Nếu callback_url được chỉ định trong yêu cầu, SMSBAT sẽ gửi cập nhật trạng thái gửi dưới dạng tải trọng JSON POST tới điểm cuối của bạn.

Ví dụ về yêu cầu gọi lại

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Mô tả trường gọi lại

Lĩnh vực	Loại	Mô tả
`số`	chuỗi	Số điện thoại người nhận.
`thời gian`	số	Dấu thời gian sự kiện tính bằng mili giây Unix.
`trạng thái`	số	Mã định danh trạng thái được đơn giản hóa (xem bảng Mã trạng thái).
`trạng thái phụ`	số	Mã định danh trạng thái chi tiết (xem bảng mã trạng thái phụ).
`hyber_status`	số	Mã trạng thái nội bộ SMSBAT chi tiết (xem bảng Trạng thái Hyber).
`tin nhắn_id`	chuỗi	ID tin nhắn SMSBAT (GUID) được tạo khi gửi.
`thêm_id`	chuỗi	ID phía khách hàng được cung cấp trong yêu cầu ban đầu.
`đã gửi_via`	chuỗi	Kênh đã xử lý tin nhắn: `viber`, `sms` hoặc `rcs`.
`match_template_id`	số	Trạng thái khớp mẫu Viber (nếu có).

Ánh xạ trạng thái

1. Trạng thái đơn giản hóa (`trạng thái`)

Mã	Ý nghĩa
`1`	Tin nhắn được chấp nhận hoặc đang được gửi.
`2`	Tin nhắn đã được gửi.
`3`	Lỗi xử lý hoặc giao hàng.

2. Trạng thái chi tiết (`trạng thái phụ`)

Mã	Ý nghĩa
`12`	Được chấp nhận để xử lý.
`23`	Đã giao hàng.
`24`	Đã xem/đọc.
`35`	Không được giao trong vòng TTL (Đã hết hạn).
`36`	Lỗi giao hàng.

3. Loại kênh (`sent_via`)

Kênh	Mô tả
`viber`	Status do kênh Viber sản xuất.
`tin nhắn`	Trạng thái được tạo bởi kênh SMS.
`rcs`	Trạng thái do kênh RCS tạo ra.

4. Trạng thái SMSBAT chi tiết (`hyber_status`)

Mã	Kênh	Trạng thái	Trạng thái phụ	Ý nghĩa
23033	`viber`	`2`	`23`	Tin nhắn Viber đã được gửi.
24013	`viber`	`2`	`24`	Tin nhắn Viber được người nhận đọc (Đã xem).
36013	`viber`	`3`	`36`	Viber lỗi nội bộ.
36023	`viber`	`3`	`36`	ID dịch vụ Viber không hợp lệ hoặc không khả dụng.
36033	`viber`	`3`	`36`	Dữ liệu tải trọng Viber không hợp lệ.
36037	`viber`	`3`	`36`	URL hình ảnh Viber quá dài.
36038	`viber`	`3`	`36`	URL hình ảnh Viber không hợp lệ.
36039	`viber`	`3`	`36`	Văn bản Viber quá dài.
36044	`viber`	`3`	`36`	Văn bản Viber trống.
36053	`viber`	`3`	`36`	Loại tin nhắn Viber không được hỗ trợ.
36063	`viber`	`3`	`36`	Thông số Viber không hợp lệ.
36073	`viber`	`3`	`36`	Đã hết thời gian chờ của nhà cung cấp Viber.
36083	`viber`	`3`	`36`	Người gửi Viber bị người nhận chặn.
36093	`viber`	`3`	`36`	Người nhận chưa được đăng ký là người dùng Viber.
36103	`viber`	`3`	`36`	Không tìm thấy thiết bị Android/iOS nào có hỗ trợ Viber.
36113	`viber`	`3`	`36`	Địa chỉ IP trái phép để gửi Viber.
36123	`viber`	`3`	`36`	Đã phát hiện thấy tin nhắn Viber trùng lặp.
36143	`viber`	`3`	`36`	Lỗi thanh toán Viber.
36153	`viber`	`3`	`36`	Tin nhắn bị chặn bởi danh sách đen nền tảng.
36163	`viber`	`3`	`36`	Lỗi xử lý nội bộ nền tảng Viber.
36173	`viber`	`3`	`36`	Nhãn Viber sai hoặc thiếu.
36183	`viber`	`3`	`36`	Giá trị TTL Viber không hợp lệ.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS được chấp nhận.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS trên đường đi.
23011	`sms` / `rcs`	`2`	`23`	Đã gửi SMS/RCS.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS đã hết hạn (không được gửi trong TTL).
36021	`sms` / `rcs`	`3`	`36`	Đã xóa tin nhắn SMS/RCS.
36031	`sms` / `rcs`	`3`	`36`	Không thể gửi SMS/RCS.
36041	`sms` / `rcs`	`3`	`36`	Trạng thái gửi SMS/RCS không xác định.
36051	`sms` / `rcs`	`3`	`36`	Tin nhắn SMS/RCS bị từ chối.