zalo-platform

n8n community node for Zalo Bot Platform - send messages, photos, stickers and manage webhooks

Package Information

Released: 1 mo ago
Downloads: 84 weekly / 432 monthly
Latest Version: 2.0.1
Author: hecigo

Available Nodes

Zalo Bot icon
Zalo Bot
Send messages, photos, stickers, chat actions and manage webhooks. Compatible with official Zalo Bot Platform.
Zalo Bot Trigger icon
Zalo Bot Trigger
Receive messages and events via webhook with auto-registration. Compatible with official Zalo Bot Platform.

Documentation

n8n-nodes-zalo-platform

npm version npm downloads license

Community node for Zalo Bot Platform on n8n. Automate Zalo Bot interactions: receive messages via webhook, send replies, photos, stickers, and chat actions.

Verified by n8n, so it installs from the nodes panel on n8n Cloud as well as self-hosted. Unverified community nodes cannot run on n8n Cloud.

Built by hecigo — Middleware & Integration Lab.

Guides: Running a Zalo bot on n8n: what breaks in production (English) · Detailed Guide (Vietnamese)

Nodes

Zalo Bot Trigger

Receives incoming messages via webhook. Webhook URL and secret token are managed automatically.

When a workflow is activated, the node:

  1. Registers a webhook URL with Zalo (POST /setWebhook)
  2. Derives a secret token: SHA256(botToken).hex().substring(0, 32)
  3. Validates incoming requests via X-Bot-Api-Secret-Token header
  4. Cleans up on deactivation (POST /deleteWebhook)

Event filtering:

Option Value Passes Through
Any Message anyMessage All message types
Text Message message.text.received Text only
Image Message message.image.received Images only
Sticker Message message.sticker.received Stickers only

Sample output:

{
  "event_name": "message.text.received",
  "message": {
    "date": 1775362520302,
    "chat": { "chat_type": "PRIVATE", "id": "818e7bf147beaee0f7af" },
    "message_id": "261de7b845d153890ac6",
    "from": { "id": "818e7bf147beaee0f7af", "is_bot": false, "display_name": "Nguyen Van A" },
    "text": "Xin chao"
  }
}

Useful expressions:

Expression Returns
{{ $json.message.chat.id }} Chat ID (use to reply)
{{ $json.message.text }} Message content
{{ $json.message.from.display_name }} Sender name
{{ $json.event_name }} Event type

Zalo Bot (Action)

9 operations, all using POST requests to https://bot-api.zaloplatforms.com/bot{TOKEN}/{method}.

Send Message

Parameter Type Required Description
chatId String Yes User ID or Group ID
text String Yes Message content, max 2000 characters

Request body: { "chat_id": "...", "text": "..." }

Send Photo

Parameter Type Required Description
chatId String Yes User ID or Group ID
photo String Yes HTTPS image URL
caption String No Caption, max 2000 characters

Send Chat Action

Parameter Type Required Description
chatId String Yes User ID or Group ID
action Options Yes typing (bot is typing) or upload_photo (bot is uploading a photo)

Request body: { "chat_id": "...", "action": "typing" }

Useful before sending a message or photo to show the bot is "thinking".

Send Sticker

Parameter Type Required Description
chatId String Yes User ID or Group ID
stickerId String Yes Sticker ID (e.g., bfe458bf64fa8da4d4eb)

Note: UI shows stickerId but the API body uses key "sticker". The node handles this mapping.

Get Updates (Long Polling)

Parameter Type Default Description
timeout Number 30 Polling timeout in seconds. 0 for immediate.

Important: getUpdates and webhooks are mutually exclusive. Call Delete Webhook before using Get Updates. The timeout is sent as a string in the request body.

Get Bot Info / Set Webhook / Delete Webhook / Get Webhook Info

Operation Endpoint Parameters
Get Bot Info POST /getMe None
Set Webhook POST /setWebhook webhookUrl (HTTPS), secretToken (8-256 chars)
Delete Webhook POST /deleteWebhook None
Get Webhook Info POST /getWebhookInfo None

If you use the Trigger node, you do not need Set/Delete Webhook manually.

Installation

n8n Cloud

Search for Zalo Bot in the nodes panel on the canvas. Verified nodes are
installed on first use, with no Settings step and no risk prompt.

Self-hosted n8n

  1. Go to Settings > Community Nodes
  2. Select Install
  3. Enter n8n-nodes-zalo-platform
  4. Agree to the risks and click Install

Manual (Self-Hosted)

cd ~/.n8n
npm install n8n-nodes-zalo-platform

Restart n8n after installation.

Queue/Worker mode: Install the node on both the main instance and all workers. Custom nodes must exist in ~/.n8n/ on every container.

Creating Your Zalo Bot

  1. Open Zalo on your phone
  2. Search for OA "Zalo Bot Manager"
  3. Tap "Create Bot"
  4. Enter a bot name (must start with "Bot", e.g., Bot MyShop)
  5. Zalo sends your Bot Token via message: {bot_id}:{secret_key}

Credentials

Field Description
Bot Token Format: {bot_id}:{secret_key}. Tested via POST /getMe.

Cloudflare Configuration

Zalo sends webhooks with User-Agent: Java/1.8.0_192. Cloudflare blocks this by default. Create 2 rules:

Rule 1 - WAF Custom Rule: Skip all managed rules for URI path contains /webhook

Rule 2 - Configuration Rule: Disable Browser Integrity Check for URI path contains /webhook

Use /webhook (no trailing slash) to cover both /webhook/... and /webhook-test/... URLs.

Workflow Examples

Auto-reply:

Zalo Bot Trigger (Any Message)
  -> IF (event_name == "message.text.received")
    -> Zalo Bot: Send Message (chatId, reply text)

Lead capture:

Zalo Bot Trigger (Text Message)
  -> Google Sheets: Append Row (name, message, timestamp)
  -> Slack: Send notification

Polling (no HTTPS):

Schedule Trigger (every 30s)
  -> Zalo Bot: Delete Webhook (run once)
  -> Zalo Bot: Get Updates (timeout: 25)
  -> IF (has data) -> Process...

Troubleshooting

Problem Cause Fix
Trigger receives nothing Cloudflare blocks Java UA Create both Cloudflare rules
401 on credential test Token expired/wrong Create new bot
Test mode spins forever Workflow still active Deactivate before testing
getUpdates empty Webhook still registered Call Delete Webhook first
Worker missing node Only on main instance Install on all containers

Compatibility

  • n8n: >= 1.83. The nodes import NodeConnectionTypes from n8n-workflow, which
    first shipped in n8n-workflow@1.83.0. On older n8n the node package fails to load.
    Stay on 1.0.13 if you cannot upgrade n8n.
  • Zalo Bot Platform API

About

hecigo is a middleware and integration lab. We build and run the layer that makes disconnected business systems talk to each other — with the right data, and nothing lost. Need custom n8n nodes or middleware consulting? Get in touch.

Other n8n nodes by hecigo: n8n-nodes-firecrawl-v2 — scrape, crawl, map, search and AI extraction against Firecrawl v2. Self-hosted n8n only.

Consulting partner: THE NEXOVA — Bridge Strategy to Execution.

License

MIT

Discussion