diendh/zca-bridge

zca-bridge connects two separate systems used in Vietnamese customer support: Zalo, a messaging app extremely popular in Vietnam, and Chatwoot, an open-source help desk platform. Without a bridge like this, a support team using Chatwoot would need to separately check the Zalo app for messages, keeping two interfaces open and breaking their workflow. This project adds Zalo as an inbox inside Chatwoot so agents can read and reply to Zalo messages from the same interface they use for other channels. The bridge runs on your own server rather than passing through a third-party service, which matters for businesses with data privacy requirements. It supports two types of Zalo connections. The first is Zalo Official Accounts, which uses Zalo's official API and is the safer option for business use. The second is personal Zalo accounts, which relies on an unofficial library and carries a real risk of the account being restricted or permanently banned. The README warns clearly that the personal account channel should only be used with disposable or test accounts, not primary business accounts. Messages flow in both directions: incoming Zalo messages become conversations in Chatwoot, and replies from Chatwoot agents are sent back through Zalo. The bridge supports text, images, files, voice recordings, video, stickers, and location messages. A durable queue backed by PostgreSQL handles message delivery, with automatic retry on failure and a dead-letter store for messages that cannot be delivered. A deduplication mechanism prevents the same message from appearing twice. The project is written in TypeScript using the Fastify web framework and requires a PostgreSQL database separate from Chatwoot's own database. Docker Compose files are included for straightforward self-hosted deployment. The README is primarily written in Vietnamese but includes a link to an English version, and a project wiki covers installation, configuration, and troubleshooting in both languages. The project is licensed under Apache 2.0 and is independent of Zalo, Chatwoot, and the unofficial library it uses.