English | Português (Brasil)

WPPConnect Server

Run a REST API for WhatsApp sessions, messages and webhooks.

A project in the WPPConnect ecosystem, maintained by WPPConnect Team.

Getting started | Documentation | Contributing | Support WPPConnect

Overview

For integrators who want an HTTP service around the WPPConnect Node.js library. The Docker image also includes WPPConnect Manager for session and chat administration.

Features

• Session pairing, text/media messaging, contacts, groups and product operations.
• Session tokens, webhooks, authenticated Manager events and Swagger UI.
• Persistent Docker volumes for credentials, browser data, media and logs.

Getting started

Use Docker with Compose, or Node.js 22.22.2, Corepack/Yarn 4.14.1, Chromium and native dependencies for source development. From the repository root:

cp .env.example .env

In PowerShell use Copy-Item .env.example .env. Edit .env and set a private random SECRET_KEY before starting.

docker compose up -d
docker compose ps
curl -fsS http://localhost:21465/healthz

Open http://localhost:21465/manager/ and sign in with the configured SECRET_KEY to create/pair a session, or use the API at http://localhost:21465/api-docs. Session-restricted Manager access uses a session name and token. For source development: corepack enable, yarn install --immutable, yarn build, then yarn start.

Configuration

.env.example lists supported environment variables; src/config.ts contains advanced options. Process environment overrides the optional working-directory .env, then built-in defaults apply. Restart after changes. Set exact webhook/Chatwoot destinations in WEBHOOK_ALLOWED_URLS and CHATWOOT_ALLOWED_URLS. Session inventory and backups use POST with x-secret-key; legacy GET URLs containing secrets return 410. MANAGER_ENABLED=false disables the UI. Preserve the named volumes and pin WPP_SERVER_TAG for repeatable deployments.

Documentation

• Swagger reference
• Manager configuration, access and rollback
• HTTP request examples
• Postman collection
• Retained technical details and acknowledgments

WPPConnect ecosystem

Project	Purpose	When to use it
WPPConnect	Control WhatsApp Web from Node.js applications.	Embed automation in a Node.js application.
WPPConnect Manager	Manage WPPConnect Server sessions and conversations in a self-hosted web workspace.	Operate compatible Server sessions and chats through a UI.
WPPConnect Server CLI	Start WPPConnect Server from the wppserver command.	Launch the Node.js Server from a terminal.
WPPConnect Server Go	Run a browser-free WhatsApp HTTP API built with Go and whatsmeow.	Evaluate a Go HTTP API and documented migration coverage.

Support the project

WPPConnect is maintained by an open-source community. Your support helps fund maintenance, infrastructure, documentation, and the people working on the ecosystem.

If WPPConnect helps your project or business, consider making a one-time contribution or becoming a recurring supporter.

Support WPPConnect on Open Collective

Contributions are voluntary. See the official page for current financial information. You can also help with code, tests, documentation, translations and well-described issue reports.

Additional official beneficiaries in .github/FUNDING.yml: joaosouz4dev, manfe.

Contributing

Contributions of code, tests, examples, documentation and translations are welcome. For larger changes, discuss the approach in an issue first. Include the project/runtime versions, a minimal reproduction and sanitized logs when reporting a problem. Update both README.md and README.pt-BR.md in the same change when installation, configuration, features, examples, licensing or funding changes.

After installing the development dependencies, use the repository checks relevant to your change:

yarn build
yarn lint
yarn test

Account-dependent examples and tests require separate validation with an authorized test account. Never attach credentials or session files to an issue.

Chatwoot webhook authentication

POST /api/:session/chatwoot requires the token generated for that WPPConnect session. Configure Authorization: Bearer <session-token> on the webhook. If the webhook sender cannot set headers, the existing /api/<session>:<URL-safe-session-token>/chatwoot URL form is also supported. Generate the URL-safe token by replacing / with _ and + with - in the session token. Protect such URLs as credentials and redact them from proxy logs.

The Chatwoot api_access_token is an outbound Chatwoot credential and does not authorize this endpoint. Requests without a matching WPPConnect session token return 401 before accessing a client; authenticated requests for an unavailable session return 409. Only public outgoing message_created events are sent to WhatsApp.

Community and support

Use repository issues for reproducible bugs and feature proposals. For usage questions, join the community through the official channels:

• Discord
• Telegram
• YouTube

This project is independent and is not affiliated with or endorsed by WhatsApp or Meta. Follow applicable terms and obtain authorization for account and messaging operations.

License

Apache License 2.0 (Apache-2.0).

Copyright 2021 WPPConnect Team.

The original legal document and existing copyright notices are preserved. Third-party components retain their own terms.