zca-bridge
Sidecar tự host Zalo ↔ Chatwoot bridge cho đội ngũ hỗ trợ Việt Nam. Kết nối Zalo OA và cá nhân qua API chính thức (OA) hoặc thư viện không chính thức (cá nhân). Hỗ trợ chat hai chiều, media, proxy riêng, auto-reconnect với backoff lũy thừa.
Ficha actualizada 23 sept 2026, 15:39 · upstream 23 sept 2026, 15:17 · release v1.0.4
Qué es zca-bridge
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
zca-bridge là một sidecar tự host để đồng bộ hội thoại Zalo hai chiều với Chatwoot. Bridge biến Zalo thành inbox trong Chatwoot cho nhân viên hỗ trợ, cho phép nhận, gửi, ghi chú và theo dõi lịch sử chat ngay trên helpdesk.
Bridge hỗ trợ cả kênh Zalo OA (qua API chính thức) và Zalo cá nhân (qua thư viện zca-js không chính thức). Đối với OA, bridge xử lý OAuth, webhook inbound/outbound, backfill tin nhắn khi khởi động, nén ảnh quá lớn trước khi upload. Với cá nhân, bridge dùng QR code để đăng nhập, có cơ chế auto-reconnect với backoff lũy thừa và cảnh báo khi phiên hết hạn.
Trong Chatwoot, bridge nhận webhook outbound từ Chatwoot và đẩy inbound message vào qua API Zalo. Bridge lưu job trong PostgreSQL, retry lỗi tạm thời và đưa lỗi vĩnh viễn vào dead-letter queue.
- Hỗ trợ khách hàng qua Zalo OA: nhận tin nhắn, gửi file, nén ảnh quá lớn trước khi upload lên Chatwoot, backfill lịch sử chat khi khởi động hệ thống
- Hỗ trợ khách hàng qua Zalo cá nhân: đăng nhập qua QR code, gửi/ghi chú tin nhắn, theo dõi chat trong helpdesk
- Quản lý proxy riêng cho từng tài khoản Zalo cá nhân để tách IP đầu ra, tránh bị block hoặc giới hạn số lượng tin nhắn
- Tự động kết nối lại phiên Zalo khi rớt mạng: sử dụng backoff lũy thừa (5s → 15s → 45s → 2 phút) và cảnh báo qua Telegram/webhook
- Archive media bền vững: lưu file đính kèm vào thư mục local, gửi link `/media/:token` cho chat để tránh giới hạn dung lượng upload Chatwoot
- Tự động tạo inbox mới khi thêm Zalo OA account mới mà không cần admin nhập thủ công
- Hỗ trợ đầy đủ các loại nội dung: text, ảnh, file, ghi âm, video, sticker và fallback cho nội dung chưa nhận diện
- Chống lặp/echo thông qua cơ chế `message_map` để tránh gửi tin đã được gửi trước trong cùng cuộc hội thoại
- Quản lý proxy riêng cho từng tài khoản cá nhân giúp tách IP đầu ra, giảm rủi ro bị block hoặc giới hạn số lượng tin nhắn
- Tự động kết nối lại phiên Zalo khi rớt mạng với backoff lũy thừa và cảnh báo qua Telegram/webhook khi gặp sự cố
- Archive media bền vững với cơ chế link token hóa: file lớn được lưu cục bộ, gửi qua link có token để tránh giới hạn dung lượng upload Chatwoot
- Admin dashboard cung cấp đầy đủ tính năng: quản lý proxy, tạo inbox mới, cấu hình cảnh báo, xem/export log và ẩn cảnh báo đã xử lý
- Tài khoản Zalo cá nhân được kết nối qua thư viện không chính thức `zca-js`, có rủi ro tài khoản bị khóa hoặc cấm vĩnh viễn nếu dùng sai cách
- Kênh Zalo OA sử dụng API chính thức nên ít gặp vấn đề bảo mật hơn, nhưng vẫn cần tuân thủ các quy định của Zalo về quyền riêng tư
- Bridge chỉ hỗ trợ chat hai chiều; không hỗ trợ gửi tin nhắn từ bot đến người nhận (ngoài webhook outbound), và không có tính năng forward tin nhắn
- Không hỗ trợ đa ngôn ngữ cho nội dung chat: mỗi tài khoản chỉ được dùng một ngôn ngữ, cần tạo inbox riêng cho từng ngôn ngữ
- Cảnh báo Telegram/webhook chỉ hoạt động khi bật trong settings admin; nếu tắt thì không nhận cảnh báo sự cố
- Không có tính năng tự động chuyển đổi ngôn ngữ chat giữa các tài khoản Zalo cá nhân (chỉ dùng inbox riêng)
Capturas del proyecto
Imágenes reales detectadas en la documentación del repositorio.
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Chạy bằng Docker: tải `docker-compose.full.yml`, chuẩn bị `.env` với biến `DATABASE_URL`, `CHATWOOT_BASE_URL`, `CREDENTIALS_KEY` và `PUBLIC_BASE_URL`. Bridge chạy ở port 4000. Chạy container đơn với `docker run --env-file .env -p 4000:4000 ghcr.io/diendh/zca-bridge:latest`. Chạy trực tiếp: `npm ci`, `npm run build`, tạo thư mục `dist/store/migrations` và `dist/admin/public`. Chạy `npm start` để khởi động bridge trên port 4000. Migration SQL tự chạy khi khởi động. Bridge lắng nghe trên `$PORT` (mặc định 4000). Lưu ý: không commit `.env`, token thật, app secret hoặc database dump vào repository. Chatwoot phải chạy riêng và trỏ `CHATWOOT_BASE_URL` tới dịch vụ Chatwoot đó.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.