Introduction
WhatsApp has become one of the most popular communication platforms for businesses, making it an excellent channel for sending notifications, customer support messages, order updates, OTPs, and marketing campaigns. While the official WhatsApp Business Platform is a great option for many use cases, developers often look for a self-hosted solution that offers greater flexibility during development and testing.
OpenWA is an open-source WhatsApp API gateway that allows you to create and manage WhatsApp sessions through REST APIs. It provides an intuitive web dashboard, built-in Swagger documentation, webhook support, multi-session management, and a developer-friendly interface for integrating WhatsApp into your applications.
In this tutorial, you'll learn how to set up OpenWA in a local development environment using Node.js. We'll walk through the complete process, from cloning the repository and configuring the application to generating an API key, creating a WhatsApp session, scanning the QR code, and sending your first WhatsApp message using the OpenWA REST APIs.
By the end of this guide, you'll have a fully functional OpenWA instance running locally and be ready to integrate WhatsApp messaging into your own applications.
What is OpenWA?
OpenWA is an open-source, self-hosted WhatsApp API gateway that enables developers to interact with WhatsApp using REST APIs. Built on Node.js and NestJS, it provides an easy way to create WhatsApp sessions, send and receive messages, manage contacts, and integrate WhatsApp functionality into web and mobile applications.
Unlike many hosted messaging services, OpenWA gives you full control over your deployment by allowing you to run the application on your own machine or server. It also includes a modern web dashboard, built-in Swagger API documentation, webhook support, and multi-session management, making it a powerful solution for development, testing, and custom integrations.
Whether you're building a customer support system, notification service, chatbot, or business automation tool, OpenWA provides a comprehensive set of APIs to help you integrate WhatsApp into your application.
Key Features of OpenWA
- Self-hosted WhatsApp API gateway
- REST APIs for WhatsApp messaging
- Interactive Swagger UI for API testing
- Web dashboard for session management
- API key authentication
- Multi-session support
- Webhook integration for real-time events
- Send text messages, images, documents, and other media
- Built with Node.js and NestJS
- Open-source and actively maintained
Prerequisites
Before you begin, make sure you have the following installed on your system:
- Node.js (Latest LTS version recommended)
- npm (Included with Node.js)
- Git (To clone the OpenWA repository)
- An active WhatsApp account (For creating and authenticating sessions)
- Visual Studio Code or any preferred code editor
You can verify the installations using the following commands:
node -v
npm -v
git --version
Clone the OpenWA Repository
First, clone the OpenWA repository from GitHub to your local machine using the following command:
git clone https://github.com/rmyndharis/OpenWA.git
Install Dependencies
After navigating into the OpenWA project directory, install all required Node.js dependencies using npm:
npm install
This command reads the project's package.json file and installs all dependencies required to run OpenWA locally.
Once the installation completes successfully, you're ready to configure the environment variables.
Configure Environment Variables
OpenWA provides an .env.example file containing the application's configuration options. Copy it to create your local .env file:
cp .env.example .env
On Windows, you can also simply copy .env.example and rename the copy to .env.
For local development, the default configuration is generally enough to get started. In particular, OpenWA uses SQLite by default and enables Swagger documentation. You can adjust settings such as the port, WhatsApp engine, database, storage, and API security in the .env file.
For example:
NODE_ENV=development
PORT=2785
DATABASE_TYPE=sqlite
STORAGE_TYPE=local
ENABLE_SWAGGER=true
Save the .env file after making any required changes. Do not commit your .env file to Git, especially if you add a custom API master key or other sensitive credentials.
Note: OpenWA's current configuration supports both whatsapp-web.js and baileys engines. For this local tutorial, we'll use the default configuration unless a specific engine needs to be selected.
Start OpenWA in Local Development
After configuring the environment variables, start OpenWA in local development mode by running:
npm run dev
Once OpenWA starts successfully, you can access the following URLs:
Dashboard: http://localhost:2886
API: http://localhost:2785/api
Swagger: http://localhost:2785/api/docs
When you run OpenWA for the first time, it will generate an API key. Make sure to save this API key, as you'll need it throughout this tutorial for accessing the OpenWA Dashboard and authenticating API requests.
We will use this API key in the upcoming steps while working with the Dashboard, Swagger UI, and OpenWA APIs.
Generate an API Key
When OpenWA is started for the first time, an API key is automatically generated and displayed in the terminal output.
Copy and save this API key securely, as it will be required to access the OpenWA Dashboard and authenticate your API requests.
You can also use this key in the upcoming Swagger UI examples to test OpenWA APIs.
Now that you have your API key, you can access the OpenWA Dashboard.
Access the OpenWA Dashboard
After starting OpenWA and obtaining your API key, open the following URL in your browser:
The OpenWA Dashboard allows you to manage and monitor your WhatsApp sessions through a user-friendly interface.
When prompted, enter the API key generated when you first started OpenWA. This key is required to access the Dashboard, so keep it available for the upcoming API and Swagger examples as well.
Once you successfully access the Dashboard, you can explore session management and other available OpenWA features.
Explore and Test APIs Using Swagger UI
OpenWA provides built-in Swagger UI, allowing you to explore and test available APIs directly from your browser.
Open the following URL:
http://localhost:2785/api/docs
Swagger displays all available OpenWA API endpoints along with their request parameters, request bodies, and response formats.
Before testing protected APIs, click the Authorize button and enter the API key generated when you first started OpenWA. Once authorized, you can test API endpoints directly from Swagger without using additional tools such as Postman.
This makes it easy to explore the APIs and follow along with the upcoming steps, where we'll create a WhatsApp session, start it, retrieve the QR code, and send messages using OpenWA's API.
Create a WhatsApp Session Using the API
Now that Swagger is configured with your API key, you can create your first WhatsApp session. In Swagger UI, expand the following endpoint:
POST /api/sessions
Click Try it out and enter the session details in the request body. For example:
{
"name": "my-bot",
"config": {
"autoReconnect": true
},
"proxyUrl": "string",
"proxyType": "http"
}
For a basic session, you can simply provide a unique session name and leave the other optional settings as required by your setup.
The autoReconnect option allows OpenWA to automatically reconnect the WhatsApp session if the connection is interrupted. The proxyUrl and proxyType options can be used when you want the session to connect through a proxy.
After entering the request details, click Execute. A successful request returns a 201 Session created response.
Example response:
{
"id": "032c06b6-2e78-4bce-83bd-49a8ace304cb",
"name": "my-bot",
"status": "created",
"phone": null,
"pushName": null,
"config": {
"autoReconnect": true
},
"proxyUrl": null,
"proxyType": null,
"connectedAt": null,
"lastActiveAt": null,
"createdAt": "2026-08-15T06:05:08.000Z",
"updatedAt": "2026-08-15T06:05:08.000Z"
}
Important: Save the id from the response (for example: 032c06b6-2e78-4bce-83bd-49a8ace304cb). This session ID is required for all next API calls, such as starting the session, fetching the QR code, and sending messages.
Make sure to also note the session name (e.g., my-bot) for easier identification in Swagger.
Start a WhatsApp Session Using the API
After creating the WhatsApp session, the next step is to start it and initialize the WhatsApp connection.
In Swagger UI, expand the following endpoint:
POST /api/sessions/{id}/start
Click Try it out and enter the session ID you received when creating the session.
For example:
032c06b6-2e78-4bce-83bd-49a8ace304cb
The request will be sent to an endpoint similar to:
POST /api/sessions/032c06b6-2e78-4bce-83bd-49a8ace304cb/start
After clicking Execute, OpenWA will start the session and initialize the WhatsApp connection.
A successful response will return the session details. Initially, the status may be:
{
"id": "032c06b6-2e78-4bce-83bd-49a8ace304cb",
"name": "my-bot2",
"status": "qr_ready"
}
The qr_ready status means the session has started successfully and is ready to generate a QR code for WhatsApp authentication.
Get the QR Code and Scan It with WhatsApp
Once the session status is qr_ready, you can retrieve the QR code and use it to authenticate your WhatsApp account.
In Swagger UI, expand the following endpoint:
GET /api/sessions/{id}/qr
Click Try it out, enter your Session ID, and click Execute.
The API will return a response containing the QR code as a Base64 image string:
{
"qrCode": "data:image/png;base64,..."
}
The qrCode value can be displayed as an image. Scan this QR code using your WhatsApp mobile application to connect your account with the OpenWA session.
On your phone, open WhatsApp → Settings → Linked Devices → Link a Device, then scan the generated QR code.
Once the QR code is scanned successfully, your WhatsApp account will be connected to the OpenWA session and ready to send messages.
Send Your First WhatsApp Message Using the API
Once your WhatsApp session is connected and active, you can send a text message using the following endpoint:
POST /api/sessions/{sessionId}/messages/send-text
In Swagger UI, click Try it out and enter your active Session ID.
Then provide the recipient's WhatsApp ID (chatId) and the message text:
{
"chatId": "919099033066@c.us",
"text": "Hello from OpenWA!"
}
Replace 919099033066 with the recipient's WhatsApp number, including the country code, followed by @c.us.
After entering the details, click Execute. If the message is sent successfully, OpenWA will return a response similar to:
{
"messageId": "true_628128455789@c.us_3EB1124556789",
"timestamp": 1765630800
}
Note: Make sure your WhatsApp session is active before sending a message. Otherwise, you may receive a 500 Internal Server Error or a session-related error.
Send and Image Using the API
Once your WhatsApp session is active, you can send an image using the following endpoint:
POST /api/sessions/{sessionId}/messages/send-image
In Swagger UI, enter your active Session ID and provide the recipient's WhatsApp ID and a publicly accessible image URL:
{
"chatId": "919099033066@c.us",
"url": "https://example.com/image.jpg"
}
Replace the chatId with the recipient's WhatsApp number, including the country code, followed by @c.us.
After entering the details, click Execute. If successful, OpenWA will return a response containing the messageId and timestamp.
Note: Make sure the image URL is publicly accessible and your WhatsApp session is active before sending the image.
Understanding Webhooks
Webhooks allow OpenWA to send real-time event notifications to your application. Instead of continuously checking the API for updates, your application can receive events automatically when something happens.
For example, webhooks can be used to receive notifications for:
- Incoming WhatsApp messages
- Message status updates
- Session status changes
- Connection and authentication events
To use webhooks, configure your application's webhook URL in the OpenWA session configuration. OpenWA will then send event data to that URL when the configured events occur.
Common Errors & Troubleshooting
While setting up and testing OpenWA, you may encounter some common issues.
1. API Key Authentication Error
Make sure you have entered the correct API key in Swagger using the Authorize button. The same API key is also required to access the OpenWA Dashboard and protected API endpoints.
2. Session Not Active
If you receive an error such as Session not active or invalid request, check whether the session has been started and the QR code has been scanned successfully. Your WhatsApp account must be connected before sending messages.
3. QR Code Not Working
If the QR code cannot be scanned, generate a new QR code using the session QR API and try again. QR codes may expire, so you may need to retrieve a fresh one.
4. Internal Server Error
A 500 Internal Server Error can occur when the WhatsApp session is not connected, the request data is invalid, or the provided image URL is inaccessible. Check the OpenWA terminal logs for more details.
5. Image Message Not Sent
Make sure the image URL is publicly accessible. A local file path or a URL that requires authentication may not work.
6. Port Already in Use
If OpenWA fails to start because a port is already in use, check the configured ports in your .env file and stop the application using those ports or change the configuration.
After resolving the issue, restart OpenWA and test the API again using Swagger UI.
Conclusion
OpenWA provides a convenient way to build and manage WhatsApp integrations using REST APIs. In this guide, we set up OpenWA in a local development environment, generated an API key, accessed the Dashboard and Swagger UI, and tested the APIs directly from the browser.
We also created and started a WhatsApp session, retrieved a QR code to authenticate the account, and sent text messages and images using the available API endpoints.
With OpenWA's API, Swagger documentation, session management, and webhook support, you can use it as a foundation for building WhatsApp-based applications such as chatbots, customer support systems, notification services, and business automation tools.
As you move toward production, make sure to properly secure your API keys, configure your environment, and review the latest OpenWA documentation and project updates before deploying your application.