OpenWA

OpenWA: Free, Open Source WhatsApp API Gateway for developers

In a landscape where messaging infrastructure often comes with vendor lock-in, hidden fees, and restricted access to source code, OpenWA emerges as a robust alternative. It is a free, open-source WhatsApp API gateway designed for developers who demand full control, transparency, and flexibility. Built with a pluggable architecture, OpenWA lets you tailor every layer of your messaging stack—from databases to storage to caching—without rewriting your application code. The result is a dev-friendly platform that accommodates evolving requirements, scales with your business, and stays free of proprietary constraints.

Images and badges you’ll see in the project reflect its practical maturity and ongoing maintenance:

• OpenWA logo at the top to anchor the brand identity.
• A collection of status and capability badges signaling version, licensing, runtime targets, and supported technologies.

Why OpenWA?

OpenWA is more than a WhatsApp bridge. It is a deliberate design that prioritizes openness, modularity, and operator autonomy. The core philosophy is simple: give developers a gateway that behaves as a true, pluggable platform rather than a monolithic black box. The highlights include:

• 100% Open Source: No licensing fees, no feature gates, and unfettered access to the source code. You can inspect, modify, and extend every part of the system.
• Pluggable Architecture: The adapters for databases, storage backends, and caches are swappable via configuration. If SQLite isn’t your cadence or you prefer a different storage layer, you can switch with minimal fuss.
• Full Dashboard: A modern React-based web UI enables session management, webhook configuration, and API key administration. Observability and control are baked into the experience.
• Multi-Session Ready: Run multiple WhatsApp sessions concurrently on a single OpenWA instance. Each session can have its own settings, numbers, and state, enabling complex deployments without sprawling infrastructure.
• Docker Native: Production-ready with zero-configuration approach. Docker and Docker Compose streamline deployment, reproducibility, and scaling.
• n8n Integration: Community nodes connect OpenWA to workflow automation, enabling seamless automation and integration with broader automation ecosystems.
• Developer-First Experience: With REST APIs, comprehensive docs, and a design that emphasizes clean separation of concerns, developers can build, test, and iterate quickly.

Core Features

OpenWA’s core features establish a solid foundation for reliable WhatsApp automation and integration.

• REST API: A complete WhatsApp API surface accessible via HTTP endpoints. This makes integration straightforward for any language or platform that can issue HTTP requests.
• Multi-Session: Manage several WhatsApp accounts in parallel. Each session stands alone, with its own keys, tokens, and lifecycle.
• Webhooks: Real-time event delivery with optional security via HMAC signatures. Webhooks enable you to react to incoming messages, session changes, and more, powering event-driven automation.
• Web Dashboard: An accessible, modern dashboard for managing sessions, webhooks, and API keys. Observability and control are centralized in a single interface.
• API Key Authentication: Secure access control through API keys to enforce proper usage and governance.
• Swagger Documentation: Interactive API documentation to speed up exploration, testing, and developer onboarding.

Messaging Capabilities

OpenWA makes outbound and inbound messaging fluent and versatile.

• Text Messages: Send and receive plain text messages, with reliable delivery semantics.
• Media Messages: Support for images, videos, documents, and audio. Media handling is designed to be efficient and scalable.
• Message Reactions: Respond to messages with emoji reactions, enabling richer conversations without creating new threads.
• Bulk Messaging: Send messages to multiple recipients in a single operation, while respecting rate limits and compliance considerations.
• Message Status: Track delivery, read receipts, and delivery failures to monitor performance and end-user experience.

Advanced Features

Beyond basic messaging, OpenWA offers features that address real-world enterprise needs.

• Groups API: Create, manage, and message WhatsApp groups. Group administration is streamlined and programmable.
• Channels/Newsletter: Support for WhatsApp Channels and subscription-based messaging to channels or newsletters.
• Labels Management: Organize chats with labels for efficient routing, filtering, and analytics.
• Proxy Support: Per-session proxy configuration to adapt to network constraints and ensure reliable connectivity.
• Rate Limiting: Configurable request limits to protect backends, maintain quality of service, and prevent abuse.
• CIDR Whitelisting: IP-based access control to secure API exposure and reduce the risk surface.
• Audit Logging: Comprehensive audit trails to track all API operations for compliance and troubleshooting.

Infrastructure and Backend

OpenWA is designed to work across development and production environments with flexible backend choices.

• SQLite: Zero-config embedded database for lightweight development and testing.
• PostgreSQL: Production-grade database option for robust reliability and scalability.
• Redis Cache: Optional performance caching to accelerate frequently accessed data and reduce latency.
• S3/MinIO Storage: Scalable media storage with support for S3-compatible backends.
• Docker: One-command deployment for reproducible environments and easy scaling.
• Health Checks: Kubernetes-ready probes and health endpoints to support robust orchestration.
• Data Migration: Smooth export/import paths between backends to facilitate migrations with minimal downtime.

Quick Start

OpenWA embraces practical paths to getting started, whether you prefer containerized adoption or local development.

Option A: Docker (Recommended)

• Clone the repository
• git clone https://github.com/rmyndharis/OpenWA.git
• cd OpenWA
• Start the stack
• docker compose -f docker-compose.dev.yml up -d
• Access
• Dashboard: http://localhost:2886
• API: http://localhost:2785/api
• Swagger: http://localhost:2785/api/docs

Option B: Local Development

• Clone the repository
• git clone https://github.com/rmyndharis/OpenWA.git
• cd OpenWA
• Install dependencies (dashboard included)
• npm install
• Start API + Dashboard (config auto-generated on first run)
• npm run dev
• Access
• Dashboard: http://localhost:2886
• API: http://localhost:2785/api
• Swagger: http://localhost:2785/api/docs

Production Deployment

For production deployments, OpenWA provides structured profiles to tailor the stack to your needs.

• Basic production (SQLite, local storage)
• docker compose up -d
• With PostgreSQL database
• docker compose --profile postgres up -d
• Full stack (PostgreSQL, Redis, Dashboard, Traefik)
• docker compose --profile full up -d

Service profiles map to a combination of services:

• postgres: PostgreSQL database
• redis: Redis cache
• minio: S3-compatible storage
• with-dashboard: Web dashboard
• with-proxy: Traefik reverse proxy
• full: All services above

Development vs Production

• Development uses docker-compose.dev.yml with SQLite and local storage, including both API and Dashboard for rapid iteration.
• Production uses docker-compose.yml with profiles to enable optional services and production-grade configurations.

Ports and Accessibility

• API: 2785 for REST endpoints
• Dashboard: 2886 for web-based management
• Swagger docs: 2785/api/docs for interactive API exploration

API Examples

To illustrate typical interactions with the OpenWA API, here are representative workflows (commands shown as examples).

Create a Session

• curl -X POST http://localhost:2785/api/sessions \ -H "Content-Type: application/json" \ -H "X-API-Key: YOURAPIKEY" \ -d '{"name": "my-bot"}'

Start Session and Get QR Code

• Start session:
• curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \ -H "X-API-Key: YOURAPIKEY"
• Get QR code (scan with WhatsApp):
• curl http://localhost:2785/api/sessions/{sessionId}/qr \ -H "X-API-Key: YOURAPIKEY"

Send a Message

• curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \ -H "Content-Type: application/json" \ -H "X-API-Key: YOURAPIKEY" \ -d '{ "chatId": "628123456789@c.us", "text": "Hello from OpenWA!" }'

Setup Webhook

• curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \ -H "Content-Type: application/json" \ -H "X-API-Key: YOURAPIKEY" \ -d '{ "url": "https://your-server.com/webhook", "events": ["message.received", "session.status"], "secret": "your-hmac-secret" }'

These examples illustrate the practical workflow: provisioning a session, starting it to obtain a QR for WhatsApp pairing, sending messages, and wiring webhooks to receive real-time events.

Tech Stack

OpenWA’s architecture and technology choices reflect a balance between performance, maintainability, and developer familiarity.

• Runtime: Node.js 22 LTS
• Framework: NestJS 11.x
• Language: TypeScript 5.x
• WA Engine: whatsapp-web.js
• Database: SQLite or PostgreSQL
• Cache: Redis (optional)
• Storage: Local / S3 / MinIO
• ORM: TypeORM
• Containerization: Docker and Docker Compose

Project Structure

OpenWA’s layout is designed for clarity and extension. A high-level look helps teams orient themselves quickly:

• openwa/
• src/
  • main.ts: Application entry point
  • app.module.ts: Root module
  • config/: Configuration management
  • common/: Shared utilities
  • cache/: Redis caching
  • storage/: File storage (Local/S3)
  • core/: Core systems
  • hooks/: Plugin hooks
  • plugins/: Plugin system
  • engine/: WhatsApp engine abstraction
  • modules/
  • session/: Session management
  • message/: Message handling
  • webhook/: Webhook management
  • group/: Groups API
  • contact/: Contacts API
  • auth/: API key authentication
  • infra/: Infrastructure management
  • health/: Health checks
• dashboard/: React web dashboard
• docs/: Documentation
• docker-compose.yml
• Dockerfile
• package.json

Documentation

Comprehensive documentation accompanies the project, helping new users get started and existing teams deepen their usage.

• Project Overview
• Requirements Specification: Feature requirements and expectations
• System Architecture: Architectural diagrams and design decisions
• Security Design: How OpenWA protects data and access
• Database Design: Data models and migrations
• API Specification: Complete reference for endpoints, payloads, and responses
• Development Guidelines: Coding standards and best practices
• Migration Guide: How to migrate between databases or storage backends

Contributing

OpenWA invites contributions from developers who want to improve the project or adapt it to new environments.

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit changes with meaningful messages
• Push to the branch and open a Pull Request
• Review the Development Guidelines for coding standards and best practices

License

OpenWA is released under the MIT License. This license enables broad usage in both personal and commercial projects while preserving attribution and a permissive redistribution policy.

• MIT License: See LICENSE for details
• Community and Collaboration: The project is maintained by Yudhi Armyndharis and a global OpenWA community that contributes to documentation, examples, and plugins

From Vision to Reality: The OpenWA Experience

OpenWA presents a compelling value proposition for developers who build with WhatsApp as a primary channel. It aligns with modern software practices: open-source licensing, modular architecture, and cloud-native deployment. The ability to mix and match databases, caching, and storage means you can design a stack that suits your organization’s data governance, performance needs, and cost considerations. The inclusion of a web dashboard, a richly documented API, and a developer-friendly workflow lowers the barrier to entry while offering enterprise-grade capabilities—such as session isolation, per-session proxies, rate limiting, and audit logging—that matter for production deployments.

A practical note on security and governance: with per-session access controls, API key authentication, and HMAC-secured webhooks, OpenWA emphasizes careful management of credentials and event streams. This design helps keep your WhatsApp automation both auditable and controllable, which is essential as teams scale messaging operations or operate within strict regulatory contexts.

What You Can Build with OpenWA

• Customer support bots that leverage WhatsApp as the primary channel, backed by a robust REST API and webhook-driven event architecture.
• Automated notification systems (alerts, order updates, shipping notices) delivered to user devices with reliable read receipts.
• Marketing newsletters and broadcast channels that respect channel constraints while enabling precise audience targeting and segmentation.
• Internal workflows that connect WhatsApp interactions to CRM, ticketing, and analytics ecosystems through the included n8n integration and API endpoints.
• Multi-tenant or multi-session deployments that serve different brands or departments from a single OpenWA instance, thanks to the pluggable adapters and per-session configuration options.

Community and Sustainability

OpenWA thrives on community engagement. The project welcomes feedback, feature requests, and code contributions from developers around the world. The open-source model ensures that improvements can be audited, extended, and sustained beyond any single organization. Documentation is kept current to reflect evolving capabilities, and the dashboard provides a centralized experience for managing deployments in a transparent way.

Final Thoughts

For developers seeking a transparent, flexible, and scalable WhatsApp API gateway, OpenWA offers a thoughtful blend of openness and practicality. Its pluggable architecture invites experimentation and customization, while its production-ready components—Docker-based deployment, health checks, and robust audit capabilities—support real-world usage. The combination of a modern web dashboard, a solid REST API, and a focus on security and governance makes OpenWA a compelling platform for organizations that want to own their messaging stack rather than rent it.

If you’re curious to dive deeper, the project’s README and docs folder provide a thorough map to installation, configuration, and extension. The community-driven approach means that you are not just using a tool; you are contributing to a movement toward more open and flexible messaging infrastructure.

Images and acknowledgments

Throughout the description, the OpenWA branding and badges reflect the project’s status and capabilities. The OpenWA logo anchors the narrative, while badges convey version, license, and technology compatibility. These visuals serve as quick indicators of maturity and openness, complementing the textual content with tangible cues about how OpenWA can fit into your tech stack.

Thank you for exploring OpenWA—the Free, Open Source WhatsApp API Gateway that puts you in control. If you’d like to learn more, you can explore the docs folder, experiment with the docker-based quick start, or contribute to the ongoing evolution of the platform. Made with care by Yudhi Armyndharis and the OpenWA community.