Trình kích hoạt tin nhắn Zalo icon

Trình kích hoạt tin nhắn Zalo

Lắng nghe sự kiện tin nhắn trên Zalo (hỗ trợ nhiều người dùng)
Join our community

Overview

This node listens for incoming Zalo messages in real-time and triggers workflows based on those events. It supports monitoring both personal (one-on-one) and group messages, with advanced filtering options such as triggering only when the message contains specific @mentions. This is useful for automating responses, logging conversations, or integrating Zalo messaging into broader automation pipelines.

Practical examples include:

  • Automatically responding to direct messages from users.
  • Triggering workflows only when the bot or specified users are mentioned in group chats.
  • Collecting and processing message data for analytics or CRM systems.
  • Debugging and monitoring all incoming Zalo message events for development purposes.

Properties

Name Meaning
Loại sự kiện Select which types of messages to listen for: "Tin nhắn cá nhân" (personal messages), "Tin nhắn nhóm" (group messages). You can select one or both.
Nghe tin của chính mình Boolean option to enable receiving messages sent by yourself. If enabled, the node will also trigger on messages you send.
Định danh người dùng A unique identifier string for this user instance, used internally to distinguish between multiple users or sessions.
Tùy chọn @mention Collection of options related to @mention filtering:
- Chỉ kích hoạt khi có @mention: Only trigger when a group message contains an @mention to you or specified UIDs.
- Mention tôi: Include current account UID in targets.
- Additional UIDs: Comma-separated list of extra UIDs to trigger on mention.
- Bỏ qua tin của chính mình: Ignore your own messages even if they contain mentions.
- Self UID: Optionally specify your own UID; if empty, it tries to fetch automatically.
Ghi log mọi sự kiện (Debug) Enable detailed logging of all events received from the underlying API listener. Useful for debugging but may produce verbose logs.
Tùy chọn Payload Options controlling what data is included in the output payload:
- Kèm metadata kỹ thuật: Include technical metadata like timestamps, instance keys, credential IDs.
- Kèm thông tin người dùng: Attach user info.
-- Người gửi: Include detailed sender info.
-- Chính tôi: Include info about the current account.

Output

The node outputs an array of JSON objects representing each received message event that matches the configured filters. Each object includes:

  • The original message data from Zalo, including type, content, sender, mentions, etc.
  • Optional technical metadata fields such as:
    • _timestamp: ISO timestamp when the event was processed.
    • _instanceKey: Unique key combining credential ID and user identifier.
    • _credentialId: Identifier of the used API credentials.
    • _userIdentifier: User identifier string.
    • _eventType: Type of the message event (personal or group).
    • _source: Fixed string "zalo_message_trigger" indicating the source node.
  • Optional user information under _userInfo if enabled, containing detailed data about the sender and/or the current account.
  • If the node is configured to listen only for @mentions, matched mentions and target UIDs are added internally for filtering.

The node does not output binary data.

Dependencies

  • Requires valid Zalo API credentials with login cookie, IMEI, and user agent information.
  • Uses an external Zalo API client library (zca-js) to connect and listen for messages.
  • Needs webhook URL configuration in n8n to receive incoming message events.
  • Requires network access to Zalo's API endpoints.
  • No additional environment variables beyond standard n8n credential setup.

Troubleshooting

  • Common issues:

    • Invalid or expired Zalo API credentials will prevent connection and cause errors during instance creation.
    • Missing or incorrect webhook URL configuration can result in no events being received.
    • If @mention filtering is enabled but self UID is not set and cannot be fetched automatically, mentions may not be detected correctly.
    • Enabling debug logging produces verbose output; disable it in production to reduce noise.

  • Error messages:

    • Zalo connection failed for ...: Indicates failure to authenticate or create the Zalo API instance. Check credentials and network connectivity.
    • No API instance found. Please make sure to provide valid credentials.: Credentials are missing or invalid.
    • Failed to trigger webhook for ...: Network or webhook endpoint issues; verify webhook URL and availability.
    • Warnings about failing to fetch user info or self UID usually indicate temporary API issues or insufficient permissions.

  • Resolutions:

    • Verify and refresh Zalo API credentials.
    • Ensure the webhook URL is publicly accessible and correctly configured in n8n.
    • Provide self UID manually if automatic fetching fails.
    • Disable debug logging after troubleshooting.

Links and References

Discussion