How cfranco92/chat-bot-openai-whatsapp works
Project Type and Purpose
• This is a full-stack Node.js application that serves as a WhatsApp chatbot. It integrates with the WhatsApp Business API to receive messages, uses OpenAI’s API for intelligent responses, and stores data in Google Sheets. It’s designed around a flexible conversation flow (appointment scheduling by default) with multi-language support.
File Structure
• The top-level directories and core files (app.js, routes, controllers, services) indicate the use of the Model-View-Controller (MVC)-like pattern, although this is mostly a service-based design.
• The “src/config” handles environment and configuration variables which are important for controlling the system’s behavior.
• In “src/controllers” you see webhookController.js, which suggests that incoming HTTP requests (webhooks) are immediately routed here.
• “src/routes” (webhookRoutes.js) is the Express router layer mapping endpoints to controllers.
• “src/services” contains the business logic components such as messageHandler.js, whatsappService.js, googleSheetsService.js, and openAiService.js. This is where external integrations and heavy lifting occur.
• “src/i18n” contains all internationalization assets, allowing support for multiple languages.
• The tests in “src/__tests__” confirm that the project validates its components via unit and integration testing.
Elements
a. Main Components:
• Client / External Systems: WhatsApp Business API is the provider of incoming messages and data, and external systems (Google Sheets API, OpenAI API) are also integral.
• HTTP Webhook Endpoint: Represented by the Express router (webhookRoutes.js) that handles inbound HTTP requests (GET for verification, POST for messages).
• Controller Layer: The webhookController.js handles routing logic and initiates service calls.
• Service Layer:
• Message Handler: Coordinates conversation flow.
• WhatsApp Service: Manages sending/receiving messages through WhatsApp.
• OpenAI Service: Processes natural language for responses.
• Google Sheets Service: Handles storing and retrieving data.
• Configuration / Environment: The config folder (with env.js) and environment variables (.env file) ensure correct API keys, tokens, and settings.
• Internationalization (i18n): Handles language-specific responses, using locales like English and Spanish.
b. Relationships and Interactions:
• The WhatsApp Business API sends webhooks to the Express server.
• The webhookRoutes maps incoming requests to webhookController.
• The controller calls the messageHandler, which orchestrates the overall process.
• Depending on the message content, the messageHandler interacts with:
• WhatsApp Service (for replies)
• OpenAI Service (for intelligent, AI-driven responses)
• Google Sheets Service (to log appointments or conversation data)
• The i18n module is used throughout to adapt responses to the user’s language based on configuration.
• Environment config is used across all components for consistent settings such as tokens, API keys, and language preferences.
c. Architectural Patterns and Design Principles:
• Separation of concerns with explicit routing, controllers, and services.
• External API integration pattern - each external service (WhatsApp, OpenAI, Google Sheets) is encapsulated within its own service module.
• Internationalization is modularized via the i18n directory.
• Configuration via environment variables increases flexibility and deployment agility.
d. Technologies and Frameworks:
• Express.js for HTTP server and routing.
• Node.js as the platform.
• Jest and Supertest for testing.
• dotenv for configuration management.
• i18next for internationalization.
Elements to Integrate
• Use clear labels for each component (i.e., “Webhook Routes”, “Webhook Controller”, “Message Handler”, “WhatsApp Service”, “OpenAI Service”, “Google Sheets Service”, “Internationalization Module”, “Configuration”).
• From “WhatsApp Business API” to “Webhook Routes” (incoming HTTP requests).
• From “Webhook Routes” to “Webhook Controller”, then to “Message Handler”.
• From “Message Handler” to each service (WhatsApp Service, OpenAI Service, Google Sheets Service).
• Internal server components vs external services.
• Utility modules such as configuration and i18n.