Whaticket Open Source: shared WhatsApp ticket queue for support teams

A single WhatsApp number shared across multiple support agents

Small support teams face a specific problem with WhatsApp: the account belongs to one device, so agents queue in a group chat to answer customers or hand off a phone. Whaticket Open Source routes around this by connecting one WhatsApp account to a web-based ticketing interface where multiple agents can work simultaneously. Every incoming message becomes a ticket, each ticket is assigned to one agent, and the conversation thread stays in one place.

In 2020, this repository started as a weekend experiment. It grew into what the README describes as one of the most forked WhatsApp helpdesk projects on GitHub, and eventually into the commercial Whaticket platform, which the README states serves 4,500+ companies across Latin America. Publishing the original codebase under an MIT licence was the choice the project made when the commercial version branched off.

A working deployment needs a Linux server (Ubuntu 20.04+ is the assumed platform), a MySQL or MariaDB database, and either the wwebjs or zapo WhatsApp provider. Three interface languages are available out of the box: English, Portuguese and Spanish.

Backend, frontend and database: Node.js, React and MySQL in three layers

Node.js with TypeScript, Express and Sequelize powers the backend. It stores tickets, contacts, agents and sessions in MySQL 5.7+ or MariaDB 10.6+, communicates with WhatsApp through a pluggable provider layer, and exposes REST and WebSocket endpoints to the frontend.

A React application built with Vite and Material UI serves the frontend. It connects to the backend over those REST and WebSocket channels, providing the agent chat view, the ticket queue, the contact list and a dashboard.

WhatsApp connectivity depends on the provider chosen at deployment time. wwebjs uses whatsapp-web.js, which drives a Puppeteer browser to emulate the WhatsApp Web client. zapo connects over a WebSocket. Both providers require scanning a QR code to link the account. Node.js 14+ works for wwebjs; zapo and the backend CI and Dockerfile build on Node.js 22+.

Repository root holds three compose files: docker-compose.yaml for the main stack, docker-compose.browserless.yaml for the Browserless service, and docker-compose.phpmyadmin.yaml for database access through phpMyAdmin. Running all three in combination covers a full deployment with a database GUI.

Starting the stack: environment variables and three Docker services

docker-compose.yaml defines three services: backend, frontend and mysql. Before starting the stack, copy .env.example and fill in the required variables:

MYSQL_ROOT_PASSWORD=
MYSQL_DATABASE=whaticket
JWT_SECRET=
JWT_REFRESH_SECRET=
BACKEND_URL=https://api.mydomain.com
BACKEND_SERVER_NAME=api.mydomain.com
FRONTEND_URL=https://myapp.mydomain.com
FRONTEND_SERVER_NAME=myapp.mydomain.com

JWT_SECRET and JWT_REFRESH_SECRET protect the authentication tokens. docker-compose.yaml uses fallback defaults of 3123123213123 and 75756756756 for those two variables, which are not suitable for production.

mysql defaults to the mariadb:10.6 image and sets the character set to utf8mb4 with the utf8mb4_bin collation. MYSQL_ENGINE and MYSQL_VERSION override those defaults. Backend service maps BACKEND_PORT (default 8080) to the container's port 3000. Frontend maps FRONTEND_PORT (default 3000) to port 80 and FRONTEND_SSL_PORT (default 3001) to port 443, with SSL certificate files going in ssl/certs/ and ssl/www/ as volume mounts.

CHROME_ARGS in the backend service passes --no-sandbox and --disable-setuid-sandbox to Puppeteer, which are required for Chromium to start inside a container when using the wwebjs provider.

Ticket lifecycle: pending to resolved, with a 2-hour reopen rule

Every incoming message on a connected WhatsApp number creates a ticket. Tickets land in a queue on the Tickets page, where an agent accepts one, answers it and eventually marks it resolved. States are pending, open and resolved.

Follow-up messages from the same contact attach to the first open or pending ticket found, preventing a running conversation from splitting into multiple tickets when a contact replies after an agent's response.

After resolution, a reopen rule applies. When a contact sends a message within 2 hours and has no pending or open ticket, the most recent closed ticket reopens rather than a new one being created. That window prevents trivial follow-ups from fragmenting a single support case. A contact who returns more than 2 hours later gets a fresh ticket, which may or may not match what the agent expects.

One agent handles each ticket. Queues route incoming conversations to departments before an agent picks them up. Quick replies give agents canned answers for recurring questions. Media support covers images, audio, video and documents, and a contact management view allows starting conversations with new contacts without touching the phone.

Both wwebjs and zapo are unofficial WhatsApp clients

A warning in the README's requirements section reads: 'The QR-code providers used here are unofficial WhatsApp cl'. Both whatsapp-web.js and zapo operate without an official API relationship with WhatsApp, emulating the WhatsApp Web client rather than using the approved Cloud API.

WhatsApp can block accounts that use unofficial clients, and there is no workaround within this codebase. Moving to the official API requires switching to the commercial Whaticket product, which the comparison table shows as the only path to the official WhatsApp Cloud API.

Provider architecture differs between the two options. wwebjs drives a Puppeteer Chromium browser as part of the backend process, increasing memory use compared to a typical Node.js service and requiring the --no-sandbox flags in the Docker configuration. zapo uses a WebSocket connection and needs Node.js 22+, while wwebjs works on Node.js 14+. Choosing between them depends on the available Node.js version and memory budget on the server.

Only WhatsApp is supported in the open-source version. Instagram, Facebook, TikTok, Telegram and web chat are listed in the comparison table as features available only in the commercial product.

Open Source versus the commercial Whaticket: the capability gap

A comparison table in the README makes the scope difference explicit. Both versions share the same core: multiple agents on one WhatsApp number, queues, quick replies, media messages, multiple WhatsApp connections, contact management and a basic dashboard.

Absent from the open-source version are: the official WhatsApp Cloud API, Instagram, Facebook, TikTok, Telegram and web chat channels, rule-based and AI chatbots, bulk campaigns, analytics with CSAT and performance reports, integrations with Zapier, Shopify, Slack and Google, and iOS and Android mobile apps. Community support runs through the Discord server at discord.gg/Dp2tTZRYHg and the GitHub issue tracker; the commercial product offers 24/7 support over WhatsApp.

Commercial plans start at US$49/month for 3 users, which the README notes works out to about US$16 per user per month. For teams that need only WhatsApp and are willing to manage the server, the open-source version covers those features. For teams that need the official API, additional channels or mobile apps, this codebase does not reach there.

MIT licence, no tagged releases, and three stateful directories to protect

Licence is MIT, per the repository metadata and the LICENSE file at the root. No GitHub releases exist in this repository. Comparing two deployments requires reading the git log directly rather than release notes, and no version number appears in the README or the materials.

Ubuntu 20.04+ is the production platform the README assumes. Repository's last push was on 2026-09-25.

docker-compose.yaml stores WhatsApp session data in ./backend/.wwebjs_auth/ and ./backend/.zapo_auth/ as volume mounts. Losing those directories requires re-scanning the QR code to re-link the account. Media files from conversations go in ./backend/public/. Those three paths hold the stateful parts of a deployment and should be included in any backup or migration plan.

README files are available in English (README.md), Portuguese (README.pt-br.md) and Spanish (README.es.md). Reading through .env.example before deployment is the fastest way to understand what the stack exposes, since it groups variables by section and documents the defaults.

Editorial conclusion

Whaticket Open Source suits small support teams that need shared WhatsApp access without a recurring software cost and are willing to manage a Linux server and a database. Using unofficial WhatsApp providers is the main risk: WhatsApp can block accounts that use them, and no upgrade path to the official Cloud API exists without switching to the commercial product. Before deploying, replace JWT_SECRET and JWT_REFRESH_SECRET with values stronger than the docker-compose defaults of 3123123213123 and 75756756756, confirm your server meets the Ubuntu 20.04+ requirement, and decide whether the 2-hour reopen window matches your support workflow.

Frequently asked questions

Official sources

1. canove/whaticket-community on GitHub
2. Issues
3. License: MIT
4. README