Whaticket Open Source

El sistema de tickets de WhatsApp, de código abierto, que dio origen a Whaticket.
Varios agentes en un mismo número. Cada conversación se convierte en un ticket.

English · Português · Español

Qué es esto · Open Source vs Whaticket · Capturas de pantalla · Inicio rápido · Configuración · Estado del proyecto

Qué es esto

En 2020 este repositorio era un experimento de fin de semana: convertir mensajes de WhatsApp en tickets de soporte para que todo un equipo pudiera responder desde un único número. Se convirtió en uno de los proyectos de helpdesk para WhatsApp más forkeados de GitHub, y dio origen a Whaticket, la plataforma comercial que hoy atiende a más de 4.500 empresas en América Latina.

Este repositorio es Whaticket Open Source: el código original, con licencia MIT. Puedes alojarlo por tu cuenta, forkearlo y construir encima. El código del que nació la empresa sigue siendo público.

Backend: Node.js + TypeScript + Express + Sequelize. Se comunica con WhatsApp a través de una capa de proveedores intercambiable (whatsapp-web.js o zapo-js) y guarda todo en MySQL/MariaDB.

Frontend: una aplicación de chat en React + Material UI, empaquetada con Vite. Habla con el backend mediante REST y WebSockets, en español, portugués e inglés.

[!NOTE] ¿Prefieres no administrar servidores? Whaticket es la plataforma gestionada creada por el mismo equipo. Trabaja con la API oficial de WhatsApp y reúne Instagram, Facebook, TikTok, Telegram y chat web en una sola bandeja de entrada, con chatbots con IA, campañas masivas y soporte 24/7. 14 días gratis, sin tarjeta de crédito.

Open Source vs Whaticket

Ambos están hechos por el mismo equipo. La diferencia está en cuánta infraestructura quieres administrar.

El plan comercial empieza en 3 usuarios, lo que sale alrededor de US$ 16 por usuario al mes.

Capturas de pantalla

Conversación de un ticket	Vista del agente
Múltiples conexiones de WhatsApp	Gestión de contactos

Funcionalidades

• 💬 Bandeja de entrada compartida: varios agentes respondiendo desde el mismo número
• 📱 Múltiples conexiones: conecta más de una cuenta de WhatsApp y recíbelo todo en un solo lugar
• 🎫 Ciclo de vida del ticket: pendiente → abierto → resuelto, con asignación por agente
• 🏷️ Colas: dirige las conversaciones entrantes al departamento correcto
• ⚡ Respuestas rápidas: mensajes predefinidos para las preguntas de todos los días
• 🖼️ Multimedia: envía y recibe imágenes, audios, videos y documentos
• 👥 Contactos: inicia conversaciones con contactos nuevos sin tocar el teléfono
• 📊 Panel: visión general de tickets y actividad de los agentes
• 🔌 Proveedor de WhatsApp intercambiable: whatsapp-web.js (Puppeteer) o zapo (WebSocket)
• 🌍 i18n: español, portugués e inglés incluidos

Cómo funcionan los tickets

Cada mensaje nuevo en un número de WhatsApp conectado crea un Ticket. Los tickets llegan a una cola en la página Tickets, donde un agente acepta el ticket, lo responde y finalmente lo resuelve.

Los mensajes posteriores del mismo contacto se adjuntan al primer ticket abierto/pendiente que se encuentre. Si el contacto vuelve a escribir en menos de 2 horas y no tiene ningún ticket pendiente ni abierto, se reabre el ticket cerrado más reciente en lugar de crear uno nuevo.

Requisitos

• Node.js 14+ para el proveedor wwebjs, Node.js 22+ para el proveedor zapo (la CI y el Dockerfile del backend compilan en Node 22)
• MySQL 5.7+ o MariaDB 10.6+
• Docker (opcional, pero es la forma más rápida de levantar la base de datos)
• Un servidor Linux si vas a producción. Estas instrucciones asumen Ubuntu 20.04+.

[!WARNING] Los proveedores por código QR que se usan aquí son clientes no oficiales de WhatsApp. WhatsApp no permite bots ni clientes no oficiales en su plataforma, y los números conectados así pueden ser bloqueados. La alternativa soportada es la API oficial de WhatsApp, que Whaticket ofrece.

Inicio rápido con Docker

git clone https://github.com/canove/whaticket.git
cd whaticket
cp .env.example .env

Edita el .env. Como mínimo, define MYSQL_ROOT_PASSWORD, JWT_SECRET y JWT_REFRESH_SECRET:

# MYSQL
MYSQL_ENGINE=mariadb
MYSQL_VERSION=10.6
MYSQL_ROOT_PASSWORD=cambia-esto
MYSQL_DATABASE=whaticket
MYSQL_PORT=3306
TZ=America/Fortaleza

# BACKEND
BACKEND_PORT=8080
BACKEND_SERVER_NAME=api.midominio.com
BACKEND_URL=https://api.midominio.com
PROXY_PORT=443
JWT_SECRET=cambia-esto
JWT_REFRESH_SECRET=cambia-esto-tambien

# FRONTEND
FRONTEND_PORT=80
FRONTEND_SSL_PORT=443
FRONTEND_SERVER_NAME=app.midominio.com
FRONTEND_URL=https://app.midominio.com

Levanta todo:

docker-compose up -d --build

Solo en la primera ejecución, carga los datos iniciales:

docker-compose exec backend npx sequelize db:seed:all

Abre el frontend, inicia sesión con la cuenta creada por el seed, ve a Conexiones, crea tu primera conexión de WhatsApp y escanea el código QR. A partir de ahí, cada mensaje que reciba ese número aparece en la lista de tickets.

Credenciales por defecto: [email protected] / admin. Cámbialas de inmediato.

docker-compose -f docker-compose.phpmyadmin.yaml up -d

docker-compose -f docker-compose.browserless.yaml up -d

.
├── certs
│   ├── backend
│   │   ├── fullchain.pem
│   │   └── privkey.pem
│   └── frontend
│       ├── fullchain.pem
│       └── privkey.pem
└── www

certbot certonly --cert-name backend  --webroot --webroot-path ./ssl/www/ -d api.midominio.com
certbot certonly --cert-name frontend --webroot --webroot-path ./ssl/www/ -d app.midominio.com

Ejecutar en local para desarrollo

docker run --name whaticketdb \
  -e MYSQL_ROOT_PASSWORD=strongpassword \
  -e MYSQL_DATABASE=whaticket \
  -e MYSQL_USER=whaticket \
  -e MYSQL_PASSWORD=whaticket \
  --restart always -p 3306:3306 -d mariadb:10.6 \
  --character-set-server=utf8mb4 --collation-server=utf8mb4_bin

sudo apt-get install -y libxshmfence-dev libgbm-dev wget unzip fontconfig locales gconf-service \
  libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 \
  libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 \
  libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 \
  libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates \
  fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils

cd backend
cp .env.example .env   # luego complétalo, ver Configuración más abajo
npm install
npm run build
npx sequelize db:migrate
npx sequelize db:seed:all
npm run dev            # o: npm start

cd frontend
cp .env.example .env
npm install
npm run dev

VITE_BACKEND_URL = http://localhost:8080/

Despliegue en producción en un VPS

adduser deploy
usermod -aG sudo deploy
su deploy

sudo apt update && sudo apt upgrade -y

curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
sudo apt update && sudo apt install -y docker-ce
sudo usermod -aG docker ${USER}
su - ${USER}

docker run --name whaticketdb \
  -e MYSQL_ROOT_PASSWORD=strongpassword -e MYSQL_DATABASE=whaticket \
  -e MYSQL_USER=whaticket -e MYSQL_PASSWORD=whaticket \
  --restart always -p 3306:3306 -d mariadb:10.6 \
  --character-set-server=utf8mb4 --collation-server=utf8mb4_bin

cd ~ && git clone https://github.com/canove/whaticket.git whaticket
cp whaticket/backend/.env.example whaticket/backend/.env
nano whaticket/backend/.env    # usa URLs https:// y PROXY_PORT=443

cd whaticket/backend
npm install
npm run build
npx sequelize db:migrate
npx sequelize db:seed:all

sudo npm install -g pm2
pm2 start dist/server.js --name whaticket-backend
pm2 startup ubuntu -u $USER     # ejecuta el comando que imprima

cd ../frontend
npm install
echo "VITE_BACKEND_URL = https://api.midominio.com/" > .env
npm run build
pm2 start server.js --name whaticket-frontend
pm2 save

sudo apt install -y nginx
sudo rm /etc/nginx/sites-enabled/default
sudo nano /etc/nginx/sites-available/whaticket-frontend

server {
  server_name app.midominio.com;

  location / {
    proxy_pass http://127.0.0.1:3333;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_cache_bypass $http_upgrade;
  }
}

sudo cp /etc/nginx/sites-available/whaticket-frontend /etc/nginx/sites-available/whaticket-backend
sudo nano /etc/nginx/sites-available/whaticket-backend
sudo ln -s /etc/nginx/sites-available/whaticket-frontend /etc/nginx/sites-enabled
sudo ln -s /etc/nginx/sites-available/whaticket-backend  /etc/nginx/sites-enabled

client_max_body_size 20M;

sudo nginx -t && sudo service nginx restart

sudo snap install --classic certbot
sudo certbot --nginx

Configuración

Backend (backend/.env)

Frontend (frontend/.env)

Elegir un proveedor de WhatsApp

Cambia entre ellos con WHATSAPP_PROVIDER en backend/.env.

El proveedor zapo envía medios sin ninguna dependencia extra, pero las miniaturas, las dimensiones y el waveform de las notas de voz vienen del paquete opcional @zapo-js/media-utils (que necesita ffmpeg/ffprobe y sharp). Al instalarlo, el proveedor lo usa en el siguiente reinicio; sin él los medios se envían igual, solo sin vista previa.

Actualizar una instalación existente

Compara siempre el .env.example con tu .env antes de actualizar. Las variables nuevas aparecen ahí primero.

#!/bin/bash
echo "Actualizando Whaticket, espera por favor."

cd ~/whaticket
git pull

cd backend
npm install
rm -rf dist
npm run build
npx sequelize db:migrate
npx sequelize db:seed

cd ../frontend
npm install
rm -rf build
npm run build

pm2 restart all
echo "Actualización finalizada. ¡Disfrútalo!"

Si vienes del proveedor whaileys

El proveedor whaileys fue reemplazado por zapo. Las conexiones emparejadas con whaileys siguen funcionando solas, sin escanear un código QR nuevo:

1. Actualiza el servidor a Node.js 22+ (requisito de better-sqlite3).
2. Si quieres, define WHATSAPP_PROVIDER=zapo en backend/.env. El valor antiguo whaileys sigue funcionando y apunta al mismo proveedor.
3. Ejecuta el script de actualización de arriba. Cuando el backend se reinicia, la sesión de cada conexión se copia de la base de datos a .zapo_auth/state.sqlite y la conexión vuelve sin un código QR nuevo.

La copia lee la columna session de Whatsapps y la tabla WppKeys, así que conserva WppKeys hasta que todas las conexiones vuelvan. Redis ya no se lee y puede apagarse. Una conexión cuya sesión no se pueda copiar muestra un código QR nuevo, como en un emparejamiento desde cero.

Estado del proyecto

En modo mantenimiento, con el desarrollo activo de vuelta.

Durante los últimos años este repositorio recibió solo parches de seguridad y actualizaciones de dependencias, mientras el esfuerzo del equipo se dirigía a la plataforma comercial. Eso está cambiando: planeamos retomar el trabajo regular de funcionalidades aquí. Los commits recientes son los primeros pasos: el frontend migró a Vite, y la integración con WhatsApp pasó a una capa intercambiable de proveedores, con el nuevo driver zapo-js.

Qué significa esto para ti hoy:

• Los issues y pull requests se leen. Las revisiones pueden tardar.
• El código es estable y está ampliamente desplegado, pero espera asperezas y dependencias antiguas.
• Los cambios que rompan compatibilidad se señalarán en las notas de versión.

Si dependes de este proyecto, cuéntanos en Discord qué es lo que más falta hace. Eso es lo que define las prioridades.

Contribuir

Los pull requests son bienvenidos: correcciones de bugs, actualizaciones de dependencias, documentación y traducciones. Para cualquier cosa grande, abre un issue antes para acordar el enfoque.

• 💬 Discord: preguntas y discusión
• 🐛 Issues: bugs y sugerencias

Proyectos relacionados

• zapo-js: la librería WebSocket de WhatsApp que usa el proveedor zapo
• Whaticket: la plataforma comercial gestionada

Licencia

MIT © Whaticket y colaboradores.

Aviso legal

Este proyecto no está afiliado, asociado, autorizado, respaldado ni conectado oficialmente de ninguna forma con WhatsApp ni con ninguna de sus subsidiarias o filiales. El sitio oficial de WhatsApp es https://whatsapp.com. "WhatsApp" y los nombres, marcas, emblemas e imágenes relacionados son marcas registradas de sus respectivos dueños.

Usar clientes no oficiales para conectarse a WhatsApp puede provocar el bloqueo de tu número. Usa este software bajo tu propio riesgo y revísalo según tus propios requisitos de seguridad antes de exponerlo a internet.