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