Skip to content
Get packs

Guide · Open source

How to use OpenWA: self-hosted WhatsApp API gateway

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenWA is a free, MIT-licensed WhatsApp API gateway that you run on your own server. It sits between your software and WhatsApp, offering an HTTP API and a web dashboard for managing sessions, webhooks and API keys. This guide covers what you need, how to get the code, and how to use the main features safely.

OpenWArmyndharis/OpenWA · ★ 16.5k · MIT

Quick start

  1. 1Clone the repository. Run git clone on the OpenWA repository to get the source, README and scripts.
  2. 2Install Docker. Make sure Docker is installed on the host that will run OpenWA, since the README describes a Docker-ready setup.
  3. 3Follow the README setup. Open the README in the cloned folder and follow its Docker setup instructions, because the exact commands are not reproduced here.
  4. 4Choose your database and storage. Set the database engine (SQLite or PostgreSQL) and media storage (Local or S3) through configuration.
  5. 5Open the dashboard and add a session. Log in to the web dashboard and create a WhatsApp session for the account you want to connect.
  6. 6Create scoped API keys. Create operator or viewer keys, limit them to specific sessions and, if needed, to specific chats.
  7. 7Set up backups. Back up the local media directory with scripts/backup.sh and back up any S3 bucket separately.

What OpenWA is and who it is for

OpenWA is a server, not a consumer chat app. You run it yourself and connect your own tools to it through its HTTP API. The project is aimed at developers who want to automate WhatsApp messages from their own systems and want to avoid paid hosted messaging services.

It also suits teams that need several WhatsApp sessions on one instance, and anyone who wants to connect WhatsApp to tools such as n8n or chatbots. If you are not a developer and want a ready-made chat app, OpenWA is not the right tool.

  • Good fit: developers automating WhatsApp from their own systems
  • Good fit: teams running several WhatsApp sessions on one instance
  • Not a fit: people who want a ready-made messenger
  • Not a fit: projects that need guaranteed official WhatsApp Business API compliance, since the README does not describe its connection method in detail

What you need before you install OpenWA

The main route in the README is Docker, which the project describes as Docker-ready. You also need Docker itself installed on the machine that will host OpenWA.

If you plan to build from source instead, the README asks for the Node.js LTS version shown in its badge. Check the README in the repository for the exact version before you start.

  • Docker (recommended route, described as Docker-ready in the README)
  • Node.js LTS, as named in the README badge, only if building from source
  • Git, to clone the repository

Get the OpenWA code

Clone the repository from GitHub. This gives you the full source, including the README and the scripts folder, which you will need for the setup and backup steps.

Read the README after cloning. It holds the current setup instructions for the Docker route and the configuration options.

git clone https://github.com/rmyndharis/OpenWA

Configure storage and the database

OpenWA is pluggable. You choose the database engine (SQLite or PostgreSQL) and the media storage backend (Local or S3) through configuration, not by changing application code. Redis is optional and handles the queue, rate limits and WebSocket fan-out.

Storage has a backup caveat. The scripts/backup.sh script archives only the local media directory, so an S3 bucket needs a backup of its own. Plan this before you rely on the instance.

  • Database: SQLite or PostgreSQL
  • Media storage: Local or S3
  • Redis: optional, for queue, rate limits and WebSocket fan-out
  • Back up the S3 bucket separately from scripts/backup.sh

Manage sessions, webhooks and API keys in the dashboard

OpenWA includes a web dashboard, built with React, for session, webhook and API key management. Use it to create and edit WhatsApp sessions, set up webhooks and create keys.

When you create or edit an operator or viewer key, you can tick the sessions it may use. If you select none, the key can access every session, including ones created later. Admin keys stay unscoped in the dashboard so they can keep managing other API keys.

  • Sessions: one instance can run multiple WhatsApp sessions concurrently
  • Webhooks: managed from the dashboard
  • API keys: admin, operator and viewer roles
  • Session-scoped keys: limit operator and viewer keys to chosen sessions

Limit API keys to specific chats

Session-scoped keys can be narrowed further to chosen chats, such as a few groups and contacts. This is useful when an AI agent or third-party integration uses a shared account and should see only its own conversations. Set allowedChats on POST /auth/api-keys or PUT /auth/api-keys/{id}, or use the dashboard, where you enter one chat id or phone number per line.

A chat-scoped key that makes a request outside its allowed sessions gets a 403 with the message "API key not authorized for this session". Chat-scoped operator keys cannot change group membership, read or reset invite links, or answer join requests.

  • No chats selected: the key reaches every chat on its sessions
  • One or more chats selected: the key reaches only those chats
  • Session and chat scopes are independent and can be combined
  • The WebSocket /events feed only delivers events for the key's chats

What people use it for

  • Automating WhatsApp messages from your own software
  • Running several WhatsApp sessions on one OpenWA instance
  • Connecting WhatsApp to n8n workflows through community nodes
  • Giving an AI agent a key that can only reach a few groups or contacts on a shared account
  • Adding chatbot or helpdesk integrations through the official plugins, such as Chatwoot and Typebot

Frequently asked questions

Is OpenWA free?

Yes. The README describes OpenWA as free and open source, with no licensing fees and no feature locks. The project is licensed under MIT.

What do I need to install OpenWA?

The README describes Docker-ready setup, so Docker is the main requirement. To build from source, you need the Node.js LTS version named in the README badge. Clone the repository with git clone https://github.com/rmyndharis/OpenWA.

Can I run several WhatsApp accounts on one OpenWA server?

Yes. The README says you can run multiple WhatsApp sessions concurrently on one instance. Each session can be managed from the dashboard and reached through the API.

Does OpenWA use the official WhatsApp Business API?

The README does not describe its connection method in detail, so it does not confirm official WhatsApp Business API compliance. If you need guaranteed compliance, check this with the project before you build on it.

Why does my API key return 403 "API key not authorized for this session"?

The key is limited to certain sessions, and the request names a session outside that list. Edit the key in the dashboard or through the API to add the session, or use a key that already covers it. Keys with no sessions selected can access every session.

What happens to my media if I back up OpenWA?

The scripts/backup.sh script archives only the local media directory. If you use S3 for storage, you need a separate backup of the bucket. The README calls this out, so plan it before you go live.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OpenWA suits developers and small teams who want a self-hosted WhatsApp API gateway with multi-session support, webhooks and fine-grained API keys for agents and integrations. It is not a good choice for non-developers who want a ready-made chat app, or for projects that must have guaranteed official WhatsApp Business API compliance.

Install options & downloads