How secreto31126/whatsapp-api-js works
This project is a TypeScript framework designed to work as a server-agnostic implementation of WhatsApp’s official API. Its main purpose is to let developers easily integrate WhatsApp messaging features into a variety of server environments (e.g., Express, Next, Node HTTP, Bun, Deno, SvelteKit, Vercel, etc.) with full TypeScript support and built-in middleware.
Main Components
• WhatsApp API Core: The central “WhatsAppAPI” class (located in src/index.ts) is the heart of the framework. It handles initialization, configuration (tokens, secrets, webhook verification), and holds event emitters for incoming (on.message) and outgoing (on.sent) messages.
• Message Definitions: Found in src/messages (e.g., contacts.ts, globals.ts, interactive.ts, etc.), these define the different types of messages that can be sent/received.
• Middleware Adapters: The src/middleware directory contains adapters for various server runtimes/frameworks (e.g., express, adonis, bun, deno, next, node-http, sveltekit, vercel, web-standard). These modules provide integration points enabling the library to be used in different environments.
• Environment/Setup Files: The src/setup directory (e.g., node.ts, bun.ts, deno.ts, web.ts) provides tailored initialization routines for different platforms.
• Utility and Core Helpers: Modules like src/emitters.ts, src/errors.ts, and src/utils.ts encapsulate common functionality such as error handling and event emission.
• Standalone Functionality: The src/standalone.ts file may provide a way to run or test the library independent of server integration.
• Testing: The test directory contains modules for unit tests and mocks ensuring the integrity of message handling and integration.
Establish Relationships and Data Flow
• Client Integration: At the top, external client code (user implementations) will import and initialize the WhatsAppAPI class, providing configuration parameters and setting event handlers.
• Incoming Requests & Webhook Handling: Webhook events from the Meta WhatsApp Cloud API are received by the server. They are processed by middleware adapter(s) to properly pass parsed request data into the API logic.
• Message Processing and Event Emission: Once a message is received, it is parsed and routed through the core API, leveraging message type definitions and error handling. Then, events (such as ‘on.message’ and ‘on.sent’) are triggered.
• Outgoing Messaging: Responses or outgoing messages are built using one of the message constructors found in src/messages, sent via the framework’s reply logic.
• Environmental Adaptation: The setup modules adjust the library’s behavior based on the runtime environment (e.g., initializing for Node, Bun, Deno, or web-based deployments).
• Integration Testing: The tests ensure that these components interact as expected, covering both API logic and middleware integration.
Architectural Patterns
• Modular and Pluggable Architecture: Separation into distinct directories for messages, middleware, and setups allows for modular extension and easy integration with various runtimes.
• Event-Driven Design: The “on” event handlers (for message receipt and sending) indicate a decoupled, event-driven approach.
• Abstraction Layer for Runtimes: Middleware adapters hide the differences between various server frameworks, making the library server agnostic.
Incorporate Relevant Technologies and Frameworks
• TypeScript for type safety.
• Multiple middleware patterns for popular server frameworks (Express, Next, etc.).
• Standard Node.js modules (and environment-specific modules for Bun, Deno) with configuration through Firebase (firebase.json) and CI/CD setups (GitHub workflows for releases, code analysis, and deploys).
Essential Elements
• Use clear labels for each component.
• From the external WhatsApp cloud API to the Webhook (middleware adapters).
• From the middleware to the core API handler and then back out.
• Core Business Logic (e.g., WhatsAppAPI class, event handlers).
• Middleware Adapters (each tailored for a different runtime).
• Supporting Modules (messages, setup, utilities).
• External Systems (Meta WhatsApp API, client code).
• Optionally, include CI/CD and testing modules (from .github and test directories) as supporting but peripheral aspects.
Detailed Steps for the Engineer
• An “Environment Setup” block that connects to the API core, indicating how runtime-specific initialization is performed.