docs(channels/zalo): rewrite zalo-oa, add zalo-bot — GH-966#63
Draft
vanducng wants to merge 6 commits into
Draft
docs(channels/zalo): rewrite zalo-oa, add zalo-bot — GH-966#63vanducng wants to merge 6 commits into
vanducng wants to merge 6 commits into
Conversation
Migrates the operator-facing Zalo channel guides from goclaw/docs to the public docs site, splitting into two pages aligned with the zalo_bot/zalo_oa channel rename. - channels/zalo-oa.md: full rewrite — OAuth v4 setup, polling-default (poll_count=10, poll_burndown_max_pages=10), webhook bootstrap flow, signature verification, quoted replies, reaction levels, inline error code reference table. - channels/zalo-bot.md: new page — single-token setup, polling-default, webhook with X-Bot-Api-Secret-Token header, DM-only, pairing flow, inline Bot API error code table. - VI/ZH locale mirrors with TODO-translate comments and audit-script compatible footers (cập nhật: for vi). - Quadruple-sync nav: README, DOC_MAP, sidebar, channels/INDEX.md (Quick Start + Comparison Table updated for OAuth+webhook reality). - Audit mapping extends internal/channels/zalo/* to cover both new pages. - llms.txt + llms-full.txt regenerated.
Cross-checked against Zalo developer documentation: - Prerequisites now distinguish app (developers.zalo.me) vs OA (oa.zalo.me) and surface the Liên kết OA step. - Add permission-groups requirement (Quản lý tin nhắn, Quản lý người quan tâm, Upload, Webhook); without these, API calls fail with -216. - Add token lifecycle callout: 1h access, 90d single-use refresh with automatic rotation; refresh failure → re-consent. - New Media Limits section with per-endpoint caps (image 1 MB, file 5 MB, gif 5 MB) — these are Zalo server-side, not GoClaw config. - Error code table now distinguishes -216 (perms) vs -217 (token expired, auto-recovers) vs -220/-118 (refresh dead, re-consent). Bot page unchanged structurally; SHA bumped for footer freshness.
…tion note Helps users decide between Zalo OA, Zalo Bot, and Zalo Personal. - Add identical "Choosing your Zalo variant" section to both zalo-oa.md and zalo-bot.md, with a 13-row capability matrix covering official support status, auth model, account type, DM/group support, multi- account capacity, token rotation, message types, image cap, quotas, ban risk, and best-fit use cases. - Note Bot platform (bot.zapps.me) is newer than the OA API and the surface is still expanding (sticker + chat-action endpoints landed recently per https://bot.zapps.me/docs/). - Note Personal uses reverse-engineered protocol; not for production. - End each comparison with a "Quick decision" one-liner. Replaces the prior 6-row Bot vs OA mini-table and 3-row OA-anchored mini-table with a unified, decision-oriented matrix.
…r table Switch the Social API error-code reference link from the static-CDN host (stc-developers.zdn.vn) to the canonical user-facing URL on developers.zalo.me. The CDN URL still resolves but is not the official documentation entry point. All other URLs in zalo-oa.md and zalo-bot.md verified against canonical hosts: - bot.zapps.me/docs/ — official Zalo Bot Platform (Zalo Platforms LLC, VNG subsidiary) - bot.zapps.me/docs/error-code/ — official Bot API error reference - developers.zalo.me — official Zalo developer console - oa.zalo.me — official Zalo OA management console
Source paths in goclaw rot quickly across refactors and would silently mislead readers. The pages now lean on: - runtime slog keys (already documented under Troubleshooting) - public API surfaces (Zalo dev console fields, header names) - official Zalo / Bot Platform docs (already linked) If a maintainer needs to find the implementation, they can grep — that is not the docs reader's job.
Contributor
|
Please resolve conflicts and sync with new goclaw code base @vanducng |
Resolve conflicts:
- README.md: combine page counts (providers 25, channels 15)
- llms{,-full}.txt (EN/VI/ZH): regenerate via scripts/generate-llms-txt.sh
Contributor
Author
|
@thieu1995 thanks for the review! Quick status update:
Will ping you again once it's ready for re-review. |
Contributor
|
Please let me know when you've done
Thanks!
Vào Thứ 7, 23 thg 5, 2026 vào lúc 12:49 Duc Nguyen <
***@***.***> đã viết:
… *vanducng* left a comment (nextlevelbuilder/goclaw-docs#63)
<#63 (comment)>
Apologies — wrong handle in previous comment. cc @thieung
<https://github.com/thieung>
—
Reply to this email directly, view it on GitHub
<#63 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ATCCTME2YSTQFF7W6ZFXXD344E3X3AVCNFSM6AAAAACYNGOAI6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DKMRUGMZDCNJZHA>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates the operator-facing Zalo channel guides from
goclaw/docs/(deleted in goclaw c9c7617a) to the public docs site, splitting into two pages aligned with the recentzalo_bot/zalo_oachannel rename.Pairs with goclaw PR: nextlevelbuilder/goclaw#1048 (
feat/zalo-oa-webhook-966-clean). Cross-link blockquote in goclaw'sdocs/05-channels-messaging.md§ 10 already points athttps://docs.goclaw.sh/channel-zalo-{oa,bot}. Land this PR first so those links resolve.What's in here
New / rewritten pages
channels/zalo-oa.md— full rewrite. OAuth v4 setup, polling-default with code-verified knobs (poll_count=10,poll_burndown_max_pages=10), webhook bootstrap flow, signature verification (X-ZEvent-Signature), quoted replies (quote_user_message=truedefault), reaction levels (offconfig default), media caps (image 1 MB / file 5 MB / gif 5 MB), inline Social API error reference.channels/zalo-bot.md— net-new. Single-token setup, polling-default, webhook withX-Bot-Api-Secret-Tokenheader, DM-only restriction, pairing flow with 60s debounce, inline Bot API error reference. Includes a "newer platform / surface still expanding" note since Zalo is actively adding endpoints (sticker + chat-action shipped recently).Decision aid (in both pages)
Locale mirrors
<!-- TODO: translate -->top comments and propercập nhật:footer for VI (audit-script convention).Quadruple-sync nav
README.md— Channels list + Structure tree page count (14 → 15)js/docs-app.js— DOC_MAP entry forchannel-zalo-botindex.html— sidebar<a class="sidebar-link" data-doc="channel-zalo-bot">channels/INDEX.md(+vi/,zh/mirrors) — Quick Start list, Channel Comparison Table (Zalo Bot column added, Zalo OA row updated for OAuth+webhook reality), setup checklistBuild & audit hygiene
mapping.json(audit skill) —internal/channels/zalo/*rule extended to cover both pagesllms.txt— manual TOC entry added;llms-full.txtregenerated for root +vi/+zh/./scripts/audit-docs.shreports both new pages clean (matching goclaw HEADbb68b750at push time)Authoritative references (canonical official URLs)
https://developers.zalo.me/docs/social-api/tham-khao/ma-loi— Social API error codeshttps://bot.zapps.me/docs/— Zalo Bot Platform docs (Zalo Platforms LLC, VNG subsidiary)https://bot.zapps.me/docs/error-code/— Bot API error referenceDefaults verified against goclaw code
transportpolling(default),webhook(opt-in)internal/config/config_channels.go:177reaction_level"off"config defaultinternal/channels/zalo/oa/reactions.go:126quote_user_messagetruedefaultinternal/config/config_channels.go:174poll_count10(Zalo hard cap)internal/channels/zalo/oa/poll.go:174-177poll_burndown_max_pages10Test plan
npm run dev→ load/channel-zalo-oa,/channel-zalo-bot— sidebar shows both, no 404, footer renders as commit-link badgechannels/INDEX.mdrenders the Zalo Bot column without layout breakage/vi/channel-zalo-{oa,bot}and/zh/channel-zalo-{oa,bot}Out of scope / follow-ups
<!-- TODO: translate -->commentszalo-error-codesreference page (decision: codes are inlined per page where operationally relevant)scripts/fetch-zalo-error-codes.cjsleft in goclaw repo (not relocated)