open-wa Node.js Toolkit

The @open-wa/wa-automate package provides a reliable WhatsApp automation solution with the following capabilities:

• Easy API: Run a standalone server and interact via HTTP.
• Multi-session: Manage multiple WhatsApp accounts simultaneously.
• Robustness: Advanced retries and state management.
• Drivers: Support for Playwright, Puppeteer, and Lightpanda.

The @open-wa/core package serves as the integration backbone for the Open-WA monorepo, providing the following capabilities:

• Driver Abstraction: A unified interface for interacting with different browser automation engines.
• Session Management: Handles the secure storage and restoration of authentication states.
• Event Bus: Utilizes @open-wa/hyperemitter for high-performance internal communication.

Plugins run within the open-wa host process but operate under strict security boundaries to ensure host stability and security.

Security Restrictions

• No Event Emission: Plugins can only subscribe to events; they cannot use events.emit() to send custom events into the host system.
• No Internal Event Access: The host filters out sensitive event namespaces such as launch.*, browser.*, transport.*, license.*, and raw session/authentication data.
• No Direct Browser Access: Plugins interact via a client proxy. You cannot execute CDP commands, manipulate the DOM, access browser cookies/storage, or inject scripts directly.
• Scoped File System Access: Plugins are restricted from reading or writing arbitrary files on the host. File operations must be scoped to the plugin's own data directory.

To effectively use the client, you should understand the following core architectural concepts:

• Schema Pipeline: Uses a single definition to create multiple projections.
• BaseClient: The generated flat client and dispatch table.
• Namespaced Client: How namespace members are mapped to the client.
• Argument Normalization: Handles the conversion between positional and object arguments, including aliases.
• Aliases: Support for function and parameter key aliases.
• Data Models: Core schemas for Message, Contact, Chat, and GroupMetadata.
• Generated Types: The source of input and output type aliases.
• Events: Registered events and their associated payloads.
• Licensed Methods: Identification of which methods require a license key.

Select an integration pattern based on your specific requirements for complexity and use case:

• Webhooks: Best for pushing events to an existing service (Low complexity).
• SocketClient: Best for building a bot directly in Node.js (Medium complexity).
• Plugins: Best for creating reusable integrations that run inside the open-wa process (Medium complexity).
• Chatwoot: Best for providing a full inbox experience with human agents (Medium complexity).
• MCP: Best for allowing AI agents to control WhatsApp (Low complexity).
• Embedded runtime: Best for full control over the browser (High complexity).

Depending on your architecture, you will interact with open-wa in one of two ways:

1. Easy API: A hosted runtime surface that exposes client functionality over HTTP. It is activated by running npx @open-wa/wa-automate. It provides interactive documentation and generated schemas.
2. SocketClient: A remote consumer client used to connect to an Easy API instance. Use this pattern if you want to consume open-wa features without embedding the full browser automation runtime (Puppeteer/Playwright) directly into your own application.