WhaTicket Community Documentation

To deploy WhaTicket on a bare-metal Ubuntu 20.04 VPS, follow these high-level steps:

1. User Setup: Create a non-root user with sudo privileges (required for Puppeteer).
2. System Dependencies: Install Node.js (v14.x), Docker, and Puppeteer system dependencies.
3. Database: Run a MariaDB container via Docker or use docker-compose to start MySQL.
4. Backend Setup:
   • Clone the repository.
   • Configure backend/.env.
   • Install dependencies, build, and run Sequelize migrations/seeds.
   • Use pm2 to manage the backend process.
5. Frontend Setup:
   • Configure frontend/.env with the REACT_APP_BACKEND_URL.
   • Build the app and use pm2 to manage the frontend process.
6. Reverse Proxy: Install Nginx, configure site blocks for both frontend and backend subdomains, and increase client_max_body_size to 20M to allow larger media uploads.
7. SSL: Use Certbot to enable HTTPS for both subdomains.

# Example: Create deploy user
adduser deploy
usermod -aG sudo deploy

# Example: Install Puppeteer dependencies
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

You can set up the required MySQL database using Docker or docker-compose.

Using Docker CLI: Run the following command, ensuring you replace the placeholder passwords with strong values. The database uses utf8mb4 character sets to support various message types.

Using docker-compose: Before running, copy .env.example to .env and configure your database credentials. Then run:

docker-compose up -d mysql

Administering with phpMyAdmin: You can run phpMyAdmin to manage the database easily. It runs on port 9000 by default, but you can change this using the PMA_PORT environment variable. Use the following command to start it:

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

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:latest --character-set-server=utf8mb4 --collation-server=utf8mb4_bin

After cloning the repository, follow these steps to set up the backend:

1. Environment Setup: Navigate to the backend folder, copy .env.example to .env, and configure the variables.
2. Required Environment Variables:
   • NODE_ENV: Set to DEVELOPMENT for debugging.
   • BACKEND_URL: The URL of your backend.
   • FRONTEND_URL: The URL of your frontend.
   • PROXY_PORT: Port for the proxy.
   • PORT: The backend port.
   • DB_HOST, DB_DIALECT, DB_USER, DB_PASS, DB_NAME: MySQL connection details.
   • JWT_SECRET, JWT_REFRESH_SECRET: Security tokens for authentication.
3. Installation and Initialization:
   • Install dependencies: npm install
   • Build the app: npm run build
   • Run migrations: npx sequelize db:migrate
   • Run seeds: npx sequelize db:seed:all
4. Execution:
   • Start the server: npm start

# Backend setup sequence
cp .env.example .env
nano .env
# (Edit .env with required variables)
npm install
npm run build
npx sequelize db:migrate
npx sequelize db:seed:all
npm start

The Contacts component provides a user interface for managing customer contacts. It supports searching, adding new contacts, editing existing ones, deleting contacts, and importing contacts.

Key Functionalities

• Search: Real-time searching of contacts using a debounced search parameter.
• Pagination: Infinite scrolling is implemented via the onScroll handler on the Paper component. When the user scrolls near the bottom, loadMore increments the pageNumber to fetch more results.
• Real-time Updates: The component listens to socket.io events for contact actions. It automatically updates the local state when a contact is created, updated, or deleted.
• Ticket Creation: Users can quickly start a conversation with a contact by clicking the WhatsApp icon, which triggers handleSaveTicket to create an open ticket.
• Permissions: Deleting a contact is protected by the <Can /> component, requiring the user to have the contacts-page:deleteContact permission based on their profile.

API Interactions

• GET /contacts/: Fetches a paginated list of contacts. Supports searchParam and pageNumber query parameters.
• POST /tickets: Creates a new ticket for a specific contactId with status: "open".
• DELETE /contacts/:contactId: Removes a contact from the system.
• POST /contacts/import: Triggers a contact import process.

The Connections component provides a management interface for WhatsApp sessions. It allows users to view a list of connections, check their connection status, and perform various actions such as adding new connections, editing existing ones, disconnecting sessions, or deleting connections entirely.

Key connection statuses handled include:

• CONNECTED: The session is active.
• DISCONNECTED: The session is inactive.
• qrcode: The session is waiting for a QR code scan.
• OPENING: The system is currently attempting to connect.
• PAIRING / TIMEOUT: The session is in a transitional or failed state.

Actions available based on status:

• Add: Create a new WhatsApp connection.
• Edit: Modify details of an existing connection.
• Try Again: Restart a DISCONNECTED session.
• New QR: Request a new QR code for a DISCONNECTED session.
• Disconnect: Terminate an active session (CONNECTED, PAIRING, or TIMEOUT).
• Delete: Permanently remove a connection.