DOCSEARCHbyAlgolia
Submit Docs

OpenWA

repository·main·Indexed 11 days ago

https://github.com/rmyndharis/openwa

An open-source WhatsApp API Gateway providing a REST and WebSocket interface for managing multiple WhatsApp sessions. Version 0.18.0 supports pluggable engines (whatsapp-web.js or Baileys), includes a web dashboard for session and webhook management, and provides a Go SDK for integration.

Tokens
253.5K
Snippets
601
Records
921
Agent score
96%

What's inside OpenWA

  1. Overview of OpenWA Dashboard features

    main

    The OpenWA Dashboard is a modern web interface for managing OpenWA WhatsApp API Gateway sessions, webhooks, and infrastructure. Key capabilities include:

    • Session Management: Create, monitor, and control WhatsApp sessions.
    • QR Code Authentication: Real-time QR code display for device pairing.
    • Webhook Configuration: Configure and test webhook endpoints.
    • API Key Management: Generate and manage API keys.
    • Infrastructure Monitoring: View system health and storage status.
    • Real-time Updates: Live session status via WebSocket.

  2. Overview of OpenWA SDKs

    main

    OpenWA provides official client libraries for the OpenWA WhatsApp API Gateway. All SDKs are hand-written to match the exact API surface (paths, DTOs, response shapes) and are unit-tested against mocked HTTP transports to prevent drift. The SDKs use a fluent resource-based surface (e.g., client.sessions, client.messages) to interact with the gateway.

    Available SDKs

    LanguagePackageNotes
    JavaScript / TypeScript@rmyndharis/openwaDual ESM/CJS, bundled types
    Pythonrmyndharis-openwaSync (httpx), PEP 561 typed
    PHPrmyndharis/openwaSync (Guzzle, PHP 8.1+)
    Javacom.rmyndharis:openwaSync (java.net.http + Gson, Java 17)
    Gogithub.com/rmyndharis/OpenWA/sdk/goStdlib-only, context-first, injectable transport (Go 1.22+)

  3. Overview of the OpenWA Dashboard architecture

    main

    The OpenWA Dashboard is a web-based management interface designed to manage sessions, webhooks, and monitor activity without direct API calls.

    Tech Stack

    • Frontend: React 19, Vite 8, TypeScript, and Lucide icons.
    • Styling: Uses plain, hand-written CSS colocated with components (e.g., Sessions.tsx + Sessions.css). It does not use Tailwind, shadcn/ui, or CSS-in-JS.
    • State Management:
      • Server State: Managed via TanStack Query (see src/hooks/queries.ts).
      • Client State: Uses React Context for RoleProvider and ToastProvider.
      • Theme: Managed via a useTheme hook backed by localStorage (no Zustand).
    • Backend Integration: Communicates with the OpenWA API and uses socket.io for real-time WebSocket updates.
    • Visuals: Charts are powered by recharts and internationalization via react-i18next.

  4. Overview of OpenWA Dashboard Wireframes

    main

    The OpenWA Dashboard provides a visual interface for managing WhatsApp sessions and system health. The interface is organized into several key views:

    • Dashboard Home: A high-level overview showing key metrics (Sessions, Connected status, Message volume, Active Webhooks), a Sessions Overview, Recent Activity feed, and Message Volume charts.
    • Session List: A searchable and filterable list of all sessions. Each entry shows the session name, connection status (e.g., Connected, Disconnected), phone number, message count, and last active timestamp. Actions include QR scanning, Test Chat, Settings, and Delete.
    • Session Detail: A deep-dive view for a specific session containing:
      • Identity: Name, phone number, status, and platform (e.g., Android).
      • Session Management: Restart Session, Unlink Device, and Delete.
      • Statistics: Messages sent/received, webhook calls, and uptime.
      • Configuration: Auto-reconnect settings, Webhook URL, and Proxy settings.
      • Recent Messages: A snippet of the latest incoming/outgoing messages.
    • QR Code Scanner: A dedicated view for pairing new devices via the WhatsApp 'Linked Devices' menu.
    • Test Chat Interface: A simulated chat environment to verify session functionality and message flow.

    Each view is designed to facilitate rapid monitoring and management of the OpenWA engine.

  5. What is OpenWA?

    main
    OpenWA is an open-source platform that provides an HTTP REST API for WhatsApp integration. It is designed as a free, self-hosted alternative to paid solutions like WAHA Plus, offering features such as multi-session support, a web dashboard, and PostgreSQL integration without paywalls. It is built using Node.js 22 LTS, NestJS, and TypeScript.

  6. Explore community-built OpenWA integrations

    main

    The OpenWA ecosystem includes third-party integrations and adapters built on top of the OpenWA REST API.

    Important Distinctions:

    • First-party integrations: Official integrations like Chatwoot and Typebot are shipped as sandboxed plugins on the Integration Fabric. You can find them in the OpenWA-plugins catalog.
    • Community integrations: These are independent projects not affiliated with or endorsed by OpenWA. They may not always be compatible with the latest OpenWA API changes. Always verify compatibility and review the source code before production use.

    Available Community Integrations:

    IntegrationPlatformSourceNotes
    ioBroker.openwaioBroker (IoT automation)GitHub / npmSend text, image, video, audio, or document messages to chats/groups via OpenWA REST API using Blockly blocks. (Early stage)

  7. Review the OpenWA release roadmap and history

    main

    The OpenWA project follows a phased roadmap. Key milestones include:

    • v0.0.1 - v0.1.0: Foundation, MVP, and initial stable release.
    • v0.2.0: Added i18n, Real-time Chats, and Webhook delivery-state.
    • v0.3.0: Introduced Engine Pluggability (e.g., Baileys engine) and a plugin layer.
    • v0.4.0: Single-port deployment (Dashboard served from the API port).
    • v0.5.0 - v0.12.x: Incremental releases including Java & Go SDKs, live message edits, and EngineRegistry for session/engine decomposition.
    • v1.0.0 (Planned): Enterprise-ready features including a Kubernetes Operator and multi-tenancy.

  8. Understand the OpenWA testing strategy and known gaps

    main

    OpenWA prioritizes deterministic tests to ensure contributor workflows remain stable and do not require external credentials or hardware.

    Key Testing Principles

    • No External Dependencies: Default CI jobs do not require a real WhatsApp connection, cloud credentials (S3/MinIO), or a Docker socket.
    • Local-First Stability: npm test and npm run test:e2e are designed to run on SQLite with the queue disabled, ensuring they work on any machine without requiring complex service containers.
    • Intentional Gaps: Certain integrations (S3, Docker socket proxy, real WhatsApp connections) are not exercised by default CI to prevent brittle workflows.

    Known Limitations

    • Database: The default test job uses SQLite. PostgreSQL 16 is only exercised via the dedicated test-postgres job.
    • Storage/Proxy: No default CI job exercises S3/MinIO or Docker socket proxy integration.
    • Automation Gaps: Performance testing and Dashboard browser/visual UI tests are not currently automated.
    • Dashboard Testing: While visual tests are manual, pure utility tests for the dashboard can be run via the dashboard package.

  9. Review the OpenWA Phase 3 (Advanced Features) features

    main

    Phase 3 (v0.1.0) aims for full feature parity with advanced WhatsApp functionalities and community tooling.

    Advanced Messaging:

    • Send location, contacts, and stickers
    • Message reactions, replies, and forwarding
    • Message history

    Groups, Channels & Contacts:

    • Full Groups API (list, info, members, create, manage participants, settings)
    • Channels/Newsletter support
    • Contact list API
    • Labels management

    Scaling & Community:

    • n8n integration (via separate repo)
    • Horizontal scaling design references
    • Comprehensive API documentation (Swagger)

  10. Understand the CI/CD Pipeline

    main

    The GitHub Actions workflow (.github/workflows/ci.yml) is used for integration testing and quality gates. It does not perform automatic deployments. The pipeline includes the following jobs:

    • lint: Runs ESLint, TypeScript type-checking, formatting checks, and OpenAPI validation.
    • audit: Runs npm audit (high level) to check for security vulnerabilities.
    • test: Executes unit and E2E tests (using a redis:7-alpine service for the queue).
    • test-postgres: Runs smoke tests and migrations against a postgres:16-alpine service.
    • dashboard: Runs linting, type-checking, and unit tests for the dashboard package.
    • scripts-smoke: Validates backup and restore shell scripts using shellcheck.
    • build: Compiles the project and uploads the dist artifact.
    • docker: Performs multi-arch builds (linux/amd64, linux/arm64) and pushes images to GHCR.

    Note: Rollout and deployment to staging or production environments must be handled manually by the operator.

  11. Review the OpenWA Phase 1 (MVP) features

    main

    Phase 1 (v0.0.1) focuses on providing a working single-session API with core WhatsApp connectivity.

    Core API & Session Management:

    • Create, delete, and get session status
    • Generate QR codes for connection
    • Session reconnection logic

    Messaging Capabilities:

    • Send text, images, video, audio, and documents
    • Receive incoming messages

    Webhooks:

    • Webhook delivery and retry mechanisms

    Infrastructure:

    • SQLite storage
    • Docker support
    • Health checks and Swagger documentation

  12. OpenWA Feature Roadmap and Scope

    main

    The project is being developed in phases. Current and upcoming capabilities include:

    Phase 1 (MVP)

    • REST API: Session management (create, delete, status), QR code authentication, sending messages (text, image, video, audio, document), receiving messages via webhooks, contact management, and basic group operations.
    • Infrastructure: Docker support, SQLite database, Swagger documentation, and health check endpoints.

    Phase 2 (Production Ready)

    • Multi-session support.
    • PostgreSQL support.
    • Web Dashboard and Webhook management UI.
    • Message queue (Redis/BullMQ) and Rate limiting.
    • API Key authentication.

    Phase 3 (Advanced)

    • Advanced group management (create, modify, participants).
    • Channels/Newsletter support.
    • Label management and Status/Stories.
    • Proxy per session and horizontal scaling.