felipeDS91/whatsapp-api: Self-Hosted REST API for WhatsApp Messaging

felipeDS91/whatsapp-api: Self-Hosted REST API for WhatsApp Messaging

Developers building notification systems, customer support tools, or automated messaging workflows often face a frustrating gap: WhatsApp's official Business API requires Meta approval, third-party SaaS providers charge per-message fees, and unofficial libraries demand deep protocol knowledge. felipeDS91/whatsapp-api bridges this gap with a self-hosted, queue-based REST API built on proven open-source foundations.

What is felipeDS91/whatsapp-api?

felipeDS91/whatsapp-api is an open-source REST API that enables programmatic WhatsApp message sending through a locally hosted server. Maintained by Felipe Douglas and licensed under MIT, the project has accumulated 998 GitHub stars and 143 forks as of its last commit on January 24, 2026. The codebase is written primarily in TypeScript, reflecting a deliberate choice for type safety in an integration-heavy domain.

The architecture separates concerns into two distinct processes: a standard REST API server and a dedicated WhatsApp message client that manages queue processing and WebSocket connections to WhatsApp's servers. This dual-process design allows independent scaling and failure isolation—if the message queue consumer encounters issues, the API remains responsive for new submissions.

The project leverages whatsapp-web.js under the hood, a well-established Node.js library that controls WhatsApp Web through Puppeteer. This approach avoids the complexity of reverse-engineering WhatsApp's protobuf protocol directly, though it introduces browser automation dependencies that developers must account for in deployment planning.

Relevance in 2026 stems from persistent demand for WhatsApp integration without platform lock-in. Small businesses, indie developers, and teams in regions with limited Meta API access need solutions they can run on their own infrastructure. The MIT license removes commercial usage barriers, making this viable for both personal projects and product integrations.

Key Features

Dual-Process Architecture: The separation between API and WhatsApp client processes enables operational flexibility. Developers can run both on a single machine during development, then distribute them across containers or servers in production for better resource utilization.

Queue-Based Message Delivery: Messages submitted to the API enter a persistent queue rather than attempting immediate delivery. This design handles WhatsApp Web connection instability gracefully—messages wait until the client reconnects rather than failing outright.

JWT Authentication: API access is protected through JSON Web Tokens, with default credentials (admin/123456) for initial setup. The /sessions endpoint handles token generation, while /users and /tokens routes provide administrative control over access.

MySQL^{↗ Bright Coding Blog} Persistence: TypeORM manages database operations against MySQL, storing messages, queue state, and user records. This relational approach suits audit requirements and message history queries better than ephemeral in-memory storage.

QR Code Session Management: WhatsApp Web authentication uses QR code scanning. The /tokens endpoint generates both a QR code image and terminal-rendered output, allowing headless server setup without GUI dependencies.

Insomnia Integration: The repository includes an Insomnia.json collection and a "Run in Insomnia" button for immediate API exploration. This reduces friction for developers evaluating the tool's capabilities.

Docker^{↗ Bright Coding Blog}-Ready Dependencies: While the application itself requires Node.js and Yarn, the database dependency is containerized through a one-line Docker command for MySQL 5.7.30.

Use Cases

Internal Notification Systems: Engineering teams can integrate felipeDS91/whatsapp-api with monitoring stacks (Prometheus Alertmanager, PagerDuty webhooks) to deliver critical alerts directly to on-call engineers' WhatsApp. The queue ensures alerts survive temporary connectivity issues.

Small Business Customer Communication: E-commerce operations or service businesses can build lightweight CRM integrations. A PHP^{↗ Bright Coding Blog} or Python^{↗ Bright Coding Blog} backend submits order confirmations or appointment reminders to the API, which handles the WhatsApp-specific authentication and rate limiting.

Automated Reporting Delivery: Scheduled jobs generating daily/weekly reports can push summaries to stakeholder WhatsApp numbers. The MySQL backend provides delivery confirmation tracking for compliance or debugging purposes.

Development and Testing Environments: Teams building WhatsApp-native features can use this API as a test double for Meta's official API, avoiding sandbox limitations and approval delays during early development phases.

Regional Messaging Infrastructure: In markets where WhatsApp dominates communication but Meta's business API has limited availability or prohibitive costs, self-hosting provides operational independence.

Installation & Setup

The README provides explicit setup commands. Reproduce them precisely:

Prerequisites

• Docker (for MySQL container)
• Node.js v14 or higher
• Yarn package manager

Clone and enter the project directory:

$ git clone https://github.com/felipeDS91/whatsapp-api.git && cd whatsapp-api

Install dependencies:

$ yarn

Start MySQL via Docker:

$ docker run --name "whatsapp" -e MYSQL_ROOT_PASSWORD="mysql_password" -p 3306:3306 -d mysql:5.7.30

Note: Replace "mysql_password" with your chosen root password. MySQL 5.7.30 is explicitly specified—using a newer major version may require compatibility verification.

Create a dedicated database user: Connect with a MySQL client (DBeaver, mysql CLI, etc.) and execute:

CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';

Replace 'username' and 'password' with your credentials, then grant appropriate database permissions.

Configure environment variables:

$ cp .env.example .env

Edit .env with your database credentials and any other required settings.

Run database migrations:

$ yarn typeorm migration:run

Start the application:

For combined API and WhatsApp client:

$ yarn dev:server

For separate processes (useful for debugging or distributed deployment):

$ yarn dev:api      # REST API server only
$ yarn dev:whatsapp # WhatsApp client only

Initial authentication: Access the API with default credentials:

• Username: admin
• Password: 123456

Generate a JWT token via the /sessions endpoint before accessing protected routes.

Real Code Examples

The README does not contain extensive inline code samples for API consumption. The following examples are derived directly from the documented endpoints and setup instructions, with explicit notes where behavior is inferred from the architecture.

Authenticating and obtaining a JWT token:

# POST /sessions
# Request body inferred from standard JWT login patterns
curl -X POST http://localhost:3333/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456"
  }'
# Expected response: { "token": "eyJhbGciOiJIUzI1NiIs..." }

This follows conventional Express/JWT patterns documented in the technology stack. The actual response shape should be verified against running instance behavior.

Submitting a message to the queue:

# POST /message
# Inferred from endpoint documentation; exact payload structure not specified in README
curl -X POST http://localhost:3333/message \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Your appointment is confirmed for tomorrow at 2pm."
  }'

The README confirms /message sends to queue but does not document the complete request schema. Inspect the TypeORM entities or route handlers in src/ for definitive structure.

Retrieving QR code for WhatsApp Web pairing:

# GET /tokens
# Returns QR code image and renders to terminal
curl http://localhost:3333/tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This endpoint is documented as returning both an image response and CLI-rendered QR code. The dual output format accommodates both API-driven workflows and manual server setup.

The limited code examples in the README reflect a documentation gap rather than API simplicity. Developers should expect to read source code for complete endpoint specifications.

Advanced Usage & Best Practices

Process Separation in Production: The yarn dev:api and yarn dev:whatsapp commands enable independent process management. Consider running each in separate containers or systemd units, with the WhatsApp client scaled cautiously—multiple instances with the same WhatsApp account trigger security blocks.

Credential Rotation: The default admin/123456 credentials must be changed before any network exposure. The /users administrative route supports this, though the README lacks specific user management examples.

Database Connection Resilience: The queue-based design assumes MySQL availability. Implement connection pooling and retry logic in production, or consider the operational overhead of managed database services.

Puppeteer Resource Management: The whatsapp-web.js dependency launches Chromium instances. Monitor memory usage and implement process restarts for long-running deployments—browser contexts accumulate memory leaks over days of operation.

Rate Limiting Awareness: WhatsApp's anti-spam systems are not documented in the README but are well-documented in the broader community. Implement application-level rate limiting and respect the explicit warning: "you have to be careful to not be banned for sending spam using whatsapp."

Comparison with Alternatives

felipeDS91/whatsapp-api occupies a middle ground: more structured than raw libraries, more autonomous than SaaS options, but with corresponding operational responsibilities. Teams lacking DevOps^{↗ Bright Coding Blog} capacity may find the infrastructure burden prohibitive compared to managed alternatives.

FAQ

Does this use the official WhatsApp Business API? No—it uses whatsapp-web.js with Puppeteer to control WhatsApp Web, not Meta's approved business infrastructure.

Can I run this on Heroku? Yes, but requires the jontewks/puppeteer buildpack for Chrome dependencies. The README documents this explicitly.

What Node.js version is required? Node v14 or higher, per the documented requirements.

Is commercial use permitted? Yes, under the MIT License. No restrictions are stated.

How do I handle the QR code on a headless server? The /tokens endpoint renders QR codes in the terminal. Use a terminal multiplexer (tmux, screen) or redirect output to logs.

What happens if WhatsApp Web disconnects? The queue-based design holds messages until reconnection. Monitor the WhatsApp client process health.

Are there TypeScript type definitions? The project is written in TypeScript; source types are available, though published @types packages are not mentioned.

Conclusion

felipeDS91/whatsapp-api serves developers and small teams needing WhatsApp integration without platform dependency or per-message costs. Its 998-star community, MIT licensing, and explicit queue-based architecture make it suitable for notification systems, small business tools, and development environments where Meta's official API is inaccessible or overkill.

The trade-offs are clear: you manage Puppeteer, MySQL, and infrastructure scaling. For teams with existing Node.js/TypeScript expertise and container deployment experience, this is a pragmatic middle path. For those prioritizing zero-ops, managed SaaS alternatives remain more appropriate.

Evaluate the codebase, test the Insomnia collection, and determine if the dual-process architecture fits your reliability requirements. The repository awaits at https://github.com/felipeDS91/whatsapp-api.

For related self-hosted messaging infrastructure, see [INTERNAL_LINK: self-hosted notification systems] or explore [INTERNAL_LINK: TypeScript API development patterns].