Zalo Official Account

Zalo Official Account

This connector uses the Zalo Official Account Open API (https://openapi.zalo.me, v2.0 and v3.0 endpoints) of a Zalo OA: the OA profile and message quota, the people who follow or talk to the OA, their details and labels (tags), the recent chats and the messages of one conversation, consultation (customer care) messages with text or an image, and the OA's published articles.

Setup (about 5 minutes, and again every day: read the token note)

1. At https://developers.zalo.me create an app (or open yours), link it to your Official Account and, under Official Account > OA permissions, request the permission groups this connector uses: OA information management, user information management, user message management, sending messages and notifications via OA, and article management. An OA admin approves them.
2. Open Tools > API Explorer (https://developers.zalo.me/tools/explorer), pick your app, choose the access token type OA Access Token, pick the OA, allow the requested permissions and copy the access token.
3. Paste it into ZALO_OA_ACCESS_TOKEN. It is sent in the access_token header that Zalo requires.
4. Run zalo_oa_get_oa_info to check it.

The token lasts about 25 hours. Zalo issues OA access tokens for 25 hours (expires_in 90000 seconds) and renews them only through its own OAuth v4 flow, which sends the app secret in a secret_key header and replaces the refresh token on every use. AnythingMCP cannot run that renewal for this connector, so the token is pasted. When calls answer error -216 (Access token is invalid) or -220 (access_token is expired or removed), create a new token in API Explorer and save it in the connector settings. If you renew tokens in your own system, write each new access token into ZALO_OA_ACCESS_TOKEN through the AnythingMCP API.

Workflow

• The OA: zalo_oa_get_oa_info (name, id, verification, followers, service package) and zalo_oa_get_quota (consultation and transaction message quota of the OA or app).
• People: zalo_oa_list_users pages through everyone who interacted with the OA (50 per page); zalo_oa_filter_users does the same with filters (label, last interaction period, follower or not). zalo_oa_get_user returns the name, alias, follower status, last interaction date, labels, notes and the information the user shared with the OA. zalo_oa_update_user sets the alias, your own customer id (user_external_id) and shared information.
• Labels (tags): zalo_oa_list_tags, zalo_oa_tag_user (creates the label when it does not exist), zalo_oa_untag_user and zalo_oa_delete_tag (removes a label from the OA, installed switched off).
• Conversations: zalo_oa_list_recent_chats shows the latest messages across all users (10 at most per call), zalo_oa_get_conversation the messages with one user (10 per call, newest first, page with offset).
• Replying: zalo_oa_get_user_quota tells when the user last interacted and what can still be sent to them. zalo_oa_send_text sends a consultation text (set quote_message_id to reply to a specific message), zalo_oa_send_image a consultation message with one image from a public URL or an uploaded attachment_id. Both send a real message to a real person: show the text to the user and wait for a yes before sending.
• Content: zalo_oa_list_articles lists the OA's articles or videos, zalo_oa_get_article returns one with its body.

When a consultation message can be sent: only to a user who interacted with the OA in the last 7 days (sent a message, tapped a button, called...). From 1 January 2026 consultation messages within 48 hours of the user's last interaction are free and unlimited; later ones use the OA package quota or are charged. Error -230 or -232 means the user has not interacted recently enough; -213 that the user does not follow the OA; -227 that the account is locked or inactive.

Reading the answers: every answer has error (0 = success) and message, with the payload in data. User ids, OA ids and message ids are long digit strings; keep them as strings. src in a message is 1 when the user sent it and 0 when the OA did. time and sent_time are Unix milliseconds; user_last_interaction_date is dd/MM/yyyy. Article dates (create_date, update_date) are Unix milliseconds.

Paging: offset is the position of the first item (0 = newest message or first user). Users: count up to 50, offset up to 9951 (the API reaches the first 10,000 users), total gives the number of matches. Messages: count up to 10. Articles: limit items from offset, total in the answer.

Limits: 4,000 requests per minute per app, plus a per-OA limit that depends on the OA package. Error -32 means the limit was reached: wait for the next minute.

Errors arrive with HTTP 200 and a negative error: -216 or -220 an invalid or expired token (paste a new one), -223 the OA has not granted the app this permission, -224 the OA package does not include the feature, -201 an invalid parameter, -211 quota used up, -32 rate limit.

Out of scope: transaction and promotion (broadcast) messages, ZNS template messages, file and sticker messages, GMF group chats, calls, article creation and the OA shop. Webhooks are configured in the Zalo app settings, not here.