QuePasa

QuePasa is an open-source, free license software to exchange messages with WhatsApp Platform

Chat with us on Telegram: Group || Channel

Special thanks to Lukas Prais, who developed this logo.

QuePasa

A micro web-application to make web-based WhatsApp bots easy to write.

Current Version: 3.26.0518.1539

🚀 Quick Start

Docker Installation (Recommended)

The fastest way to get QuePasa running:

# Clone the repository
git clone https://github.com/nocodeleaks/quepasa.git
cd quepasa/docker

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start with Docker Compose
docker-compose up -d --build

📖 Complete Docker Setup Guide

📋 Table of Contents

Features
Installation
- Docker Setup
- Local Development
Integration Examples
API Documentation
Connection States
Configuration
Community & Support
Contributing

✨ Features

QuePasa provides a simple HTTP API to integrate WhatsApp messaging into your applications:

📱 QR Code Authentication - Easy WhatsApp Web connection setup
💾 Persistent Sessions - Account data and keys stored securely
🔗 HTTP API Endpoints for:
- Sending messages (text, media, documents)
- Receiving messages via webhooks
- Downloading attachments
- Managing contacts and groups
- Group administration
🔄 Webhook Support - Real-time message notifications
📊 Message History Sync - Configurable history retrieval
🎯 Advanced Features:
- Read receipts
- Message reactions
- Broadcast messages
- Call handling
- Presence management

🐳 Installation

Docker Installation (Recommended)

The easiest way to deploy QuePasa is using Docker with our pre-configured setup:

Quick Setup

git clone https://github.com/nocodeleaks/quepasa.git
cd quepasa/docker
cp .env.example .env
# Edit .env with your configurations
docker-compose up -d --build

Access QuePasa
- Web Interface: http://localhost:31000

📖 Detailed Docker Setup Guide - Complete installation instructions, configuration options, and troubleshooting.

Local Development

For development or custom installations:

Prerequisites

Go 1.20+ - Download here
PostgreSQL - Database for persistent storage
Git - For cloning the repository

Build from Source

# Clone repository
git clone https://github.com/nocodeleaks/quepasa.git
cd quepasa/src

# Install dependencies
go mod download

# Build application
go build -o quepasa main.go

# Run
./quepasa

API Documentation (Swagger)

QuePasa uses Swagger/OpenAPI for API documentation:

# Install swag CLI tool (one-time setup)
go install github.com/swaggo/swag/cmd/swag@latest

# Generate/update API documentation
cd src
swag init --output ./swagger

# Or use the provided script
# Windows: double-click generate-swagger.bat
# Or run: .\generate-swagger.bat

# Or use VS Code task: Ctrl+Shift+P → "Tasks: Run Task" → "Generate Swagger Docs"

The documentation will be available at http://localhost:PORT/swagger (with or without trailing slash) when the application is running.

🔗 Integration Examples

N8N Automation Workflows

Pre-built N8N workflows for common automation scenarios:

📁 N8N + Chatwoot Integration
- Customer service automation
- Ticket management integration
- Contact synchronization
🤖 TypeBot Integration
- Chatbot workflows
- Interactive conversations
- AI-powered responses

Chatwoot Help Desk

Complete setup for customer service integration:

📁 Chatwoot Configuration
- Help desk setup
- Nginx configuration
- Multi-agent support

API Integration Examples

# Connect and get QR code
# token could be empty, if empty a new token will be generated
# user is the user that will be manage this connection

curl --location 'localhost:31000/scan' \
  --header 'Accept: application/json' \
  --header 'X-QUEPASA-USER: :user' \
  --header 'X-QUEPASA-TOKEN: :token' \
  --data ''


# Send a message
curl --location 'localhost:31000/send' \
  --header 'Accept: application/json' \
  --header 'X-QUEPASA-TRACKID: :trackid' \
  --header 'X-QUEPASA-CHATID: :chatid' \
  --header 'Content-Type: application/json' \
  --header 'X-QUEPASA-TOKEN: :token' \
  --data '{
      
      "text": "Hello World ! \nHello World !"
  }'

# Set webhook
curl --location 'localhost:31000/webhook' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-QUEPASA-TOKEN: :token' \
  --data '{
      "url": "https://webhook.example.com/webhook/5465465241654",
      "forwardinternal": true,
      "trackid": "custom-track",
      "extra": {
        "clientId": "12345",
        "company": "myCompany",
        "enviroment": "production",
        "version": "1.0"
      }
  }'

📚 API Documentation

Core Endpoints

Messages: /send
Media: /send
Groups: /groups/
Webhooks: /webhook
RabbitMQ: /rabbitmq

API Versions

v4 (Latest) - Recommended for new integrations
v3 - Legacy support
v2 - Legacy support
v1 - Deprecated

📖 Complete API Documentation - Detailed endpoint documentation with examples.

🔌 Connection States

QuePasa exposes connection states such as Ready, Stopped, Disconnected, and Failed to represent the runtime status of each WhatsApp server.

📖 Connection States Guide - Detailed explanation of each state, health semantics, and which states are currently emitted by the runtime.

🔐 Authentication

QuePasa supports four authentication modes for secure API access:

Authentication Modes

JWT (User-Level Access) - Full access to all user sessions
- Use the Authorization: Bearer <jwt-token> header
- Recommended for multi-session applications
- Managed by SIGNING_SECRET environment variable
X-QUEPASA-TOKEN (Session-Scoped Access) - Access to a single session
- Use the X-QUEPASA-TOKEN: <token> header
- Recommended for single-session applications
- Automatically created when RELAXED_SESSIONS=true (default)
- Restricted to authenticated session only (cannot access other sessions)
X-QUEPASA-MASTERKEY - Administration and setup
- Use the X-QUEPASA-MASTERKEY: <masterkey> header
- Required for setup operations when RELAXED_SESSIONS=false
- Managed by MASTERKEY environment variable
Anonymous - Public endpoints only
- No authentication required for health checks, version info, etc.
- No headers needed

Quick Examples

# JWT authentication (user-level)
curl -H "Authorization: Bearer your-jwt-token" \
  http://localhost:31000/api/servers

# Session token authentication (single session)
curl -H "X-QUEPASA-TOKEN: your-session-token" \
  http://localhost:31000/api/servers

# Master key (administration)
curl -H "X-QUEPASA-MASTERKEY: your-masterkey" \
  http://localhost:31000/api/sessions

# Anonymous (public endpoints)
curl http://localhost:31000/health

📖 Complete Authentication Guide - Detailed documentation covering all authentication modes, use cases, security considerations, and advanced examples.

📖 Environment Discovery Guide - Learn how to query server capabilities with GET /api/system/environment — public preview vs. full configuration with master key.

⚙️ Configuration

Environment Variables Overview

Key configuration options (see docker/.env.example for complete list):

# Basic Configuration
DOMAIN=your-domain.com
MASTERKEY=your-secret-key
ACCOUNTSETUP=true  # Enable for first setup

# Database (Whatsmeow store)
DBDRIVER=sqlite3
DBDATABASE=whatsmeow
# For postgres/mysql also set DBHOST, DBPORT, DBUSER, DBPASSWORD and DBSSLMODE as needed

# Features
GROUPS=true
READRECEIPTS=true
CALLS=true
WEBSOCKETSSL=false
API_DEFAULT_VERSION=v4  # Unversioned /api/... alias points to v4 or v5

# Performance
CACHELENGTH=800
HISTORYSYNCDAYS=30

📖 Environment Variables Reference - Complete configuration documentation.

By default, the unversioned alias under your configured API prefix now follows API_DEFAULT_VERSION. Examples with the default prefix:

/api/v4/... → always legacy v4
/api/v5/... → always canonical v5
/api/... → whichever version is selected by API_DEFAULT_VERSION

The official Vue.js SPA is pinned to explicit v5 routes internally, so changing API_DEFAULT_VERSION is intended for external client migration compatibility.

Cache System Architecture

QuePasa 3.26+ features a centralized cache system with automatic fallback:

┌─────────────────────────────────────────┐
│  Centralized CacheService (Singleton)   │
├─────────────────────────────────────────┤
│                                         │
│  Messages Backend        Queue Backend  │
│  ├─ Memory (sync.Map)    ├─ Memory      │
│  ├─ Disk (JSON)          ├─ Disk        │
│  └─ Redis (go-redis)     └─ Redis       │
│                                         │
│  Auto-Fallback on Failure               │
│  (Enabled when CACHE_INIT_FALLBACK=true)│
└─────────────────────────────────────────┘

Usage Examples:

# Default: In-memory caching (no setup required)
CACHE_BACKEND=memory

# Persistent disk-based caching
CACHE_BACKEND=disk
CACHE_DISK_PATH=/var/cache/quepasa

# Distributed caching with Redis
CACHE_BACKEND=redis
REDIS_HOST=redis-server
REDIS_PORT=6379
REDIS_PASSWORD=your-password

# Mixed: Memory messages + Redis queue
CACHE_BACKEND=memory
RABBITMQ_CACHE_BACKEND=redis
REDIS_HOST=redis-server

Key Features:

✅ Single cache backend for entire system
✅ Pluggable backends (memory/disk/redis)
✅ Automatic fallback to memory on backend failure
✅ Separate queue backend configuration (optional)
✅ Environment-based configuration
✅ Zero external dependencies for default setup

🏗️ Architecture

QuePasa is built with:

Backend: Go with Whatsmeow library
Storage: internal QuePasa data uses local SQLite by default, while the Whatsmeow store is configurable through DB* variables (sqlite3, postgres, or mysql)
API: RESTful HTTP endpoints
Real-time: WebSocket support for live updates

🤝 Community & Support

Get Help

💬 Telegram Group: QuePasa API
📢 Telegram Channel: QuePasa Channel
🐛 Issues: GitHub Issues

Alternative Projects

Looking for Node.js? Check out whatsapp-web.js - A more complete Node.js WhatsApp API.

⚠️ Important Notices

Security: This application has not been security audited. Use at your own risk.
Unofficial: This is a third-party project, not affiliated with WhatsApp.
Terms: Ensure compliance with WhatsApp's Terms of Service.
Rate Limits: Respect WhatsApp's rate limiting to avoid account suspension.

🔄 Development & Contributing

Project Structure

├── src/                    # Go source code
├── docker/                 # Docker configuration
├── extra/                  # Integration examples
│   ├── chatwoot/          # Chatwoot integration
│   ├── n8n+chatwoot/      # N8N workflow examples
│   └── typebot/           # TypeBot integration
├── docs/                   # Documentation
└── helpers/               # Installation helpers

Building

# Development build
go build -o .dist/quepasa-dev src/main.go

# Production build
go build -ldflags="-s -w" -o .dist/quepasa-prod src/main.go

Environment Variables Reference

For detailed configuration options, see docker/.env.example and src/environment/README.md.

Core Configuration

Variable	Description	Default
`DOMAIN`	Your domain name for the service	`localhost`
`WEBAPIPORT`	HTTP server port	`31000`
`WEBSOCKETSSL`	Use SSL for WebSocket connections	`false`
`MASTERKEY`	Master key for administration	required
`ACCOUNTSETUP`	Enable account creation setup	`true`

WhatsApp Features

Variable	Description	Default
`GROUPS`	Enable group messaging	`true`
`BROADCASTS`	Enable broadcast messages	`false`
`READRECEIPTS`	Trigger webhooks for read receipts	`false`
`CALLS`	Accept incoming calls	`true`
`READUPDATE`	Mark chats as read when sending	`true`

Cache System (Centralized)

New architecture: Single CacheService with three backend options:

memory: In-process cache (default, no external dependencies)
disk: File-based storage (JSON format)
redis: Distributed cache (for multi-instance deployments)

Variable	Description	Default	Options
`CACHE_BACKEND`	Cache backend type	`memory`	`memory`, `disk`, `redis`
`CACHE_DISK_PATH`	Disk storage directory (for disk backend)	`./cache`	file path
`CACHE_INIT_FALLBACK`	Auto-fallback to memory on backend failure	`true`	`true`, `false`
`CACHELENGTH`	Max messages in cache	`800`	number
`CACHEDAYS`	Days to keep cached messages	`7`	number

Redis-specific variables (when CACHE_BACKEND=redis):

Variable	Description	Default
`REDIS_HOST`	Redis server hostname	`localhost`
`REDIS_PORT`	Redis server port	`6379`
`REDIS_USERNAME`	Redis authentication username	``
`REDIS_PASSWORD`	Redis authentication password	``
`REDIS_DATABASE`	Redis database number	`0`
`REDIS_KEY_PREFIX`	Prefix for all Redis keys	`quepasa:`
`REDIS_POOL_SIZE`	Connection pool size	`10`
`REDIS_MAX_RETRIES`	Max reconnection attempts	`3`
`REDIS_DIAL_TIMEOUT`	Connection timeout (seconds)	`5`
`REDIS_READ_TIMEOUT`	Read operation timeout (seconds)	`3`
`REDIS_WRITE_TIMEOUT`	Write operation timeout (seconds)	`3`

RabbitMQ Queue Backend (independent from message cache):

Variable	Description	Default
`RABBITMQ_CACHE_BACKEND`	Queue backend (disk/redis/memory)	inherits CACHE_BACKEND
`RABBITMQ_CACHE_DISK_PATH`	Queue disk storage path	inherits CACHE_DISK_PATH
`RABBITMQ_CACHE_QUEUE_KEY`	Redis queue namespace	`rabbitmq_retry`
`RABBITMQ_CACHELENGTH`	Max messages in retry queue (legacy)	`100000`

Performance & Sync

Variable	Description	Default
`HISTORYSYNCDAYS`	Days of history to sync on QR scan	`30`
`SYNOPSISLENGTH`	Length for message synopsis	`50`

Database Configuration

These DB* variables configure the Whatsmeow SQL store used during startup. They do not currently move the internal QuePasa application database, which still follows the local quepasa.sqlite / quepasa.db path in the current code.

Variable	Description	Default
`DBDRIVER`	SQL driver for the Whatsmeow store (`sqlite3`, `postgres`, `mysql`)	`sqlite3`
`DBHOST`	Host for `postgres` / `mysql`; ignored by `sqlite3`	empty
`DBPORT`	Port for `postgres` / `mysql`; ignored by `sqlite3`	empty
`DBDATABASE`	Database name for `postgres` / `mysql`, or sqlite base file path/name for the Whatsmeow store	runtime fallback: `whatsmeow` when empty with `sqlite3`
`DBUSER`	User for `postgres` / `mysql`; ignored by `sqlite3`	empty
`DBPASSWORD`	Password for `postgres` / `mysql`; ignored by `sqlite3`	empty
`DBSSLMODE`	PostgreSQL `sslmode`; usually unused by `sqlite3` / `mysql`	empty

Logging & Debug

Variable	Description	Options
`LOGLEVEL`	Application log level	`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`
`WHATSMEOW_LOGLEVEL`	WhatsApp library log level	`error`, `warn`, `info`, `debug`
`HTTPLOGS`	Log HTTP requests	`true`, `false`
`DEBUGREQUESTS`	Debug API requests	`true`, `false`

Media & Conversion

Variable	Description	Default
`CONVERT_PNG_TO_JPG`	Convert PNG to JPG format	`false`
`COMPATIBLE_MIME_AS_AUDIO`	Convert audio to OGG/PTT	`true`
`REMOVEDIGIT9`	Remove digit 9 from BR numbers	`false`

Regional Settings

Variable	Description	Default
`TZ`	Timezone	`America/Sao_Paulo`
`APP_TITLE`	App title suffix	`QuePasa`
`PRESENCE`	Default presence state	`unavailable`

📄 License

QuePasa is free software licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

What this means:

✅ Free to use for personal and commercial purposes
✅ Modify and distribute freely
✅ No warranty - use at your own risk
⚠️ Copyleft license - derivative works must also be AGPL-3.0
⚠️ Network use - if you run a modified version as a service, you must provide source code

🔗 References

WhatsApp Official - Official WhatsApp platform
Whatsmeow Library - Go library for WhatsApp Web API
Docker Documentation - Container platform documentation
PostgreSQL - Database system documentation

Made with ❤️ by the QuePasa Community

Name		Name	Last commit message	Last commit date
Latest commit History 801 Commits
.github		.github
.husky		.husky
docker		docker
docs		docs
extra		extra
helpers		helpers
src		src
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.lesshst		.lesshst
AGENTS.md		AGENTS.md
LICENSE.md		LICENSE.md
README.md		README.md
build-debug.bat		build-debug.bat
debug-launch.js		debug-launch.js
dlv-wrapper.bat		dlv-wrapper.bat
dlv.bat		dlv.bat
generate-swagger.bat		generate-swagger.bat
update-readme-version.bat		update-readme-version.bat
update-readme-version.go		update-readme-version.go
update-whatsmeow.ps1		update-whatsmeow.ps1

Folders and files

Latest commit

History

Repository files navigation

QuePasa

🚀 Quick Start

Docker Installation (Recommended)

Alternative Installation Methods

📋 Table of Contents

✨ Features

🐳 Installation

Docker Installation (Recommended)

Local Development

Prerequisites

Build from Source

API Documentation (Swagger)

🔗 Integration Examples

N8N Automation Workflows

Chatwoot Help Desk

API Integration Examples

📚 API Documentation

Core Endpoints

API Versions

🔌 Connection States

🔐 Authentication

Authentication Modes

Quick Examples

⚙️ Configuration

Environment Variables Overview

Cache System Architecture

🏗️ Architecture

🤝 Community & Support

Get Help

Alternative Projects

⚠️ Important Notices

🔄 Development & Contributing

Project Structure

Building

Environment Variables Reference

Core Configuration

WhatsApp Features

Cache System (Centralized)

Performance & Sync

Database Configuration

Logging & Debug

Media & Conversion

Regional Settings

📄 License

What this means:

🔗 References

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 114

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages