Bỏ qua, đến phần nội dung

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 code từ đó.
  • Lệnh ph trê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-zalo của Tara. Bạn dùng chúng dưới dạng kit-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 ​

  1. Mở https://developers.zalo.me và đăng nhập bằng tài khoản đang quản lý OA.
  2. 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.
  3. 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.
Hình minh họa, màn hình thật có thể hơi khác. Điền form rồi bấm Tạo ID ứng dụng (1). Trang ứng dụng sẽ hiện ID ứng dụng và khóa bí mật (2).

2. Liên kết OA và đăng ký quyền ​

  1. Trong app, mở Official Account, rồi General settings.
  2. Đặt Official Account Callback Url là địa chỉ HTTPS của bạn, và liên kết OA của bạn.
  3. Đă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.
  4. Sau khi được duyệt, kích hoạt app.
Trong Official Account › Thiết lập chung, nhập Official Account Callback Url rồi bấm Cập nhật (1), sau đó đăng ký quyền gửi tin và quản lý người dùng (2).

3. Cấp quyền cho app ​

  1. 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.
  2. Chọn OA của bạn, đồng ý điều khoản và cho phép app.
  3. Trình duyệt chuyển về địa chỉ callback của bạn kèm ?oa_id=…&code=…. Chép ngay code.
text
https://oauth.zaloapp.com/v4/oa/permission?app_id=<APP_ID>&redirect_uri=<CALLBACK_URL>
Chọn OA (1), đồng ý điều khoản (2) rồi bấm Cho phép (3). Trình duyệt chuyển về địa chỉ callback kèm code=… (4).

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.

bash
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_tokenBí mật mà kit dùng
refresh_tokenDùng để lấy access token mới. Lưu cẩn thận
expires_inThời gian sống của access token, tính bằng giây
Kết quả có access_token (1) và refresh_token (2). Xem expires_in để biết khi nào cần gia hạn.

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:

bash
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.

Mỗi user_id trong data.users là một người nhận (1).

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>.

bash
PHILLIP_KIT_TOKEN=<access token> ph kit check kit-notify-zalo --set userIds=<id1,id2> --send "test"
  • Có --live, lệnh gọi check(): đọ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ừng user_id. Người nhận ngoài khung thời gian gửi sẽ lỗi not_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.

bash
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ụKitSettings mặc địnhBí mật
TaraTARA_NOTIFY_PLUGINSTARA_NOTIFY_SETTINGSTARA_NOTIFY_SECRET_KIT_NOTIFY_ZALO
RyomaRYOMA_NOTIFY_PLUGINSRYOMA_NOTIFY_SETTINGSRYOMA_NOTIFY_SECRET_KIT_NOTIFY_ZALO
BandumBANDUM_NOTIFY_PLUGINSBANDUM_NOTIFY_SETTINGSBANDUM_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.

bash
#!/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.sh

Bạ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.

  1. Đă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.
  2. Chọn Organization và Plugin là kit-notify-zalo.
  3. Trong Organization-specific settings, nhập userIds=<id1,id2>, mỗi dòng một cặp name=value.
  4. Chọn các sự kiện muốn nhận rồi lưu.
  5. Ở menu thao tác của dòng, chọn Send test.
Nhập userIds=… vào Organization-specific settings (1), chọn sự kiện (2), rồi bấm Save (3). Gửi thử bằng menu thao tác ở dòng của kênh.

Bạn cũng làm được việc này bằng dòng lệnh:

bash
ph tara notify set <org> kit-notify-zalo --set userIds=<id1,id2> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-zalo

Xử lý lỗi ​

Nội dung lỗiNguyên nhânCách sửa
the Zalo OA access token is missingBiế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ậnThê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ạnLà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ửiSửa user_id bị lỗi, hoặc nhờ người đó nhắn OA
could not reach ZaloMáy chủ không gọi tới được openapi.zalo.meMở đườ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ỗiChờ. 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_id chỉ 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_id củ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.

Đọc thêm ​