Monitor and Troubleshoot Zalo¶
Guide Info
Zalo channel failures often lack clear error messages — messages don’t reach customers, ZBS templates get rejected, or webhooks go silent. This guide helps Admin/IT pinpoint the exact error category from the start, avoiding wasted time escalating when you can handle it.
Error Categories¶
Error Group |
Symptom |
Where to Check |
|---|---|---|
Token / Authorization |
OA account status is Error, or the account card shows Token invalid with a red warning icon |
|
Webhook not receiving |
Customer messages do not appear in Discuss |
Zalo OA Developer Console → Webhook settings |
Send failure |
Zalo State = Failed in the Zalo Events list |
Zalo Events list (Admin grants access) |
ZBS template rejected / disabled |
Template status is Rejected or Disabled |
→ ZBS Templates button |
Recipient not identified |
“no valid phone was found” error; message cannot send |
Contact form in Viindoo → check phone number |
Check Failed Messages¶
Access: Open the Zalo Events list — access is granted by Admin (this list has no default menu item; Admin makes it reachable). Then filter by customer/OA to check.
Two status columns on the list:
Processing State — Received / Queued / Processing / Processed / Error (Viindoo failed to process)
Zalo State — On Queue / Sent / Delivered / Received / Read / Failed (Zalo failed to deliver)
Quick filter: search bar → filter Errors (processing error) or Failed Deliveries (Zalo reported failure).
Recover from message form:
Open failed message → check Processing State and Zalo State.
If Processing State = Error → click “Retry Processing” to have Viindoo process again from the start.
If Zalo State = Failed (outbound message) → click “Resend” to resend to Zalo.
If message is stuck with unclear status → click “Mark Error” to manually flag it, then retry.
Check OA Token and Webhook¶
Menu:
Open the OA account record and check:
Field / Indicator |
Meaning |
|---|---|
Account status bar |
Draft / Connected / Error - needs re-authorization if not Connected. The bar also lists Expired, but Viindoo does not set it by itself: a token problem shows as Error. |
Token Expires At |
In the OAuth Authorization tab, which appears only while the account is Connected. When the token expires; if past this date → re-authorize immediately |
Token Valid |
In the same tab: ticked = Viindoo holds a token that has not reached its expiry. The account card in the Accounts view shows the same as Token valid (green check) or Token invalid (red warning); invalid also covers an account that was never authorized. |
OAuth Callback URL |
Read-only — must match exactly the URL registered in Zalo OA Developer Console |
Webhook URL |
Read-only — copy and paste into Webhook configuration in Zalo OA Developer Console |
Recover token:
When authorization does not complete, either the Zalo tab ends on a plain page with a short message, or the tab never opens. Find what you see below: in every case the fix is to click “Authorize Account” again - you never need to reset the account first.
Symptom |
Cause |
Solution |
|---|---|---|
“Authorization failed. You can close this tab.”; the account status is Error (unchanged if the refusal came after the 10 minutes) |
Zalo returned a refusal instead of a permission, for example because the request was declined on the permission page. Viindoo marks the account Error and stores no new token. If the refusal reaches Viindoo after the 10 minutes, the tab shows the same message but the status does not change. |
Close the tab, reload the account form and follow the steps below. |
“The authorization request is invalid or has expired.”; the account status does not change |
More than 10 minutes passed since Viindoo created the link (the 10 minutes do not restart when you click “Authorize Account” again, which reopens the same link), or the tab was opened from an older link. |
Follow the steps below. Viindoo creates a fresh link by itself, so no reset is needed. |
“Authorization failed:” followed by a reason, or “Authorization failed due to an unexpected error.”; the account status is Error |
Viindoo received the permission but could not turn it into a token. The reason after the colon says why. |
Follow the steps below. If the same reason comes back, check App ID, re-enter the App Secret copied from the Zalo app (the field shows dots only, so you cannot compare it by eye) and check that the OAuth Callback URL registered in the Zalo OA Developer Console matches the one on the form. |
Nothing opens after you click “Authorize Account”; a warning says a popup window has been blocked |
The browser blocked the new tab that holds the Zalo permission page. |
Allow popups for your Viindoo address, then click “Authorize Account” again. |
Open the account and click “Authorize Account” to restart OAuth. Viindoo opens the Zalo permission page in a new tab. Its link works for 10 minutes from the moment it is created (clicking again within that time reopens the same link and does not restart the 10 minutes), and a click after that creates a fresh link automatically.
On the Zalo page, select the OA you are connecting (Zalo preselects the first OA in your list, which may not be yours) and check that the line under the page header names it, tick the checkbox that accepts Zalo’s terms of use and press Cấp quyền.
After authorization completes → click “Sync OA Profile” to confirm successful connection.
Tip
You know it worked when the browser returns to the account form with the status bar on Connected. After “Sync OA Profile”, OA Name and OA ID in the Profile Get From Zalo tab belong to the OA you meant to connect; if they do not, the wrong OA was authorized and the sync has already imported its followers as Zalo contacts (see the warning below). A plain page with a message instead of the form means authorization did not complete: use the table above.
Note
“Authorize Account” is shown only while the account has no valid token. If you cannot see it, Viindoo still holds a token that has not reached its expiry: click “Sync OA Profile” to re-check the connection, and read the API log if it fails again (see View API Logs below). If you already know the account is connected to the wrong OA, skip the sync and use “Clear OAuth Session” below.
Warning
“Clear OAuth Session” is a deliberate reset, not a repair step. Never use it to fix a failed or expired authorization: click “Authorize Account” again instead.
It deletes the OAuth session and the access and refresh tokens, and sets the account back to Draft (it can turn Error once something tries to call Zalo). From that moment Viindoo cannot call Zalo: every send stops with the error “Missing access token. Please authorize this account.”, Viindoo can no longer renew the token by itself, and a Zalo tab still open from an earlier click stops working. Only a completed “Authorize Account” restores the connection; it needs someone who administers the OA on Zalo to press Cấp quyền, and the deleted tokens cannot be recovered.
Use it only when you want to disconnect the OA on purpose and connect again from scratch, for example after authorizing the wrong OA. It disconnects the account but does not delete the Zalo contacts that “Sync OA Profile” already imported from that OA. If you are unsure, click “Authorize Account” or “Sync OA Profile” instead: neither deletes the tokens.
Webhook not receiving events:
Copy the Webhook URL field value → paste into Zalo OA Developer Console → Webhook settings.
Ensure you have enabled all necessary event groups: conversation (user_send_*), delivery status, follow/unfollow, ZBS status (change_template_status, change_template_quota, user_feedback).
Check ZBS Templates¶
Access: → select the OA account to check → click ZBS Templates button at top of form.
Template statuses: Draft → Pending → Approved / Rejected / Disabled
Rejected template:
Open template → read the Reject Reason field — Zalo states the reason clearly.
Click Reset to Draft when available, then edit the rejected template according to the feedback.
Review the corrected preview, then click Submit to Zalo to resubmit for approval.
Disabled template:
Disabled means Zalo has deactivated the template. Check the status details and API response rather than inferring the reason from this status alone.
Template Quality field shows the quality score from Zalo (read-only).
Note
Viindoo displays template quality when Zalo supplies it, but the template form does not show allowance counters. Check the relevant sending allowance and account balance separately in Zalo’s management tools; a quota error does not by itself mean the template is Disabled.
Recipient not identified:
Symptom |
Cause |
Solution |
|---|---|---|
“no valid phone was found” |
Contact has no phone number or wrong format |
Update phone number in format 84xxxxxxxxx in contact record |
Send via UID does not arrive |
Partner has no Zalo UID link in Viindoo |
Route Policy is read-only. Check the customer’s Zalo link at Manage Zalo Partner Links, or select an approved template whose route matches the available UID or phone data. |
View API Logs¶
API logs record every request Viindoo sends to Zalo and every response Zalo returns — the most accurate source when you need to know the exact error code.
Three access points:
From OA account form → “API Logs” button
From message form in Zalo Events → “API Logs” button
From ZBS template form → “API Logs” button
Read a log entry:
HTTP status code — 200 means the API responded; also check the JSON error code and message. HTTP 401 indicates an authorization problem, while HTTP 429 indicates too many requests. Read the response to determine the cause.
Error message — may describe a failure. An empty value does not prove success; inspect the JSON response and the corresponding Zalo message state.
Duration — request processing time in seconds; a long duration alone does not prove a timeout.
Open the log form to see complete request body and response data
Pre-Escalation Checklist¶
Tip
Complete all steps below before reporting to dev or contacting Zalo support:
Open API log of the failed action → note HTTP status code and error message.
Check OA account status and the Token valid / Token invalid line on the account card → re-authorize if the token is invalid.
Go to Zalo Events → filter failed messages → note Processing State and Zalo State.
For ZBS templates: read the Reject Reason and Template Quality fields.
Check Zalo OA Developer Console: quota limits, webhook URL, OA account status.
Summarize for escalation: OA name, account status, error message timestamp, API log entry, error message content.