DEV Community

Cover image for I Built a Self-Hosted WhatsApp Gateway Using Node.js, Docker and PostgreSQL
Nitin Mehta
Nitin Mehta

Posted on

I Built a Self-Hosted WhatsApp Gateway Using Node.js, Docker and PostgreSQL

#opensource #node #docker #webdev

Building Puffx WhatsApp Gateway: A Self-Hosted WhatsApp Messaging API with Node.js, Docker and PostgreSQL

Author: Nitin Mehta

Project: Puffx WhatsApp Gateway

GitHub Repository: https://github.com/puffxhost/puffx-whatsapp-gateway

Website: https://puffxhost.com

Introduction

What if developers could run their own WhatsApp messaging gateway instead of depending entirely on a third-party hosted messaging service?

That question inspired me to build Puffx WhatsApp Gateway, an open-source, self-hosted messaging gateway designed to connect a WhatsApp account with applications through a REST API.

The project brings together a web dashboard, WhatsApp account pairing, API key authentication, PostgreSQL, and Docker-based deployment.

The main idea is simple:

  • Run the gateway on your own computer or VPS.
  • Connect a WhatsApp account using QR pairing or a phone pairing code.
  • Manage the connected session through a web dashboard.
  • Generate an API key.
  • Send text messages from your own backend applications using HTTP requests.

I built this project under Puffx Host to explore backend development, API architecture, self-hosted infrastructure, and messaging integrations.

The project is currently in its initial beta stage.

Explore the source code:

https://github.com/puffxhost/puffx-whatsapp-gateway

1. What Is Puffx WhatsApp Gateway?

Puffx WhatsApp Gateway is a self-hosted application that exposes a REST API for sending text messages through a paired WhatsApp Web session.

Instead of using a gateway hosted by someone else, developers can deploy the application on infrastructure they control.

The application provides a web dashboard for managing sessions and API credentials.

Main Features

1. QR Code Pairing

Connect a WhatsApp account by scanning a QR code using WhatsApp's Linked Devices feature.

2. Phone Pairing Code

The project also supports an alternative phone pairing code flow.

3. Web Dashboard

Manage your account, create WhatsApp sessions, check connection status, and generate API keys.

4. REST API

Send text messages programmatically through an HTTP endpoint.

5. API Key Authentication

The API uses Bearer token authentication to authorize message requests.

6. PostgreSQL Database

PostgreSQL stores application data.

7. Docker Deployment

Docker Compose provides a convenient way to run the gateway and its database together.

8. Persistent Session Storage

Docker volumes preserve database data and WhatsApp authentication state across normal container restarts.

2. Technology Stack

I used the following technologies and tools to build the project.

Technology Purpose
Node.js Backend runtime
TypeScript Application development
PostgreSQL Database
Docker Containerization
Docker Compose Service orchestration
REST API Application integration
Baileys WhatsApp Web connectivity

Why Docker?

A self-hosted application should be relatively straightforward to deploy and maintain.

Docker makes it easier to package the gateway and database into a consistent environment.

Instead of manually configuring every dependency, developers can start the application using Docker Compose.

Why PostgreSQL?

The project needs persistent application data. PostgreSQL provides a relational database for managing that information.

3. Understanding the Architecture

At a high level, the application has four important parts:

  1. Dashboard: The interface used to manage accounts, sessions, and API keys.
  2. Backend API: Handles authentication, session management, and message requests.
  3. PostgreSQL: Stores persistent application data.
  4. WhatsApp Web integration: Handles the paired WhatsApp session and communication.

The basic message flow looks like this:

Your Application
       |
       | HTTP Request
       v
Puffx REST API
       |
       | Bearer Token Authentication
       v
Session Validation
       |
       v
WhatsApp Integration
       |
       v
WhatsApp Network
Enter fullscreen mode Exit fullscreen mode

This architecture allows another backend application to communicate with the gateway without directly managing the WhatsApp session itself.

4. Installing the Project with Docker

One of the main goals was to make local setup accessible to developers.

Requirements

Before starting, install:

  • Docker Desktop or Docker Engine.
  • Docker Compose.
  • Git.
  • A WhatsApp account that can use Linked Devices.

For Windows users, Docker Desktop should be installed and running.

Step 1: Clone the Repository

Open Windows CMD, PowerShell, or a terminal on Linux/macOS.

git clone https://github.com/puffxhost/puffx-whatsapp-gateway.git

cd puffx-whatsapp-gateway
Enter fullscreen mode Exit fullscreen mode

Step 2: Configure Environment Variables

Copy the example environment configuration.

On Windows CMD:

copy .env.example .env
Enter fullscreen mode Exit fullscreen mode

On Linux/macOS:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Open the .env file and configure the required secrets.

POSTGRES_PASSWORD=your_strong_database_password
SESSION_SECRET=your_random_session_secret
API_KEY_PEPPER=your_random_api_key_pepper
Enter fullscreen mode Exit fullscreen mode

Use unique, randomly generated values.

The session secret and API key pepper should be different from each other.

Important: Never commit your real .env file to a public repository.

Step 3: Start Docker Compose

Run:

docker compose up -d --build
Enter fullscreen mode Exit fullscreen mode

Docker Compose will build and start the gateway and database services.

Step 4: Open the Dashboard

After the services start, open:

http://127.0.0.1:3000
Enter fullscreen mode Exit fullscreen mode

You can also check the readiness endpoint:

http://127.0.0.1:3000/api/v1/ready
Enter fullscreen mode Exit fullscreen mode

The endpoint should report that the application is ready.

Step 5: Check Container Status

Run:

docker compose ps
Enter fullscreen mode Exit fullscreen mode

To view gateway logs:

docker compose logs -f gateway
Enter fullscreen mode Exit fullscreen mode

To restart the gateway:

docker compose restart gateway
Enter fullscreen mode Exit fullscreen mode

To stop the services while preserving data:

docker compose down
Enter fullscreen mode Exit fullscreen mode

Be careful with docker compose down -v. It removes the associated named volumes and can permanently delete the database and WhatsApp login data.

5. Connecting a WhatsApp Account

After opening the dashboard, follow these steps:

  1. Create an account in the dashboard.
  2. Select Add session.
  3. Give your WhatsApp session a name.
  4. Choose QR pairing or phone pairing code.
  5. For QR pairing, open WhatsApp on your phone.
  6. Navigate to Settings → Linked Devices → Link a Device.
  7. Scan the displayed QR code.
  8. Wait until the session status becomes connected.

Once connected, the session is available for API integration.

Security note: Never share QR codes, pairing codes, WhatsApp authentication files, or session backups with anyone.

6. Generating an API Key

After connecting your WhatsApp session:

  1. Open the connected session in the dashboard.
  2. Select Create API key.
  3. Copy the generated key immediately.
  4. Store it securely on your backend server.

The key is displayed only once.

If you lose it, revoke it and generate a new key.

The API key is associated with the session selected when it was created.

The session UUID is also required when making a message request. Use the dashboard's Copy ID option to obtain it.

7. Sending Your First WhatsApp Message Through the REST API

This is one of the most important parts of the project.

Once the gateway is running and a WhatsApp session is connected, another application can send a text message using an authenticated HTTP request.

API Endpoint 

POST /api/v1/messages/send
Enter fullscreen mode Exit fullscreen mode

Authentication 

Authorization: Bearer YOUR_API_KEY
Enter fullscreen mode Exit fullscreen mode

Request Body 

{
  "sessionId": "YOUR_SESSION_UUID",
  "to": "919876543210",
  "type": "text",
  "message": "Hello from Puffx WhatsApp Gateway!"
}
Enter fullscreen mode Exit fullscreen mode

Replace the example phone number with the recipient's number, including the country code and digits only.

Complete cURL Example 

curl -X POST "http://127.0.0.1:3000/api/v1/messages/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_UUID",
    "to": "919876543210",
    "type": "text",
    "message": "Hello from Puffx WhatsApp Gateway!"
  }'
Enter fullscreen mode Exit fullscreen mode

Replace the API key and session UUID with your actual values.

The API returns HTTP 202 when the provider accepts the message request.

An important distinction: HTTP 202 does not guarantee successful delivery or confirm that the recipient has read the message.

Delivery and read receipts are not currently implemented in this beta.

8. Integrating with Other Programming Languages

The gateway is designed to be accessed through HTTP, so a developer can integrate it with a backend written in different programming languages.

Examples and integration guidance are included in the repository's API documentation.

Potential client applications include:

  • Node.js applications.
  • PHP applications.
  • Python applications.
  • Internal business tools.
  • Backend automation systems.

For example, a PHP application could make an HTTP POST request to the gateway with its API key stored in a server-side environment variable.

Never expose an API key in frontend JavaScript, a public GitHub repository, or a mobile application's publicly accessible configuration.

For detailed examples, refer to:

https://github.com/puffxhost/puffx-whatsapp-gateway/blob/main/docs/api-reference.md

9. Can It Run on a VPS?

Yes. The application is designed for self-hosted deployment on a Linux VPS or cloud virtual machine.

A typical deployment needs:

  • Linux server.
  • Docker Engine.
  • Docker Compose.
  • PostgreSQL.
  • Persistent storage.
  • Domain name.
  • HTTPS reverse proxy.
  • Outbound WebSocket connectivity.

For public deployments, the gateway should run behind an HTTPS reverse proxy such as Nginx.

The repository includes deployment documentation and an example Nginx configuration.

A typical deployment workflow:

Domain
  |
  v
HTTPS Reverse Proxy
  |
  v
Puffx WhatsApp Gateway
  |
  +------ PostgreSQL
  |
  +------ Persistent WhatsApp Session Data
Enter fullscreen mode Exit fullscreen mode

The Docker Compose configuration binds the gateway to localhost on port 3000. The reverse proxy forwards HTTPS requests to that local service.

Ordinary shared hosting and static website hosting are generally unsuitable because the application requires continuously running services and persistent writable storage.

For additional information:

10. Security Considerations

Self-hosting gives developers control over their infrastructure, but it also means they are responsible for securing it.

Some important considerations:

Environment Secrets

Use strong, unique secrets for the database password, session secret, and API key pepper.

HTTPS

Never expose a public dashboard or API over unencrypted HTTP. Configure a valid TLS certificate.

API Key Protection

Keep API keys in backend environment variables or a secret manager.

Session Data

WhatsApp authentication state is stored on disk and is not encrypted by the application. Protect the Docker volume and its backups.

Database Backups

Back up PostgreSQL and the WhatsApp authentication volume. Treat both as sensitive data.

Access Restrictions

Do not expose internal database ports or unnecessary services to the public internet.

Read the full security documentation before deploying publicly:

https://github.com/puffxhost/puffx-whatsapp-gateway/blob/main/docs/security.md

11. Current Beta Status and Limitations

I want to be transparent about the current state of the project.

Puffx WhatsApp Gateway is an initial beta implementation.

Currently supported functionality:

  • WhatsApp QR pairing.
  • Phone pairing code.
  • Web dashboard.
  • Session management.
  • API key creation.
  • REST API authentication.
  • Text message sending.
  • Docker Compose deployment.

Current limitations:

  • Only text messages are supported.
  • Media messaging is not implemented.
  • Webhooks are not implemented.
  • Message queues are not implemented.
  • Delivery and read receipts are not implemented.
  • There is no separate admin console.
  • Real WhatsApp pairing and delivery behavior have not been verified by automated tests.

These limitations are important. The project should not be treated as a fully production-ready messaging platform.

12. Why I Started This Project

I enjoy exploring how software systems work beyond the frontend.

Working on this project has given me an opportunity to explore:

  • Backend architecture.
  • REST API design.
  • Database integration.
  • Docker-based deployment.
  • Authentication and secrets management.
  • Persistent application data.
  • VPS infrastructure.
  • WhatsApp Web connectivity.

I also wanted to build a practical tool that other developers could inspect, run, and experiment with.

This is an ongoing learning and development project under Puffx Host.

13. Open Source and Community Feedback

The project is publicly available on GitHub.

I welcome feedback from developers who work with:

  • Node.js.
  • TypeScript.
  • PostgreSQL.
  • Docker.
  • REST APIs.
  • Backend development.
  • Self-hosted infrastructure.

You can explore the source code, read the documentation, report issues, and contribute improvements.

GitHub Repository:

https://github.com/puffxhost/puffx-whatsapp-gateway

If you find a bug or have a technical suggestion, please open an issue in the GitHub repository.

Conclusion

Puffx WhatsApp Gateway is my attempt to build a self-hosted messaging gateway with a practical REST API and Docker-based deployment.

It is still in beta, and there is plenty of room for improvement.

Building this project has been a useful experience in backend engineering, infrastructure, and API development.

I would love to hear your feedback:

What would you improve in a self-hosted WhatsApp messaging gateway?

Would you focus on better session management, more API capabilities, monitoring, or deployment improvements?

Explore the project:

https://github.com/puffxhost/puffx-whatsapp-gateway

Built by Nitin Mehta | Puffx Host

Website: https://puffxhost.com

GitHub: https://github.com/puffxhost

Disclaimer

Puffx WhatsApp Gateway uses Baileys, an unofficial WhatsApp Web integration. It is not the official WhatsApp Business Platform and is not affiliated with, endorsed by, or sponsored by WhatsApp or Meta.

WhatsApp pairing and service availability may change. Users are responsible for complying with applicable WhatsApp terms, local laws, privacy requirements, and recipient-consent requirements. Use this project responsibly.

Top comments (0)