Download the PHP package field-vn/zalo without Composer

Zalo

SDK Laravel cho Zalo Official Account, Zalo Bot và ZBS Template Message: quản lý nhiều OA, tự refresh token, nhận webhook, gửi tin theo mẫu tới số điện thoại, kèm giao diện cấu hình không cần viết code.

Mục lục

Cấu hình — làm bằng giao diện, không cần code

• Yêu cầu
• Cài đặt
• Xác thực domain
• Mở giao diện quản trị
• Kết nối Official Account
• Kết nối Bot
• Gửi tin tới số điện thoại (ZBS)
• Scheduler

Dùng trong code

• Gửi tin nhắn
• Kiểm tra khả dụng OA / ZBS
• Nhận tin nhắn
• Nhiều OA
• Testing
• Mở rộng

Tham chiếu

• Chi phí và giới hạn
• Biến môi trường
• Commands

Yêu cầu

• PHP 8.2+
• Laravel 12 hoặc 13

Cấu hình

Toàn bộ phần này làm bằng giao diện web, không cần viết dòng code nào. Ai thích dòng lệnh thì mọi thao tác đều có command tương đương — xem Commands.

Cài đặt

Thêm credential của Zalo App vào .env:

Chạy trình cài đặt:

Lệnh này kiểm tra env, publish config, chạy migration và nhắc các bước còn thiếu.

Xác thực domain

Zalo chỉ chấp nhận URL thuộc domain đã xác thực. Làm bước này trước, nếu không webhook sẽ báo "chưa được xác thực domain" và OAuth trả -14003 Invalid redirect uri.

Vào Zalo Developers → App → Xác thực domain, tải file HTML được cấp, đặt vào thư mục public/ của dự án, rồi bấm xác thực.

Mở giao diện quản trị

Mở https://your-app.com/zalo. Đây là nơi làm mọi việc cấu hình còn lại.

Bỏ trống ZALO_UI_PASSWORD thì giao diện chỉ chạy ở môi trường local. Basic Auth gửi credential ở mọi request nên site phải chạy HTTPS.

Dự án đã có hệ thống auth riêng thì định nghĩa gate — nó được ưu tiên hơn basic auth:

Token và secret không hiển thị đầy đủ trên giao diện. Giao diện không cần build step và không cần vendor:publish; muốn tuỳ biến thì chạy php artisan vendor:publish --tag=zalo-views.

Kết nối Official Account

Vào Official Account → Thêm OA, nhập tên và OA ID (lấy ở trang quản trị Zalo OA). Mở OA vừa tạo, làm theo bốn bước hiện sẵn trên trang:

1. Copy Redirect URI trên trang đó
2. Dán vào Zalo Developers → App → Callback URL
3. Quay lại bấm Cấp quyền, đăng nhập bằng tài khoản admin của OA
4. Bấm Kiểm tra kết nối

Redirect URI phải khớp chính xác giá trị khai trong Zalo Developers, kể cả dấu / cuối. Lệch một ký tự là Zalo trả -14003 Invalid redirect uri.

Xong bước này, trang OA cho gửi một tin thử để xác nhận luồng chạy thật.

Kết nối Bot

Bot dùng token tĩnh, không cần OAuth và không dính Zalo App. Lấy token tại bot.zaloplatforms.com, rồi vào Bot → Thêm Bot. Package gọi getMe ngay để kiểm tra token trước khi lưu.

Bot cần chat_id để gửi tin, mà Zalo không có API liệt kê chat_id. Cách lấy: cắm webhook rồi để package tự ghi lại khi có người nhắn tới.

Trên trang chi tiết bot, bấm Cắm webhook, mở Zalo nhắn cho bot một câu — chat_id hiện ngay trong danh sách hội thoại, bấm để copy. Mọi người nhắn tới bot được lưu vào bảng zl_bot_chats.

getUpdates và webhook loại trừ nhau — Zalo trả lỗi 400 nếu gọi getUpdates khi bot đang cắm webhook.

Gửi tin tới số điện thoại (ZBS)

Tin Tư vấn của OA chỉ tới được người đã từng nhắn cho OA. Muốn gửi tới một số điện thoại bất kỳ thì phải qua ZBS Template Message — kênh duy nhất làm được việc đó.

Đổi lại ba ràng buộc, cả ba do Zalo đặt ra:

1. Chỉ gửi được theo mẫu đã đăng ký và được duyệt
2. Mỗi tin đều tính phí, trừ vào số dư tài khoản ZBS
3. OA phải được cấp quyền ZBS tại zalo.solutions

Trang OA → ZBS Template Message hiển thị mẫu tin, hạn mức còn lại, và một form gửi thử. Chọn mẫu, các ô tham số hiện ra theo đúng mẫu đó.

Chế độ gửi. Form mặc định development: tin chỉ tới được quản trị viên của OA hoặc của App, không trừ số dư chính, và gửi được cả mẫu đang chờ duyệt — đây là cách thử mẫu trước khi Zalo duyệt xong. Gửi cho khách thật phải tick production kèm một ô xác nhận nữa.

Mẫu chưa duyệt trả về danh sách tham số rỗng. Khi đó form chuyển sang ô nhập JSON; mở mẫu bên Zalo, chép tên trong cột Tên tham số (bỏ dấu <>) rồi nhập tay.

Zalo nhận tin không có nghĩa là đã giao được. Gửi xong bạn nhận msg_id; dùng ô Tra trạng thái trên cùng trang để biết tin đã tới máy người nhận chưa. Trạng thái 0 nghĩa là Zalo giữ tin nhưng chưa giao được.

Scheduler

Thêm cron sau, nếu không token sẽ hết hạn:

refresh_token của Zalo sống khoảng ba tháng và xoay vòng mỗi lần dùng. Package đăng ký sẵn zalo:token:refresh --all chạy hàng giờ.

Dùng trong code

Gửi tin nhắn

Xử lý lỗi Open API

Zalo trả HTTP 200 kèm error != 0 cho hầu hết lỗi nghiệp vụ. Package ném ApiException (bắt ZaloException để gồm cả mạng / token / cấu hình).

toArray() gồm ok, source, code, message, description, hint, category, docs, http_status. App Laravel gọi API JSON: nếu không bắt exception, package tự trả JSON đó khi request expectsJson().

category: token, rate_limit, quota, validation, recipient, permission, oa_state, zbs, bot, transport, config, unknown.

Mã OA đầy đủ: Mã lỗi Official Account API. $e->isTokenError() chỉ -216, -220, -124, 401 — không gồm -32 (rate limit) hay -217 (user chặn tin mời).

Notifier khi fail giữ errorCode và error (cùng shape toArray()), không chỉ chuỗi reason.

Notifier — chọn CS hoặc ZBS giúp bạn. Có zalo_user_id và token còn hạn thì gửi tin Tư vấn; token sắp hết / user unfollow / ngoài cửa sổ CS thì fallback ZBS theo số điện thoại (cần templateId + templateData). CS lỗi thì dừng — không tự nhảy sang ZBS để tránh gửi đôi.

Hoặc dùng helper toàn cục:

Official Account

Tin có nút bấm

Message object là immutable — mỗi lần gọi trả về bản sao mới, nên dựng sẵn tin mẫu rồi tuỳ biến cho từng người nhận là an toàn.

Gửi ảnh

OA yêu cầu upload ảnh trước để lấy attachment_id:

attachment_id dùng lại được, nên gửi cùng một ảnh cho nhiều người chỉ cần upload một lần. Package kiểm tra file tồn tại, dung lượng dưới 1 MB và đúng định dạng trước khi gọi API.

Payload tuỳ ý

Với những dạng tin package chưa bọc thành class (list, carousel, request_user_info, file):

Gọi thẳng endpoint chưa được bọc:

Bot

Bot nhận thẳng URL ảnh, không cần upload trước như OA.

ZBS Template Message

Zalo không có Open API xoá/disable template. Xoá trên ZBS Account. Trạng thái DELETE / DISABLE chỉ đọc được qua list, info(), hoặc webhook change_template_status.

API tạo/sửa đang được Zalo đánh giá lại — ưu tiên UI ZBS Account nếu không cần tạo hàng loạt. $layout là JSON docs, package không dựng DSL component.

Duyệt mẫu: lắng nghe webhook (khuyến nghị) hoặc waitUntilStatus() / zalo:zbs:wait.

Check trước khi send() — không POST tin thật, không trừ tiền:

Số điện thoại nhận mọi cách viết — 0987…, +8498…, 8498…, có dấu cách hay gạch ngang — và được quy về dạng Zalo yêu cầu trước khi gửi.

Chế độ gửi lấy từ env, mặc định development:

Mặc định là development có chủ đích: quên đổi sang production thì tin không tới khách và bạn phát hiện ngay; ngược lại, mặc định production mà quên thì bạn biết khi nhận hoá đơn. Ghi đè cho từng lần gửi bằng tham số mode:.

Nhiều OA

Kiểm tra khả dụng OA / ZBS

Zalo không có API “danh sách quyền lợi”. capabilities()->check() gọi API đọc (getoa, quota OA v3, quota/template ZBS) rồi trả report — không throw khi gói thiếu Open API, template chưa duyệt, hay hết hạn mức. Chỉ throw khi token hoặc mạng hỏng.

Mỗi mục có available + số liệu docs (remain / limit / meta). Hết hạn mức vẫn trả remain: 0.

zbs_send gộp: ZBS gọi được + mẫu ENABLE + remainingQuota > 0. Không POST /message/template.

Nhận tin nhắn

OA và Bot dùng hai URL và hai cơ chế xác thực khác nhau:

Mỗi bot có URL riêng vì payload Zalo gửi không kèm định danh bot.

ZALO_WEBHOOK_SECRET khác ZALO_APP_SECRET. Nó là OA Secret Key nằm ở phần cài đặt webhook, không phải secret của ứng dụng.

Lắng nghe event

ZaloWebhookReceived và ZaloBotUpdateReceived được bắn cho mọi loại sự kiện, kể cả loại package chưa bọc riêng.

Hành vi cần biết

• Route webhook không đi qua auth của giao diện. Chữ ký (OA) hoặc secret header (Bot) là lớp bảo vệ duy nhất.
• Chưa cấu hình secret thì webhook bị từ chối 401.
• Webhook của Bot yêu cầu HTTPS vì secret đi nguyên văn trong header.
• Mặc định xử lý qua queue (ZALO_WEBHOOK_QUEUE=true).
• Lỗi trong listener của bạn không làm webhook trả 500. Nếu trả 500, Zalo sẽ gửi lại và bạn xử lý trùng.
• Chống trùng nên dựa vào $e->messageId.

Bật ZALO_WEBHOOK_LOG=true để ghi payload vào zl_webhook_logs khi cần debug. Mặc định tắt vì payload chứa nội dung tin nhắn của người dùng.

Package không tự gửi cảnh báo khi OA mất kết nối. Lắng nghe ZaloOaDisconnected để tự xử lý.

Testing

Zalo::fake() chặn mọi lời gọi tới Zalo và cho phép assert những gì đã gửi:

Không cần OA trong DB, không cần token, không cần giả lập OAuth.

Đặt response giả:

fake() chỉ thay tầng mạng. Message builder, resource và phần validate payload vẫn chạy code thật, nên tin nhắn dựng sai (quá 2000 ký tự, nút không phải HTTPS) vẫn bị bắt trong test.

Mở rộng

Thay thành phần mà không cần fork:

OAChannel, BotChannel và các Resource đều dùng Macroable.

Tham chiếu

Chi phí và giới hạn

Tin Tư vấn (OA)

Tính từ tương tác cuối của người dùng:

Package không tự chặn khi quá 48 giờ vì nó không biết thời điểm tương tác cuối. Nếu cần kiểm soát chi phí, hãy tự lưu mốc tương tác từ webhook.

"Tương tác" gồm: gửi tin nhắn tới OA, gửi tin trong nhóm GMF, gọi thoại tới OA, đồng ý nhận cuộc gọi, bình luận bài viết, tương tác chatbot, bấm Menu hoặc CTA, bấm widget.

Khả năng của từng kênh

ZBS Template Message

Từ 01/01/2026 Zalo hợp nhất ZNS, tin UID Giao dịch và tin UID Truyền thông thành ZBS Template Message.

Hai method transaction() và promotion() trỏ tới endpoint có trước thời điểm hợp nhất và có thể đã ngừng hoạt động — dùng zbs() thay thế.

Biến môi trường

Zalo App

App credential chỉ đọc từ env, không lưu vào DB hay sửa qua giao diện.

Prefix bảng

Chốt giá trị này trước lần migrate đầu tiên. Đổi sau khi đã migrate sẽ khiến code tìm bảng theo tên mới trong khi DB giữ tên cũ.

Prefix cộng dồn với prefix của DB connection: DB_PREFIX=app_ cộng zl_ cho ra bảng app_zl_oas.

Package tạo 6 bảng: oas, oa_tokens, bots, bot_chats, audit_logs, webhook_logs.

Toàn bộ biến env

APP_KEY

Token lưu trong DB được mã hoá bằng APP_KEY. Đổi APP_KEY sẽ làm mất toàn bộ token và phải cấp quyền lại cho mọi OA.

Commands

Gặp vấn đề thì chạy zalo:doctor trước — lệnh này kiểm credential, redirect URI, bảng, mã hoá, giao diện, scheduler, từng OA và từng Bot.

Phát triển package

Đóng góp

Xem CODE_OF_CONDUCT.md.

Bảo mật

Phát hiện lỗ hổng? Xem SECURITY.md — vui lòng không mở public issue.

License

MIT — xem LICENSE.