Set up Zalo OA notifications
This guide connects the kit-notify-zalo kit to a Zalo Official Account (OA). After it, Tara, Ryoma, or Bandum can send advisory messages ("tin Tu van") to people on Zalo. It is the longest of the four setups, because Zalo needs an app, an authorization, and a token that you must renew.
About the pictures
The figures are illustrations that show where to click. Zalo and the Portal change their screens from time to time, so the real screen may look a little different. Check the official Zalo documents when a name differs.
Who this is for
- An administrator who installs notification kits on a server (see Notifications).
- The owner of a Zalo Official Account who can create an app on developers.zalo.me.
Read this first: when Zalo can deliver
Zalo sends a customer-service message through the OA OpenAPI only under these rules (see the official guide):
- The recipient interacted with the OA in the last 7 days: messaged it, called, commented, or tapped a menu or CTA. Following the OA alone is not an interaction.
- The recipient has not blocked the OA.
- The message is free within the first 48 hours after the interaction and charged by Zalo's price list after that. Beyond 7 days Zalo rejects it.
So treat Zalo as a secondary channel, and ask recipients to message the OA regularly. Use Telegram, Slack, or email for alerts that must always arrive.
Before you start
- A Zalo Official Account, and an account that manages it.
- An HTTPS address that can receive a redirect (the callback URL), so you can read the
codefrom it. - The
phcommand on your machine, to test the kit before you touch the server. - The kit version and its sha256 from the
kit-notify-zaloresource page on Tara. Use them askit-notify-zalo@<version>:<sha256>. - A place on the server to store tokens and a way to restart the service (see "Renew the token automatically").
1. Create the app
- Open
https://developers.zalo.meand sign in with the account that manages the OA. - Choose Create app. Enter a display name, a category, and a description.
- After you save, copy the App ID. Open the app settings and copy the secret key. Keep it private.
2. Link the OA and register permissions
- In the app, open Official Account, then General settings.
- Set Official Account Callback Url to your HTTPS callback address, and link your OA.
- Register the Official Account API permissions for sending messages and for user management, and submit the app for review.
- After the review, activate the app.
3. Authorize the app
- Build the permission link with your App ID and callback URL, and open it in a browser. Add
code_challengeif you use PKCE. - Choose your OA, agree to the terms, and allow the app.
- The browser goes to your callback address with
?oa_id=…&code=…. Copy thecoderight away.
https://oauth.zaloapp.com/v4/oa/permission?app_id=<APP_ID>&redirect_uri=<CALLBACK_URL>4. Get the access token
Exchange the code for tokens. Run this right after step 3, and use each code only once.
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>"With PKCE, add -d "code_verifier=<verifier>". The answer has three values:
| Field | Meaning |
|---|---|
access_token | The secret that the kit uses |
refresh_token | Gets a new access token. Store it safely |
expires_in | Lifetime of the access token, in seconds |
The access token is short-lived. Do not guess its lifetime: read expires_in and renew well before it ends.
5. Get the user IDs
The kit sends to Zalo user_id values, not phone numbers. A user_id belongs to one OA. Ask each recipient to message the OA first, because they need a recent interaction anyway. Then list the users:
curl -G https://openapi.zalo.me/v3.0/oa/user/getlist \
-H "access_token: <access token>" \
--data-urlencode 'data={"offset":0,"count":50}'Read data.users[].user_id in the answer. You can also read sender.id from an OA webhook event.
6. Test the kit with ph kit check
Pass the access token through the PHILLIP_KIT_TOKEN variable, never as an argument. The command ph kit check takes a kit folder or name[@version], repeated --set key=value, --live, and --send <text>.
PHILLIP_KIT_TOKEN=<access token> ph kit check kit-notify-zalo --set userIds=<id1,id2> --send "test"- With
--live, the command callscheck(), which reads the OA information (/v2.0/oa/getoa) and sends nothing. It cannot test each recipient without sending. - With
--send, it sends a real message to eachuser_id. A recipient outside the delivery window fails withnot_found.
7. Configure the service
Tara, Ryoma, and Bandum use the same kit. Each service has its own variable prefix. The example below is for Ryoma. Take <version> and <sha256> from the Tara resource page.
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>"}}| Service | Kits | Default settings | Secret |
|---|---|---|---|
| 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 also needs TARA_NOTIFY_TOKEN, a read-only Tara token that downloads the kit package. The service reads the secret at startup, so renewing the token means updating the variable and restarting the service. For the other variables, see Notifications.
8. Renew the token automatically
The kit keeps no state and writes no files, so it cannot renew the token. You run a small job that refreshes the token, stores the new values, and restarts the service. Each refresh returns a new refresh token: store it and stop using the old one.
The script below is only an example. Adapt the paths, the secret store, and the restart command to your setup.
#!/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.shRun it first by hand and check the service log. If you lose the latest refresh token, authorize again from step 3.
9. Choose the channel for each organization
The secret stays one per kit on the server. Each organization sets its own recipients.
- Sign in to the Portal as an owner or admin of the organization. Open the account menu, then Admin, then Notifications, then add a channel.
- Choose the Organization and the Plugin
kit-notify-zalo. - In Organization-specific settings, enter
userIds=<id1,id2>, onename=valueper line. - Choose the events to receive, then save.
- In the row's actions menu, choose Send test.
You can do the same from the command line:
ph tara notify set <org> kit-notify-zalo --set userIds=<id1,id2> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-zaloTroubleshooting
| Error text | Cause | Fix |
|---|---|---|
the Zalo OA access token is missing | The secret variable is empty or has the wrong name | Set <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_ZALO and restart |
settings.userIds is missing (recipients' Zalo user_ids, separated by commas; …) | No recipients | Add userIds with comma-separated IDs |
Zalo rejected the access token (HTTP 401): has the token expired? | The token is wrong or expired | Refresh the token (step 8), update the variable, and restart |
Zalo error -216: … (Zalo access tokens are short-lived: issue a new token) | The token expired or is invalid (errors -216, -124, -118) | Same as above |
Zalo error -213: … (has the recipient interacted with the OA within the last 7 days and not blocked it? …) | The recipient is outside the delivery window, blocked the OA, or does not exist (errors -213, -212, -230) | Ask the person to message the OA, then try again. Check the user_id |
1/2 recipients failed; … | One recipient failed. The others were sent | Fix the failing user_id, or ask that person to message the OA |
could not reach Zalo | The server cannot reach openapi.zalo.me | Open the network route, or set apiUrl to your internal proxy |
Zalo is temporarily failing (HTTP 429) or (HTTP 5xx) | Zalo limits the rate or is down | Wait. Tara retries up to 8 times |
Limits
- Recipients are individual people, not a group. The
user_idbelongs to one OA. - A message is cut at 2000 characters.
check()reads the OA information only. It cannot tell whether a recipient is inside the delivery window.- The kit ignores the
toaddress, because the destination is the Zalouser_id. - The kit sends advisory messages only. It does not send ZNS or broadcast messages.
- Messages carry metadata and links only, never the content of work.
Official documents: Advisory messages and Authentication and authorization.