Help Center Khả năng tương thích API Messagio

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

SMSBAT hỗ trợ lớp tương thích với Messagio API. Điều này cho phép bạn di chuyển trực tiếp các tích hợp Viber hiện có được thiết kế cho Messagio sang SMSBAT mà không cần phải viết lại cấu trúc tải trọng hoặc thay đổi logic tích hợp.

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/SendMessage
Định dạng yêu cầu: application/x-www-form-urlencoded (Dữ liệu biểu mẫu)

Xác thực & Thông tin xác thực

Yêu cầu được xác thực bằng cách sử dụng các tham số được gửi trực tiếp trong dữ liệu biểu mẫu nội dung yêu cầu:

Tham số	Loại	Bắt buộc	Mô tả
`người dùng`	chuỗi	Có	Thông tin đăng nhập tài khoản SMSBAT của bạn hoặc số nhận dạng người dùng.
`ký`	chuỗi	Có	Bí mật API hoặc chữ ký đã đăng ký cho tên người gửi.
`từ`	chuỗi	Có	Tên alpha của người gửi đã đăng ký.
`phương thức gửi`	chuỗi	Có	Loại kênh. Sử dụng `viber` cho tin nhắn Viber Business thông thường hoặc `viber_otp` cho các mẫu Viber OTP.
`đ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`).

Các loại tin nhắn Viber

Chọn tab bên dưới để xem các tham số cụ thể và tải trọng yêu cầu cho các cấu trúc tin nhắn Viber khác nhau:

Gửi một tin nhắn văn bản đơn giản.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`txt`	chuỗi	Có	Văn bản tin nhắn.

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Gửi tin nhắn văn bản có nút kêu gọi hành động tương tác.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`txt`	chuỗi	Có	Văn bản tin nhắn.
`nút_văn bản`	chuỗi	Có	Văn bản hiển thị trên nút.
`button_link`	chuỗi	Có	URL đích khi nút được nhấp vào.

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Gửi một tập tin hình ảnh công cộng.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`liên kết hình ảnh`	chuỗi	Có	URL HTTPS công khai của hình ảnh.
`txt`	chuỗi	Không	Văn bản chú thích tùy chọn để hiển thị bên dưới hình ảnh.

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Gửi thẻ rich chứa văn bản, hình ảnh và nút.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`txt`	chuỗi	Có	Văn bản chú thích.
`liên kết hình ảnh`	chuỗi	Có	URL HTTPS công khai của hình ảnh.
`nút_văn bản`	chuỗi	Có	Văn bản hiển thị trên nút.
`button_link`	chuỗi	Có	URL đích khi nút được nhấp vào.

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Gửi tệp video có chú thích văn bản tùy chọn và các nút tác vụ.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`video.url`	chuỗi	Có	URL HTTPS công khai của tệp video.
`video.hình thu nhỏ`	chuỗi	Có	URL HTTPS công khai của hình ảnh xem trước video.
`video.size_mb`	số nguyên	Có	Kích thước tệp video gần đúng tính bằng Megabyte.
`video.duration_sec`	số nguyên	Có	Thời lượng video tính bằng giây.
`txt`	chuỗi	Không	Văn bản mô tả tùy chọn.
`nút_văn bản`	chuỗi	Không	Văn bản nút tùy chọn (có thể đóng vai trò là chú thích hoặc liên kết).
`button_link`	chuỗi	Không	URL liên kết nút tùy chọn.

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Thông số bổ sung:

| Tham số | Loại | Bắt buộc | Mô tả |
| :--- | :--- | :--- | :--- |
| `template.id` | chuỗi | **Có** | ID mẫu Viber OTP đã được phê duyệt trước. |
| `template.lang` | chuỗi | **Có** | Mã ngôn ngữ mẫu (ví dụ: `en`, `uk`). |
| `template.params.pin` | chuỗi | **Có** | Giá trị mã pin OTP để đưa vào mẫu. |
| `template.params.business_platform_name` | chuỗi | **Có** | Phần giữ chỗ tên doanh nghiệp trong mẫu. |
| `template.params.code_validity_time` | chuỗi | **Có** | Thời hạn hiệu lực của mã PIN tính bằng phút. |

**Ví dụ về tải trọng yêu cầu:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

Gửi một thẻ tin nhắn tương tác chứa nhiều slide (thẻ) mà người dùng có thể vuốt qua.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`txt`	chuỗi	Có	Văn bản tiêu đề của băng chuyền.
`băng chuyền[N].title`	chuỗi	Có	Tiêu đề thẻ `N` (bắt đầu từ 0).
`băng chuyền[N].image_url`	chuỗi	Có	URL hình ảnh HTTPS công khai của thẻ `N`.
`băng chuyền[N].primary_label`	chuỗi	Có	Chú thích nút chính của thẻ `N`.
`băng chuyền[N].primary_url`	chuỗi	Có	URL liên kết nút chính của thẻ `N`.
`băng chuyền[N].secondary_label`	chuỗi	Không	Chú thích nút phụ của thẻ `N`.
`băng chuyền[N].secondary_url`	chuỗi	Không	URL liên kết nút phụ của thẻ `N`.

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Gửi tin nhắn chứa câu hỏi thăm dò hoặc khảo sát mang tính tương tác.

Thông số bổ sung:

Tham số	Loại	Bắt buộc	Mô tả
`txt`	chuỗi	Có	Văn bản câu hỏi khảo sát.
`survey_options[N]`	chuỗi	Có	Văn bản tùy chọn khảo sát cho mục `N` (chỉ mục bắt đầu từ 0). Cần có ít nhất 2 lựa chọn.
`tùy chọn_type`	số nguyên	Có	Loại bộ chọn: `1` (RadioButtons) hoặc `2` (Nút thông thường).

Ví dụ về tải trọng yêu cầu:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

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

Điểm cuối tương thích API Messagio trả về phản hồi ở định dạng XML với mã trạng thái HTTP 200 OK.

Phản hồi được chấp nhận (Thành công)

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Phản hồi lỗi

Nếu xác thực tham số yêu cầu không thành công hoặc xác thực không thành công, phản hồi sẽ trả về mã khác 0.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Cuộc gọi lại

URL gọi lại phải được triển khai và lưu trữ trên nền tảng của bạn. SMSBAT gửi lệnh gọi lại HTTP để cập nhật hệ thống của bạn về các sự kiện gửi, phản hồi khảo sát và phản hồi của người dùng.

1. Gọi lại trạng thái giao hàng

Được gửi khi thư chuyển trạng thái (đã gửi, đã đọc, không thành công).

Loại nội dung: application/x-www-form-urlencoded
Phương thức: POST

Yêu cầu định dạng tải trọng:

Đã giao:
```
msg_id=MESSAGE_GUID&status=delivered
```

Đã xem/Đọc:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Chưa gửi được / Không thành công:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Mô tả trường:

msg_id: ID tin nhắn duy nhất SMSBAT (GUID) được trả về trong phản hồi SendMessage.
status: Kết quả giao hàng (đã giao, chưa giao hoặc không xác định trạng thái).
type: Đặt thành seen khi người nhận đã xem tin nhắn.
status_extend: Lý do kỹ thuật cụ thể dẫn đến trạng thái không được gửi (ví dụ: VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Gọi lại câu trả lời khảo sát

Được kích hoạt khi người dùng chọn tùy chọn phản hồi trong tin nhắn Khảo sát trên Viber.

Loại nội dung: application/x-www-form-urlencoded
Phương thức: POST

Định dạng tải trọng yêu cầu:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Gọi lại tin nhắn người dùng gửi đến

Được kích hoạt khi người dùng gửi tin nhắn trả lời bằng văn bản hoặc phương tiện trở lại dịch vụ Viber Business của bạn.

Loại nội dung: application/json
Phương thức: POST

Định dạng tải trọng yêu cầu:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Mô tả trường:

msg_id: ID tin nhắn duy nhất được tạo cho thư trả lời gửi đến.
text: Nội dung văn bản do người dùng gửi (có thể là null nếu họ chỉ gửi media).
media: URL trực tiếp để tải xuống bất kỳ tệp đính kèm phương tiện nào do người dùng gửi (có thể là null nếu chỉ có văn bản).
phone: Số điện thoại của người gửi ở định dạng quốc tế.
sender_bm_id: ID người gửi Viber Business.

Search Results

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

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

Xác thực & Thông tin xác thực

Các loại tin nhắn Viber

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

Phản hồi được chấp nhận (Thành công)

Phản hồi lỗi

Cuộc gọi lại

1. Gọi lại trạng thái giao hàng

2. Gọi lại câu trả lời khảo sát

3. Gọi lại tin nhắn người dùng gửi đến