Skip to content

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 code from it.
  • The ph command on your machine, to test the kit before you touch the server.
  • The kit version and its sha256 from the kit-notify-zalo resource page on Tara. Use them as kit-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 ​

  1. Open https://developers.zalo.me and sign in with the account that manages the OA.
  2. Choose Create app. Enter a display name, a category, and a description.
  3. After you save, copy the App ID. Open the app settings and copy the secret key. Keep it private.
Illustration, the real screen may differ slightly. Fill in the form and choose the create app ID button (1). The app page then shows the App ID and the app secret key (2).
  1. In the app, open Official Account, then General settings.
  2. Set Official Account Callback Url to your HTTPS callback address, and link your OA.
  3. Register the Official Account API permissions for sending messages and for user management, and submit the app for review.
  4. After the review, activate the app.
Under Official Account, General settings: enter the Official Account Callback Url and choose Update (1), then request the message and user permissions (2).

3. Authorize the app ​

  1. Build the permission link with your App ID and callback URL, and open it in a browser. Add code_challenge if you use PKCE.
  2. Choose your OA, agree to the terms, and allow the app.
  3. The browser goes to your callback address with ?oa_id=…&code=…. Copy the code right away.
text
https://oauth.zaloapp.com/v4/oa/permission?app_id=<APP_ID>&redirect_uri=<CALLBACK_URL>
Choose the OA (1), accept the terms (2) and choose Allow (3). The browser goes to your callback address with code=… (4).

4. Get the access token ​

Exchange the code for tokens. Run this right after step 3, and use each code only once.

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

With PKCE, add -d "code_verifier=<verifier>". The answer has three values:

FieldMeaning
access_tokenThe secret that the kit uses
refresh_tokenGets a new access token. Store it safely
expires_inLifetime of the access token, in seconds
The answer contains the access_token (1) and the refresh_token (2). Read expires_in to know when to renew.

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:

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

Each user_id under data.users is one recipient (1).

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

bash
PHILLIP_KIT_TOKEN=<access token> ph kit check kit-notify-zalo --set userIds=<id1,id2> --send "test"
  • With --live, the command calls check(), 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 each user_id. A recipient outside the delivery window fails with not_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.

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>"}}
ServiceKitsDefault settingsSecret
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 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.

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

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

  1. 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.
  2. Choose the Organization and the Plugin kit-notify-zalo.
  3. In Organization-specific settings, enter userIds=<id1,id2>, one name=value per line.
  4. Choose the events to receive, then save.
  5. In the row's actions menu, choose Send test.
Enter userIds=… in Organization-specific settings (1), choose the events (2), then choose Save (3). Send a test from the channel row's actions menu.

You can do the same from the command line:

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

Troubleshooting ​

Error textCauseFix
the Zalo OA access token is missingThe secret variable is empty or has the wrong nameSet <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_ZALO and restart
settings.userIds is missing (recipients' Zalo user_ids, separated by commas; …)No recipientsAdd userIds with comma-separated IDs
Zalo rejected the access token (HTTP 401): has the token expired?The token is wrong or expiredRefresh 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 sentFix the failing user_id, or ask that person to message the OA
could not reach ZaloThe server cannot reach openapi.zalo.meOpen 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 downWait. Tara retries up to 8 times

Limits ​

  • Recipients are individual people, not a group. The user_id belongs 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 to address, because the destination is the Zalo user_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.

Further reading ​