hermes-zalo-plugin: messaging bridge for Hermes Agent

Node.js bridge that connects a personal Zalo account to the Hermes Agent gateway

What hermes-zalo-plugin does

The bridge sits between Zalo and Hermes. Zalo events arrive over a WebSocket listener in zca-js, and replies go out over HTTPS. On the Hermes side, inbound messages reach the Hermes adapter for the platform named zalo through Server-Sent Events at GET /events, with heartbeats and Last-Event-ID replay, while outbound actions use REST calls such as /send, /send-attachment, /send-sticker, /send-voice and /typing.

Setup logs in once with a QR code scanned from the Zalo mobile app, saves credentials under ~/.hermes-zalo, and installs a background service that starts on login and restarts after a crash: launchd on macOS, a systemd user unit on Linux or a Scheduled Task on Windows. The bridge listens on 127.0.0.1 port 8787 by default and can require a shared token on every route. The author chose zca-js for its wider API coverage, which the bridge exposes as a 145-method API.

Key features

QR-code login with credentials saved under ~/.hermes-zalo
Background service on macOS, Linux and Windows that restarts on crash
Inbound events over Server-Sent Events and outbound REST endpoints for text, attachments, stickers, voice and typing
Optional shared token required on every route
CLI commands setup, login, start, stop, status and uninstall
Installer flags such as --no-service, --relogin and --hermes-home

When to use it

Talking to a Hermes agent from Zalo on a phone
Running a Hermes gateway for a Vietnamese-language chat workflow
Sending files, stickers or voice replies from Hermes through Zalo

Who it is for: Hermes Agent users in Vietnam or anyone who wants Zalo as a chat channel for their agent.

How it fits with Hermes Agent

Built for Hermes Agent as a gateway add-on. It is registered through hermes gateway setup by choosing Zalo, and the Hermes side uses a Python adapter.

How to install hermes-zalo-plugin

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

npm install -g hermes-zalo-plugin
hermes-zalo-plugin setup
hermes gateway setup
hermes gateway

Requirements: Node.js 18 or newer with npm; a Zalo account (a secondary account is recommended); Hermes Agent with the hermes CLI on PATH; Python aiohttp

Note: Relies on the unofficial zca-js library, and Zalo may rate-limit or lock accounts that automate.

FAQ

What is hermes-zalo-plugin?

hermes-zalo-plugin is a Node.js bridge that connects a personal Zalo account to the Hermes Agent gateway through the unofficial zca-js library. It lets you message your Hermes agent from Zalo.

How do I install hermes-zalo-plugin?

Run npm install -g hermes-zalo-plugin, then hermes-zalo-plugin setup to scan the QR code and install the background service. Finish with hermes gateway setup, choosing Zalo, and start relaying with hermes gateway.

Is it safe to use my main Zalo account with hermes-zalo-plugin?

The README recommends a secondary account. zca-js is an unofficial, reverse-engineered client, and Zalo may rate-limit or lock accounts that automate, a risk the user accepts.