zca-zalo

n8n community node for Zalo Personal integration via zca-js

Package Information

Released: 7 mo ago
Downloads: 20 weekly / 72 monthly
Latest Version: 0.3.3
Author: chuanman2707

Available Nodes

Zalo Trigger icon
Zalo Trigger
Triggers workflow when a Zalo message is received or a friend request arrives
Zalo Send icon
Zalo Send
Send messages, images, files, links, and reactions via Zalo
Zalo Action icon
Zalo Action
Manage Zalo contacts, friends, and account actions
Zalo Login QR icon
Zalo Login QR
Login to Zalo Personal account via QR code. Run once — credentials are saved automatically for persistent use.

Documentation

n8n-nodes-zca-zalo

Custom n8n community nodes for Zalo Personal integration using zca-js.

⚠️ Note: This package uses the unofficial Zalo Personal API. Use at your own risk.

📦 Installation

  1. Open your n8n instance
  2. Go to Settings → Community Nodes
  3. Click Install a community node
  4. Enter: n8n-nodes-zca-zalo
  5. Click Install

🔑 Credentials Setup

Before using any Zalo node, create credentials:

  1. Go to Settings → Credentials → Add Credential
  2. Search for Zalo API
  3. Fill in 3 fields:
Field How to get it
Cookie Export cookies from chat.zalo.me as JSON (use a browser extension like EditThisCookie)
IMEI In Zalo Web console: localStorage.getItem('z_uuid')
User Agent In Zalo Web console: navigator.userAgent

🛠️ Nodes

This package provides 3 nodes:

1. Zalo Trigger

Listens for incoming Zalo events and triggers your workflow.

Event Types:

  • 📩 Direct Message — Triggers when someone DMs you
  • 👥 Group Message — Triggers when a message is sent in a group
  • 🤝 Friend Request — Triggers when someone sends a friend request

Options:

Option Default Description
Self Listen false Also trigger on messages sent by your own account
Auto Accept Friend true Automatically accept incoming friend requests
Welcome Message (empty) Message to send after accepting a friend (leave empty to skip)
Poll Interval 30s How often to check for pending friend requests

Output Data:

{
  "eventType": "message",
  "threadId": "123456789",
  "threadType": "User",
  "message": "Xin chào!",
  "senderId": "987654321",
  "isSelf": false,
  "timestamp": 1710700000000,
  "rawData": { ... }
}

For friend requests:

{
  "eventType": "friend_request",
  "userId": "123456789",
  "displayName": "Nguyen Van A",
  "autoAccepted": true,
  "timestamp": 1710700000000
}

2. Zalo Send

Send messages, files, images, and reactions to Zalo users or groups.

Message → Send Text

Send a text message to a user or group.

Parameter Required Description
Thread ID ✅ Recipient user or group ID (use {{$json.threadId}} from trigger)
Thread Type ✅ User (DM) or Group
Message ✅ Text content to send

Message → Send Attachment

Send a file or image (PDF, JPG, PNG, etc.).

Parameter Required Description
Thread ID ✅ Recipient user or group ID
Thread Type ✅ User (DM) or Group
File Path ✅ Absolute path to the file on the server
Message ❌ Optional caption

Message → Send Link

Send a URL with auto-preview.

Parameter Required Description
Thread ID ✅ Recipient user or group ID
Thread Type ✅ User (DM) or Group
URL ✅ The link to send
Caption ❌ Optional text with the link

Message → Delete

Delete a previously sent message.

Parameter Required Description
Thread ID ✅ Thread where the message is
Message ID ✅ ID of the message to delete

Reaction → Add Reaction

React to a message with an emoji.

Parameter Required Description
Thread ID ✅ Thread where the message is
Message ID ✅ ID of the message to react to
Reaction ✅ 👍 👎 ❤️ 😆 😮 😢 😠 ✅

3. Zalo Action

Manage contacts and friend requests.

Friend → Accept Request

Accept a pending friend request by user ID.

Friend → Get Pending Requests

Get all pending friend requests (returns array).

Friend → Get All Friends

Get your full friends list.

Contact → Find User

Find a Zalo user by phone number or user ID.

Contact → Change Alias

Set a custom display name for a friend (e.g., "Room 101 - Nguyen Van A").

💡 Example Workflows

Auto-Reply Chatbot

ZaloTrigger (DM) → IF (not self) → ZaloSend (Send Text: "Thanks for your message!")

Forward to AI

ZaloTrigger (DM) → AI Agent (LLM) → ZaloSend (reply with AI response)

Auto-Accept & Welcome

ZaloTrigger (Friend Request, autoAccept=true, welcomeMessage="Welcome!")
→ Code (log new friend)

Send File on Keyword

ZaloTrigger (DM) → IF (message = "invoice")
→ ZaloSend (Send Attachment: /path/to/invoice.pdf)

🔧 Technical Details

  • Library: zca-js v2.x (unofficial Zalo Personal API)
  • Authentication: Cookie-based (Zalo Web session)
  • Session: Singleton pattern — one login shared across all nodes in a workflow
  • Node types: Trigger (ITriggerFunctions), Send/Action (IExecuteFunctions)

⚠️ Important Notes

  1. Unofficial API — This uses the Zalo Personal account API, not the official Zalo OA Bot API. Your account may be restricted if Zalo detects unusual activity.
  2. Cookie expiration — Cookies may expire. Re-export from Zalo Web if authentication fails.
  3. One account per workflow — The session manager shares a single API instance per credential set.
  4. File access in Docker — If running n8n in Docker, make sure file paths for attachments are accessible inside the container.

📄 License

MIT

👤 Author

chuanman2707

Discussion