WhatsApp HR Assistant

WhatsApp HR Assistant is a private bot for employee inquiries. An employee chats with the connected WhatsApp account, chooses a language and inquiry path, and receives information read from configured Google Sheets. Operators use a browser panel to pair the account and inspect its connection state.

The problem

Employee information can sit in spreadsheets while questions arrive as chat messages. A reply needs to follow a predictable sequence, select the right record, and survive a restart without losing the conversation step. Messages from the same chat may also arrive close together. The bot handles those concerns in the message router and storage services.

Key features

• Guide users through language, employee identification, inquiry type, and month selection.
• Support Arabic, English, and Urdu response catalogs.
• Match aliases and approximate input when users do not type an exact option.
• Read vacation and deduction data from configured Google Sheets.
• Cache spreadsheet information to reduce repeated reads.
• Store conversation state and bot settings in SQLite.
• Send replies through a prioritized queue with configurable delays.
• Show a pairing QR code and connection updates in a Socket.IO admin panel.
• Send operational alerts through Telegram.

Technical architecture

Baileys receives WhatsApp events and passes message text to a step router. The router loads conversation state from SQLite, then invokes a fixed allowlist of step handlers. Google Sheets requests go through a service with caching and retry behavior. A per-chat lock serializes messages for the same conversation. Outgoing replies enter p-queue before Baileys sends them. Express and EJS serve the admin interface, with Socket.IO carrying live status after session checks. Telegram is an operational alert channel.

Engineering highlights

• The step router uses an explicit handler map, so a database value cannot become an arbitrary module path.
• A per-chat mutex prevents fast consecutive messages from advancing the same conversation out of order.
• Conversation storage can migrate a previous phone-based key to a WhatsApp LID key.
• The message log records metadata rather than employee message content.
• Admin Socket.IO connections check both the session and the request origin.