Deploy and Host WuzAPI on Railway

WuzAPI is an open-source, lightweight RESTful API service for WhatsApp built with Go and the whatsmeow library. It connects directly to WhatsApp Web WebSocket servers without requiring Puppeteer or headless Chrome, providing a fast and memory-efficient solution for sending messages, managing groups, and handling webhooks across multiple concurrent sessions using PostgreSQL for session data persistence.

About Hosting WuzAPI

Hosting WuzAPI on Railway involves running the Go-based application container connected to a managed PostgreSQL database service. During deployment, Railway automatically links the services and provisions environment variables for database authentication (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME, DB_PORT), admin security (WUZAPI_ADMIN_TOKEN), and encryption keys. Once deployed, WuzAPI automatically initializes its database schema in PostgreSQL, binds to port 8080, and maintains active WebSocket connections to WhatsApp servers while dispatching real-time event notifications to configured webhook endpoints.

Common Use Cases

Automated customer notifications, transactional alerts, and order verification messages.
Chatbot integration and customer support ticket automation via webhooks.
Multi-device WhatsApp session management for CRM systems and marketing platforms.

Dependencies for WuzAPI Hosting

WuzAPI Service: Application container (asternic/wuzapi:latest).
PostgreSQL Service: Railway PostgreSQL database with persistent volume mounted at /var/lib/postgresql/data.

Deployment Dependencies

Implementation Details

Below is the environment variable configuration for WuzAPI linked directly to the PostgreSQL service on Railway:

WUZAPI_ADMIN_TOKEN=${{secret(32)}}
WUZAPI_GLOBAL_ENCRYPTION_KEY=${{secret(32)}}
WUZAPI_GLOBAL_HMAC_KEY=${{secret(32)}}
PORT=8080
TZ=UTC
DB_USER=${{Postgres.PGUSER}}
DB_PASSWORD=${{Postgres.PGPASSWORD}}
DB_NAME=${{Postgres.PGDATABASE}}
DB_HOST=${{Postgres.PGHOST}}
DB_PORT=${{Postgres.PGPORT}}
DB_SSLMODE=disable

Architecture Comparison

WuzAPI (whatsmeow + Postgres) vs Puppeteer-Based Solutions

Feature / Parameter	WuzAPI + PostgreSQL	Puppeteer-Based Solutions (Web JS)
Connection Protocol	Native WhatsApp WebSocket	Headless Chrome Browser Automation
Session Persistence	Centralized PostgreSQL Database	File-system local auth folders
RAM Consumption	Very Low (~30MB - 100MB)	High (~500MB - 1.5GB per session)
CPU Usage	Minimal	High (Browser rendering processes)
Scalability	High (Handles multiple concurrent users)	Constrained by server memory limits
Data Integrity	ACID compliant session management	Vulnerable to local file corruption

How to Use WuzAPI (API Quickstart)

Once your WuzAPI and PostgreSQL stack is deployed on Railway, follow these steps to connect a WhatsApp account and start sending messages:

1. Create a New User (Admin Endpoint)

Send a POST request to the /admin/users endpoint using your admin token in the Authorization header:

curl -X POST "https://${RAILWAY_PUBLIC_DOMAIN}/admin/users" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyWhatsAppUser",
    "token": "USER_SECRET_TOKEN",
    "webhook": "[https://your-app.com/webhook](https://your-app.com/webhook)",
    "events": "Message,ReadReceipt"
  }'

2. Connect WhatsApp Session (QR Code)

Request a QR Code to pair your WhatsApp account:

curl -X GET "https://${RAILWAY_PUBLIC_DOMAIN}/session/qr" \
  -H "token: USER_SECRET_TOKEN"

Scan the returned QR code image or string using the WhatsApp app on your phone.

3. Send a Text Message

Once the session status shows Connected, send a text message (include the country code without a + sign):

curl -X POST "https://${RAILWAY_PUBLIC_DOMAIN}/chat/send/text" \
  -H "token: USER_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Phone": "1234567890",
    "Body": "Hello! This is an automated message sent from WuzAPI on Railway."
  }'

Why Deploy WuzAPI on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying WuzAPI on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.