Tài liệu API của ZNS

ZNS API DOCUMENT Version 2020.10.01 Về tài liệu Tài liệu tài liệu kỹ thuật nhằm mục đích mơ tả API liên quan đến Zalo Notification Service (ZNS) phục vụ cho việc tìm hiểu kỹ thuật Tài liệu mang tính chất tham khảo có thay đổi tuỳ theo tình hình thực tế Prerequisite Tài khoản Official Account (OA) cần phải cấu hình để sử dụng OA API Xem hướng dẫn cấu hình OA để sử dụng API Về tài liệu ZNS Template - Nội dung tin nhắn Cấu trúc Cấu hình Text Section Cấu hình Table Section - Notification hình chờ user nhận tin nhắn ZNS API Send Message Method: POST Kết trả Bảng mã lỗi Sự kiện người dùng nhận tin nhắn ZNS API Get Message Status 10 11 Method: GET 11 Kết trả 11 Bảng mã lỗi 11 ZNS API Get All Template 13 Method: GET 13 Kết trả 13 ZNS API Get Template Info 14 Method: GET 14 Kết trả 14 ZNS API Get Template Sample Data 15 Method: GET 15 Kết trả 15 ZNS Template Doanh nghiệp cần phải đăng ký cài đặt ZNS Template (mẫu tin nhắn) với Zalo trước sử dụng ZNS Template có nhóm thơng tin chính: - Nội dung tin nhắn - Notification hình chờ user nhận tin nhắn - Nội dung tin nhắn Cấu trúc Gồm Text Section Table Section Cấu hình Text Section - - Thành phần bắt buộc phải có Hiển thị dạng: Ký tự Số lượng tối đa: paragraphs Cài đặt: Doanh nghiệp đăng ký với Zalo phần nội dung cố định nội dung tuỳ biến cho ZNS template Các loại nội dung tuỳ biến: - Ngày tháng: dd/mm/yyyy - Thời gian: Theo chuẩn 24h (hh:mm) - Mã đơn hàng, mã khách hàng: Gồm chữ số, chuẩn tuỳ theo tình hình thực tế - Array (dạng ký tự) với phần tử khai báo trước - Số Các cấu hình cho phép: - Điều chỉnh cỡ chữ - Điều chỉnh màu chữ - Điều chỉnh in đậm - Canh lề: Trái, phải, cho paragraph Cấu hình Table Section - - Thành phần khơng bắt buộc phải có Hiển thị dạng: Bên trái tiêu đề (row name - dạng ký tự), bên phải nội dung (row content) ký tự Số lượng tối đa: 10 rows Cài đặt: - Row name, số lượng row cố định theo ZNS template mà doanh nghiệp đăng ký với Zalo - Row content phải theo chuẩn đăng ký - Các loại nội dung tuỳ biến: - Ngày tháng: dd/mm/yyyy - Thời gian: Theo chuẩn 24h (hh:mm) - Mã đơn hàng, mã khách hàng: Gồm chữ số, chuẩn tuỳ theo tình hình thực tế - Array (dạng ký tự) với phần tử khai báo trước - Số Cấu hình cho phép: - Row name: Có thể có khơng có Nếu có, bắt buộc phải theo format ký tự có sẵn - Row content: - Điều chỉnh màu chữ màu background chữ - Điều chỉnh in đậm, in nghiêng - Nếu QR code: Điều chỉnh phần trăm width hình so với width field content * Khuyến nghị quy chuẩn: - Đối với ngày tháng: Phân cách dấu (“/”) dd/mm/yyyy Vd: 28/04/1999 - Đối với giờ: Chuẩn 24 giờ, cách dấu chấm (“:”) hh:mm Vd: 14:23 14:23:40s - Notification hình chờ user nhận tin nhắn - - Trong trường hợp User khơng tắt có cài đặt đặc biệt liên quan đến notification từ Zalo app, doanh nghiệp điều chỉnh nội dung notification hiển thị điện thoại user Cài đặt: Doanh nghiệp đăng ký với Zalo phần nội dung cố định nội dung tuỳ biến cho ZNS template Một template sử dụng OA app tạo Có thể sử dụng lại nội dung Text Section phần nội dung tin nhắn cho cài đặt ZNS API Send Message ● URL:​ ​https://business.openapi.zalo.me/message/template ● Method​:​ ​POST Content-Type:​ ​application/json ● Response Type:​ ​application/json ● Params: ● Vd: https://business.openapi.zalo.me/message/template?access_token=your_access_token Tên Kiểu liệu Mô tả access_token String Là đoạn mã cần truyền vào để xác minh quyền sử dụng api, ​tài liệu tham khảo ● Body Vd: { "phone": ​"84984432777"​, "template_id": ​"7895417a7d3f9461cd2e"​, "template_data": { "ky": ​"1"​, "thang": ​"4/2020"​, "start_date": ​"20/03/2020"​, "end_date": ​"20/04/2020"​, "customer": " ​ Nguyễn Thị Hoàng Anh", "cid": ​"PE010299485"​, "address": ​"VNG Campus, TP.HCM"​, "amount": ​"100"​, "total": ​"100000"​, }, "tracking_id":​"tracking_id" } Tên Kiểu liệu Mô tả phone String Số điện thoại chuẩn hóa theo mã quốc gia VD: 0987654321 -> 84987654321 template_id String ID template muốn sử dung template_id phía zalo cung cấp riêng cho template template_data JSON Object Bao gồm liệu phải truyền vào ứng với template_id template_data quy định riêng ứng với template_id tracking_id String (tối 48 kí tự khơng chứa kí tự đặc biệt) Là mã số đánh dấu lần gọi API Sender, Sender định nghĩa Sender dùng tracking_id để đối sốt mà khơng phụ thuộc vào message_id Zalo cung cấp Ghi chú: ZNS API Send Message có hỗ trợ mã hoá AES/CBC/PKCS5Padding Chi tiết trao đổi cụ thể lúc thực thi tích hợp doanh nghiệp có yêu cầu ● Kết trả Vd: { "message": ​"Success"​, "data": ​"message_id"​: ​"22bcbe31e821be7ee731" }, ​"error"​: ​0 } Hoặc { "message": ​"The phone number has no Zalo account or has been inactive more than 30 days"​, "error": ​-118 } Tên Kiểu liệu Mô tả error int Mã lỗi, tham khảo chi tiết bảng mã lỗi bên tài liệu message String Nội dung lỗi data JSON Object Trả rỗng tin nhắn gửi thất bại Trả trường message_id tin nhắn gửi thành công ● Bảng mã lỗi Mã lỗi Mô tả Success -100 An error has occurred -101 App is invalid -102 App does not exits -103 App has not been approved -104 App secret key does not exits -105 App does not link with Official Account -106 Method does not support -107 message_id is invalid -108 Phone is invalid -109 Template id is invalid -111 Template data is empty -112 Template data is invalid -113 Buttons is invalid -114 User cannot receive ZNS due to the user's account status, or opt-in option, or outdated Zalo version, or other internal errors -115 Out of quota -116 Text is invalid -117 You not have permission to access this template -118 The phone number has no Zalo account or has been inactive more than 30 days -120 You not have permission to access this feature -121 Body data is empty -122 Body data is not json object -123 Can not decode body data -124 Access token is invalid -125 Official Account Id is invalid -126 Out of quota development mode -127 Make sure you only send message to admin -128 Your app does not have encoding key yet -129 Gen encoding key fails -130 Body data value too large -131 Template has not been approved -132 Invalid param -133 Not allow to send message at night from 10 PM to AM Vietnam time -134 Waiting for the user to respond to opt-in option Sự kiện người dùng nhận tin nhắn Khi người dùng nhận tin nhắn, hệ thống Zalo gửi đến callback url OA http post { } "sender": { "id": ​"2893352839501541173" }, "recipient": { "id": ​"1077170099018924429" }, "event_name": ​"user_received_message"​, "message": { "delivery_time": ​"1602960467432"​, "msg_id": ​"15a0cc0bbb13bd4ce403"​, "tracking_id": ​"tracking_id" }, "app_id": ​"2074138120372622546"​, "timestamp": ​"1602560967477" 10 ZNS API Get Message Status ● URL​: ​https://business.openapi.zalo.me/message/status ● Method​: ​GET ● Content Type: ​application/json ● Response Type:​ ​application/json ● Params: Vd: https://business.openapi.zalo.me/message/status?access_token=your_access_token&mes sage_id=message_id&phone=phone Tên Kiểu liệu Mô tả access_token String Là đoạn mã cần truyền vào để xác minh quyền sử dụng api, ​tài liệu tham khảo message_id String message_id nhận sau gửi tin nhắn thành công phone String Số điện thoại nhận tin nhắn ● Kết trả Vd: { } "message": "​Success​", "data": { "delivery_time": "​1600328011517​", "message": "​The message was delivered to the user's phone​", "status": ​1 }, "error": ​0 Tên Kiểu liệu Mô tả error int Mã lỗi, tham khảo chi tiết bảng mã lỗi bên tài liệu message String Nội dung lỗi ● Bảng mã lỗi 11 Mã lỗi Mô tả -1 The message does not exist The message is pushed successfully to Zalo server but has not yet delivered to user’s phone The message was delivered to the user's phone 12 ZNS API Get All Template ● URL​: ​https://business.openapi.zalo.me/template/all ● Method​: ​GET ● Content Type: ​application/json ● Response Type:​ ​application/json ● Params: Vd: https://business.openapi.zalo.me/template/all?access_token=your_access_token Tên Kiểu liệu Mô tả access_token String Là đoạn mã cần truyền vào để xác minh quyền sử dụng api, ​tài liệu tham khảo offset int limit int Max limit = 100 ● Kết trả { } "message": ​"Success"​, "data": [ { "templateId": ​900025​, "templateName": ​"Template_1"​, "createdTime": ​0 } ], "error": ​0 13 ZNS API Get Template Info ● URL​: ​https://business.openapi.zalo.me/template/info ● Method​: ​GET ● Content Type: ​application/json ● Response Type:​ ​application/json ● Params: Vd: https://business.openapi.zalo.me/template/info?access_token=your_access_token&temp late_id=12345 Tên Kiểu liệu Mô tả access_token String Là đoạn mã cần truyền vào để xác minh quyền sử dụng api, ​tài liệu tham khảo template_id int id template ● Kết trả { } "message": "​Success​", "data": { "templateId": ​200445​, "templateName": "​noti_status_2​ ", "status": "​PENDING_REVIEW​", "listParams": [ { "name": "​customer_name​", "require": ​true​, "type": "​STRING​", "maxLength": ​30​, "minLength": ​0​, "acceptNull": ​false } ], "timeout": ​7200000 }, "error": ​0 14 ZNS API Get Template Sample Data ● URL​: ​https://business.openapi.zalo.me/template/sample-data ● Method​: ​GET ● Content Type: ​application/json ● Response Type:​ ​application/json ● Params: Vd: https://business.openapi.zalo.me/template/sample-data?access_token=your_access_tok en&template_id=12345 Tên Kiểu liệu Mô tả access_token String Là đoạn mã cần truyền vào để xác minh quyền sử dụng api, ​tài liệu tham khảo template_id int id template ● Kết trả { } "message": ​"Success"​, "data": { "balance_debt": ​2000​, "due_date": ​"01/01/1970"​, "number_debt": ​2000​, "customer_name": ​"customer_name_sample" }, "error": ​0 15 ... Kết trả 13 ZNS API Get Template Info 14 Method: GET 14 Kết trả 14 ZNS API Get Template Sample Data 15 Method: GET 15 Kết trả 15 ZNS Template Doanh nghiệp cần phải đăng ký cài đặt ZNS Template... nhận tin nhắn ZNS API Send Message Method: POST Kết trả Bảng mã lỗi Sự kiện người dùng nhận tin nhắn ZNS API Get Message Status 10 11 Method: GET 11 Kết trả 11 Bảng mã lỗi 11 ZNS API Get All Template... OA API Xem hướng dẫn cấu hình OA để sử dụng API Về tài liệu ZNS Template - Nội dung tin nhắn Cấu trúc Cấu hình Text Section Cấu hình Table Section - Notification hình chờ user nhận tin nhắn ZNS