Hướng dẫn gửi API

1. Giới thiệu về các phương thức gửi Tin nhắn ZBS Template

Hiện tại, hệ thống Zalo Business Solutions cung cấp 2 hình thức gửi tin chính:

💻 Phương thức 1: Gửi qua API	📊 Phương thức 2: Gửi theo chiến dịch
Gửi tự động qua kết nối API. Đòi hỏi nhân sự có kiến thức về lập trình, kỹ thuật phần mềm. Phù hợp để gửi số lượng lớn, tự động hóa theo thời gian thực (Real-time). Dữ liệu gửi API không được lưu trên giao diện quản trị ZBS.	Gửi thủ công qua file Excel tải lên hệ thống ZBS. Cần chuẩn bị và định dạng file Excel. Gửi số lượng có hạn mức nhất định theo từng lần tải lên. Dữ liệu gửi được lưu và quản lý trực tiếp trên tài khoản ZBS.

2. Hướng dẫn gửi qua API

Sequence diagram API giữa Đối tác gửi tin, Zalo server và người nhận tin

Miêu tả chi tiết các bước:

a. Gửi request API

Để gửi request API, hệ thống yêu cầu xác thực bằng Access Token (Mã định danh để gửi tin). Quý khách có thể lấy Access Token theo 1 trong 2 cách sau:

Công cụ API Explorer: Dành cho Admin của Zalo OA/Ứng dụng lấy mã xác thực gửi tin một cách nhanh chóng để test.
Giao thức OAuth: Dành cho Developer tích hợp hệ thống tự động làm mới token, hoặc khi Doanh nghiệp sử dụng Ứng dụng của bên thứ 3.

b. Response sau khi gửi API

Sau khi yêu cầu (request) được gửi đi, máy chủ Zalo sẽ phản hồi (response) với các thông tin sau:

Tham số (Param)	Mô tả
`error`	Trả về `0` nếu request thành công. Nếu khác 0, vui lòng đối chiếu với Bảng mã lỗi API.
`message`	Mô tả chi tiết bằng văn bản của mã lỗi tương ứng.
`msg_id`	ID định danh của tin nhắn. * Chỉ trả về nếu yêu cầu gửi thành công.
`sent_time`	Thời gian máy chủ Zalo bắt đầu gửi tin (Định dạng Timestamp).
`quota`	Thông tin số lượng tin nhắn (quota) hiện tại của OA. * Chỉ trả về nếu yêu cầu gửi thành công.

Ví dụ mã JSON Response trả về thành công:

{
    "error": 0,
    "message": "Success",
    "data": {
        "msg_id": "a4d0243feee163bd3af2",
        "sent_time": "1626926349402",
        "quota": {
            "dailyQuota": "500",
            "remainingQuota": "499"
        }
    }
}

c. Sự kiện gửi tin (Ghi nhận thời gian)

Nếu request thành công, hệ thống sẽ ghi nhận 2 mốc thời gian quan trọng:

sent_time: Thời điểm máy chủ Zalo bắt đầu gửi tin đi.
delivery_time: Thời gian người dùng thực tế nhận được tin trên thiết bị di động.

d. Sự kiện người dùng nhận được tin (Webhook Event)

Nếu tin được gửi thành công đến thiết bị của người dùng, Zalo sẽ chủ động bắn một sự kiện (Event) tới URL Webhook mà Doanh nghiệp đã cấu hình trên hệ thống. Dữ liệu Webhook trả về bao gồm:

Tham số Webhook	Mô tả
`sender`	ID của Official Account (OA) thực hiện gửi thông báo.
`recipient`	Số điện thoại người dùng nhận thông báo.
`event_name`	Tên sự kiện. Giá trị mặc định: `user_received_message`.
`delivery_time`	Thời gian thiết bị của người dùng ghi nhận ZNS thành công.
`msg_id`	ID của tin ZNS (Chỉ trả về nếu yêu cầu thành công).
`tracking_id`	Mã số đánh dấu lần gọi API do hệ thống của Đối tác tự định nghĩa ở bước gửi Request.
`app_id`	ID của ứng dụng gửi tin (Ứng dụng đã được OA cấp quyền).
`timestamp`	Thời điểm Zalo gửi sự kiện Webhook này đi.

* Để biết thêm thông tin về cách cấu hình bảo mật Webhook và xử lý Access Token tự động, Quý khách vui lòng tham khảo các tài liệu nội bộ dành cho Developer trên hệ thống.

Gặp khó khăn khi tích hợp API ZBS hoặc Webhook?

Việc cấu hình lấy Access Token (OAuth), giải quyết các mã lỗi (-132, -114…) hay xử lý bắt sự kiện Webhook đòi hỏi nhiều thời gian đọc tài liệu kỹ thuật. Hãy để đội ngũ kỹ sư phần mềm dày dặn kinh nghiệm từ Abenla hỗ trợ bạn tích hợp hệ thống nhanh chóng và bảo mật nhất!