Zalo Send Message icon

Zalo Send Message

Gửi tin nhắn qua API Zalo với session management cải tiến
Join our community

Overview

This node sends messages through the Zalo API with improved session management. It supports sending to individual users or groups, attaching images/files via URLs, quoting previous messages (automatically or manually), and mentioning users within the message. The node manages sessions efficiently by caching them and optionally forcing new sessions. It also supports retrying failed send attempts and provides debug logging for detailed insight into the sending process.

Common scenarios where this node is beneficial include:

  • Automating replies or notifications in Zalo group chats.
  • Sending personalized messages to users while handling Zalo's restrictions on personal messaging.
  • Integrating Zalo messaging into workflows that require attachments, mentions, or quoting previous conversations.
  • Managing message urgency levels for prioritization.

Practical example:

  • A customer support workflow that listens to incoming Zalo messages and automatically sends replies with quoted context and mentions relevant support agents.
  • Broadcasting announcements to a group chat with attached images and marking messages as urgent.

Properties

Name Meaning
Notice ⚠️ Warning: Sending personal messages may be restricted by Zalo policies. It is recommended to use Auto Reply in ZaloListenMessages instead.
Thread ID The ID of the thread (chat) to which the message will be sent. This ID is typically obtained from the output of ZaloListenMessages.
Type The type of message recipient:
• User (Personal) — may be restricted by Zalo.
• Group — less restricted.
Message The content of the message to send.
Advanced Options Collection of optional settings:
• Debug Mode: Enable detailed logging of the sending process.
• Force New Session: Create a new session instead of using cached one.
• Retry Attempts: Number of retries on failure (0-5).
Urgency The urgency level of the message:
• Default
• Important
• Urgent
Quote Mode How to quote a message:
• No Quote
• Auto Quote (reply current message from ZaloListenMessages)
• Manual Quote (enter quote details manually)
Quote Message When using Manual Quote mode, specify:
• Message ID to quote
• Sender ID of quoted message
• Content of quoted message
Mentions Specify user mentions in the message:
• User ID to mention
• Position of mention in message text
• Length of mention
Attachments One or more image/file attachments specified by public URLs.

Output

The node outputs an array of JSON objects, each representing the result of sending a message for each input item. Each output object contains:

  • success: Boolean indicating if the message was sent successfully.
  • response: The raw response from the Zalo API after sending the message.
  • threadId: The thread ID used for sending.
  • threadType: Either "user" or "group".
  • messageContent: The full message content object sent, including quotes, mentions, attachments, and urgency.
  • sessionSource: Indicates whether the session was newly created, cached, or forced new.
  • sendDuration: Time taken to send the message (e.g., "123ms").
  • attempt: The attempt number on which the message was successfully sent.
  • timestamp: ISO timestamp of when the message was sent.

If sending fails, the output includes:

  • success: false
  • error: Error message describing the failure.
  • Additional troubleshooting info if the failure relates to personal message restrictions.

If binary data (attachments) are involved, the node downloads files temporarily to send them but does not output binary data itself.

Dependencies

  • Requires valid Zalo API credentials configured in n8n (an API key credential with cookie, IMEI, and user agent).
  • Uses the zca-js library for interacting with Zalo API.
  • Utilizes helper functions to download and remove attachment files.
  • Manages session caching internally with expiration and cooldown timers.

Troubleshooting

Common Issues

  • No credentials found: The node requires properly configured Zalo API credentials. Without these, it cannot authenticate.
  • Personal message restrictions: Sending direct messages to users may fail due to Zalo policy restrictions on unsolicited personal messages.
  • Invalid Thread ID: Using an incorrect or expired thread ID will cause sending failures.
  • Attachment download failures: If attachment URLs are invalid or inaccessible, sending may fail or attachments won't be included.
  • Session expiration: Sessions are cached but expire after 10 minutes; forcing new sessions or waiting may resolve some issues.

Common Error Messages and Resolutions

  • "No Zalo credentials found": Configure Zalo API credentials before running the node.
  • "Credential parsing error": Credentials might be outdated or corrupted; regenerate credentials using the recommended login method.
  • "Cannot send personal message" or errors mentioning receiving messages: Indicates Zalo restrictions on personal messages. Recommended actions:
    • Use Auto Reply in ZaloListenMessages instead of direct personal messages.
    • Send messages to groups rather than individuals.
    • Verify the Thread ID is correct and corresponds to a group or allowed user.
  • "Parameter is invalid": May occur due to incorrect message payload structure; the node tries alternative payload formats automatically.
  • Attachment-related errors: Check that attachment URLs are publicly accessible and valid.

Links and References

Discussion