Cài thông báo Zalo OA
Hướng dẫn này nối kit kit-notify-zalo vào một Zalo Official Account (OA). Xong rồi, Tara, Ryoma hoặc Bandum gửi được tin tư vấn tới từng người trên Zalo. Đây là kênh cài lâu nhất trong bốn kênh, vì Zalo cần một app, một bước cấp quyền và một token mà bạn phải gia hạn.
Về các hình
Các hình là hình minh họa, chỉ cho bạn thấy cần bấm vào đâu. Zalo và Portal thỉnh thoảng đổi giao diện nên màn hình thật có thể hơi khác. Khi tên gọi không khớp, bạn đối chiếu với tài liệu chính thức của Zalo.
Dành cho ai
- Quản trị viên cài kit thông báo lên máy chủ (xem Thông báo).
- Chủ của Zalo Official Account, người tạo được app trên developers.zalo.me.
Đọc trước: khi nào Zalo gửi được
Zalo chỉ cho gửi tin tư vấn qua OpenAPI của OA khi đủ các điều kiện sau (xem hướng dẫn chính thức):
- Người nhận đã tương tác với OA trong 7 ngày gần nhất: nhắn tin, gọi, bình luận, hoặc bấm menu hay CTA. Chỉ quan tâm OA thì chưa tính là tương tác.
- Người nhận chưa chặn OA.
- Tin gửi trong 48 giờ đầu sau lần tương tác thì miễn phí, sau đó Zalo tính phí theo bảng giá của họ. Quá 7 ngày thì Zalo từ chối.
Vì vậy bạn nên coi Zalo là kênh phụ, và nhờ người nhận nhắn OA đều đặn. Cảnh báo nào bắt buộc phải tới nơi thì dùng Telegram, Slack hoặc email.
Trước khi bắt đầu
- Một Zalo Official Account, và tài khoản đang quản lý OA đó.
- Một địa chỉ HTTPS nhận được lượt chuyển hướng (callback URL), để bạn đọc được
codetừ đó. - Lệnh
phtrên máy của bạn, để thử kit trước khi đụng vào máy chủ. - Version và sha256 của kit trên trang tài nguyên
kit-notify-zalocủa Tara. Bạn dùng chúng dưới dạngkit-notify-zalo@<version>:<sha256>. - Một nơi trên máy chủ để lưu token và cách khởi động lại dịch vụ (xem mục "Gia hạn token tự động").
1. Tạo app
- Mở
https://developers.zalo.mevà đăng nhập bằng tài khoản đang quản lý OA. - Mở hộp Tạo ứng dụng mới, nhập tên hiển thị, danh mục và mô tả, rồi bấm Tạo ID ứng dụng.
- Lưu xong, chép App ID. Mở phần cài đặt của app và chép secret key. Giữ kín khóa này.
2. Liên kết OA và đăng ký quyền
- Trong app, mở Official Account, rồi General settings.
- Đặt Official Account Callback Url là địa chỉ HTTPS của bạn, và liên kết OA của bạn.
- Đăng ký các quyền Official Account API để gửi tin nhắn và quản lý người dùng, rồi gửi app đi xét duyệt.
- Sau khi được duyệt, kích hoạt app.
3. Cấp quyền cho app
- Ghép link cấp quyền từ App ID và callback URL của bạn, rồi mở trong trình duyệt. Nếu dùng PKCE thì thêm
code_challenge. - Chọn OA của bạn, đồng ý điều khoản và cho phép app.
- Trình duyệt chuyển về địa chỉ callback của bạn kèm
?oa_id=…&code=…. Chép ngaycode.
https://oauth.zaloapp.com/v4/oa/permission?app_id=<APP_ID>&redirect_uri=<CALLBACK_URL>4. Lấy access token
Bạn đổi code lấy token. Chạy ngay sau bước 3, và mỗi code chỉ dùng một lần.
curl -X POST https://oauth.zaloapp.com/v4/oa/access_token \
-H "secret_key: <app secret>" \
-d "app_id=<APP_ID>" \
-d "grant_type=authorization_code" \
-d "code=<code>"Nếu dùng PKCE, thêm -d "code_verifier=<verifier>". Kết quả có ba giá trị:
| Trường | Ý nghĩa |
|---|---|
access_token | Bí mật mà kit dùng |
refresh_token | Dùng để lấy access token mới. Lưu cẩn thận |
expires_in | Thời gian sống của access token, tính bằng giây |
Access token sống ngắn. Bạn đừng đoán thời gian sống: hãy đọc expires_in và gia hạn từ sớm.
5. Lấy user ID
Kit gửi theo user_id của Zalo, không dùng số điện thoại. Mỗi user_id chỉ thuộc về một OA. Bạn nhờ từng người nhận nhắn OA trước, vì dù sao họ cũng cần một lần tương tác gần đây. Rồi bạn liệt kê người dùng:
curl -G https://openapi.zalo.me/v3.0/oa/user/getlist \
-H "access_token: <access token>" \
--data-urlencode 'data={"offset":0,"count":50}'Bạn đọc data.users[].user_id trong kết quả. Cách khác là đọc sender.id từ sự kiện webhook của OA.
6. Thử kit bằng ph kit check
Bạn đưa access token qua biến PHILLIP_KIT_TOKEN, không bao giờ đưa qua tham số. Lệnh ph kit check nhận thư mục kit hoặc tên[@version], các --set key=value (lặp được), --live và --send <text>.
PHILLIP_KIT_TOKEN=<access token> ph kit check kit-notify-zalo --set userIds=<id1,id2> --send "test"- Có
--live, lệnh gọicheck(): đọc thông tin OA (/v2.0/oa/getoa) và không gửi gì. Lệnh không kiểm được từng người nhận nếu không gửi. - Có
--send, lệnh gửi một tin thật tới từnguser_id. Người nhận ngoài khung thời gian gửi sẽ lỗinot_found.
7. Cấu hình dịch vụ
Tara, Ryoma và Bandum dùng chung một kit. Mỗi dịch vụ có tiền tố biến riêng. Ví dụ dưới đây là cho Ryoma. Bạn lấy <version> và <sha256> trên trang tài nguyên của Tara.
RYOMA_NOTIFY_PLUGINS=kit-notify-zalo@<version>:<sha256>
RYOMA_NOTIFY_SECRET_KIT_NOTIFY_ZALO=<access token>
RYOMA_NOTIFY_SETTINGS={"kit-notify-zalo":{"userIds":"<id1,id2>"}}| Dịch vụ | Kit | Settings mặc định | Bí mật |
|---|---|---|---|
| Tara | TARA_NOTIFY_PLUGINS | TARA_NOTIFY_SETTINGS | TARA_NOTIFY_SECRET_KIT_NOTIFY_ZALO |
| Ryoma | RYOMA_NOTIFY_PLUGINS | RYOMA_NOTIFY_SETTINGS | RYOMA_NOTIFY_SECRET_KIT_NOTIFY_ZALO |
| Bandum | BANDUM_NOTIFY_PLUGINS | BANDUM_NOTIFY_SETTINGS | BANDUM_NOTIFY_SECRET_KIT_NOTIFY_ZALO |
Tara còn cần TARA_NOTIFY_TOKEN, token Tara chỉ đọc để tải gói kit. Dịch vụ đọc bí mật lúc khởi động, nên gia hạn token nghĩa là cập nhật biến rồi khởi động lại dịch vụ. Các biến còn lại có trong trang Thông báo.
8. Gia hạn token tự động
Kit không giữ trạng thái và không ghi file, nên nó không tự gia hạn token được. Bạn chạy một tác vụ nhỏ: làm mới token, lưu giá trị mới, rồi khởi động lại dịch vụ. Mỗi lần làm mới cho ra một refresh token mới: bạn lưu nó lại và bỏ cái cũ.
Đoạn script dưới đây chỉ là ví dụ. Bạn sửa đường dẫn, nơi lưu bí mật và lệnh khởi động lại cho khớp hệ thống của mình.
#!/bin/sh
# EXAMPLE ONLY: adapt paths, secret store and restart command.
set -eu
umask 077
APP_ID=<APP_ID>
SECRET_KEY=<app secret>
STATE=/etc/zalo/refresh_token
ENV_FILE=/opt/ryoma/.env
REFRESH=$(cat "$STATE")
RESP=$(curl -s -X POST https://oauth.zaloapp.com/v4/oa/access_token \
-H "secret_key: $SECRET_KEY" \
-d "app_id=$APP_ID" -d "grant_type=refresh_token" -d "refresh_token=$REFRESH")
ACCESS=$(printf '%s' "$RESP" | jq -r '.access_token // empty')
NEW_REFRESH=$(printf '%s' "$RESP" | jq -r '.refresh_token // empty')
[ -n "$ACCESS" ] && [ -n "$NEW_REFRESH" ] || { echo "refresh failed" >&2; exit 1; }
printf '%s' "$NEW_REFRESH" > "$STATE"
sed -i "s|^RYOMA_NOTIFY_SECRET_KIT_NOTIFY_ZALO=.*|RYOMA_NOTIFY_SECRET_KIT_NOTIFY_ZALO=$ACCESS|" "$ENV_FILE"
systemctl restart ryoma
# cron: run it at an interval shorter than expires_in
# <schedule> /usr/local/bin/renew-zalo-token.shBạn chạy thử bằng tay trước và xem log của dịch vụ. Nếu làm mất refresh token mới nhất, bạn cấp quyền lại từ bước 3.
9. Chọn kênh cho từng tổ chức
Bí mật chỉ có một cho mỗi kit trên máy chủ. Mỗi tổ chức tự đặt danh sách người nhận của mình.
- Đăng nhập Portal bằng tài khoản owner hoặc admin của tổ chức. Mở menu tài khoản, chọn Admin, rồi Notifications, rồi thêm một kênh.
- Chọn Organization và Plugin là
kit-notify-zalo. - Trong Organization-specific settings, nhập
userIds=<id1,id2>, mỗi dòng một cặpname=value. - Chọn các sự kiện muốn nhận rồi lưu.
- Ở menu thao tác của dòng, chọn Send test.
Bạn cũng làm được việc này bằng dòng lệnh:
ph tara notify set <org> kit-notify-zalo --set userIds=<id1,id2> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-zaloXử lý lỗi
| Nội dung lỗi | Nguyên nhân | Cách sửa |
|---|---|---|
the Zalo OA access token is missing | Biến bí mật trống hoặc đặt sai tên | Đặt <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_ZALO rồi khởi động lại |
settings.userIds is missing (recipients' Zalo user_ids, separated by commas; …) | Chưa có người nhận | Thêm userIds gồm các ID cách nhau bằng dấu phẩy |
Zalo rejected the access token (HTTP 401): has the token expired? | Token sai hoặc đã hết hạn | Làm mới token (bước 8), cập nhật biến rồi khởi động lại |
Zalo error -216: … (Zalo access tokens are short-lived: issue a new token) | Token hết hạn hoặc không hợp lệ (các lỗi -216, -124, -118) | Làm như dòng trên |
Zalo error -213: … (has the recipient interacted with the OA within the last 7 days and not blocked it? …) | Người nhận ngoài khung thời gian gửi, đã chặn OA, hoặc không tồn tại (các lỗi -213, -212, -230) | Nhờ người đó nhắn OA rồi thử lại. Kiểm tra lại user_id |
1/2 recipients failed; … | Một người nhận bị lỗi, những người còn lại vẫn được gửi | Sửa user_id bị lỗi, hoặc nhờ người đó nhắn OA |
could not reach Zalo | Máy chủ không gọi tới được openapi.zalo.me | Mở đường mạng, hoặc đặt apiUrl về proxy nội bộ |
Zalo is temporarily failing (HTTP 429) hoặc (HTTP 5xx) | Zalo giới hạn tốc độ hoặc đang lỗi | Chờ. Tara thử lại tối đa 8 lần |
Giới hạn
- Người nhận là từng cá nhân, không có nhóm. Mỗi
user_idchỉ thuộc về một OA. - Tin nhắn bị cắt ở 2000 ký tự.
check()chỉ đọc thông tin OA. Nó không cho biết người nhận có nằm trong khung thời gian gửi hay không.- Kit bỏ qua địa chỉ
to, vì đích gửi làuser_idcủa Zalo. - Kit chỉ gửi tin tư vấn. Nó không gửi ZNS hay tin truyền thông.
- Tin chỉ chứa siêu dữ liệu và liên kết, không bao giờ có nội dung công việc.
Tài liệu chính thức: Tin Tư vấn và Xác thực và ủy quyền.