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:
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:
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:
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
Gửi mật khẩu dùng một lần (OTP) của Viber bằng mẫu đã được phê duyệt trước.
Ghi
Khi gửi tin nhắn OTP, bạn phải đặt phương thức gửi thành viber_otp.
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.
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:
- Đã xem/Đọc:
- Chưa gửi được / Không thành công:
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 giaohoặckhông xác định trạng thái).type: Đặt thànhseenkhi 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:
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ànullnế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ànullnế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.