Quick Start

This guide gets WaSphere running on a fresh server, connects a WhatsApp number, and sends a test message — in about 10 minutes.

Prerequisites

• A Linux server (Ubuntu 22.04+ or Debian 12+) with a public IP
• A domain name with an A record pointing to that IP
• Docker Engine 24+ and Docker Compose v2 installed
• Port 80 and 443 open in your firewall

Step 1 — Clone and configure

git clone https://github.com/wasphere/wasphere.git
cd wasphere
cp .env.example .env

Open .env in your editor and set the four required values:

# .env — minimum required settings
DOMAIN=wa.yourdomain.com          # Your domain — Traefik uses this for SSL
ADMIN_EMAIL=you@example.com       # Your email — used for Let's Encrypt + admin login
ADMIN_PASSWORD=changeme123!       # Strong password for the admin account
JWT_SECRET=replace_with_64_random_chars_minimum_32  # Run: openssl rand -hex 32

Generate a secure JWT secret in one command:

openssl rand -hex 32

Step 2 — Start the stack

docker compose up -d

Expected output (first run downloads images, takes 1–3 minutes):

[+] Running 6/6
 ✔ Network wasphere_default          Created
 ✔ Volume  wasphere_postgres_data     Created
 ✔ Volume  wasphere_sessions          Created
 ✔ Container wasphere-postgres-1     Started
 ✔ Container wasphere-wa-server-1    Started
 ✔ Container wasphere-dashboard-api-1 Started
 ✔ Container wasphere-dashboard-ui-1  Started

Step 3 — Verify all services are healthy

docker compose ps

All containers should show healthy or running within 30 seconds:

NAME                        STATUS          PORTS
wasphere-traefik-1          Up (healthy)    0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
wasphere-postgres-1         Up (healthy)    5432/tcp
wasphere-wa-server-1        Up (healthy)    3001/tcp
wasphere-dashboard-api-1    Up (healthy)    3000/tcp
wasphere-dashboard-ui-1     Up              13004/tcp

If any container is restarting, check its logs:

docker compose logs dashboard-api --tail=50

Step 4 — Open the dashboard

Navigate to https://wa.yourdomain.com (replace with your actual domain).

You should see the WaSphere login page. Sign in with the ADMIN_EMAIL and ADMIN_PASSWORD you set in .env.

Step 5 — Connect your first WhatsApp session

1. In the dashboard sidebar, click Sessions
2. Click New Session (top right)
3. Give the session a name — e.g. support or sales
4. A QR code appears on screen

On your phone:

• Open WhatsApp
• Tap Settings → Linked Devices → Link a Device
• Scan the QR code

The session status changes from connecting to connected within a few seconds. The QR code disappears and is replaced by your phone number.

Step 6 — Create an API key

1. Go to API Keys in the sidebar
2. Click New Key
3. Give it a name (e.g. test-key)
4. Enable the messages:send and sessions:read permissions
5. Click Create — copy the key immediately, it's only shown once

Your key looks like: wsp_live_abc123...

Step 7 — Send your first message

Replace SESSION_ID with the ID shown in your session list, and API_KEY with the key you just created.

curl -X POST https://wa.yourdomain.com/api/messages/send/text \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "447700900123",
    "text": "Hello from WaSphere!"
  }'

const response = await fetch('https://wa.yourdomain.com/api/messages/send/text', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sessionId: 'YOUR_SESSION_ID',
    to: '447700900123',
    text: 'Hello from WaSphere!',
  }),
});

const result = await response.json();
console.log(result);

import requests

response = requests.post(
    'https://wa.yourdomain.com/api/messages/send/text',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'sessionId': 'YOUR_SESSION_ID',
        'to': '447700900123',
        'text': 'Hello from WaSphere!',
    }
)

print(response.json())

The to field is the recipient's phone number in international format without the + — e.g. 447700900123 for a UK number, 12125550100 for a US number.

Successful response:

{
  "success": true,
  "messageId": "3EB0C767D097B7C7A5C1",
  "timestamp": "2026-05-25T10:30:00.000Z"
}

You'll see the message appear on the recipient's phone within seconds.

Troubleshooting

QR code doesn't appear

Check the WA Server logs:

docker compose logs wa-server --tail=100

If you see Authentication failure or Connection refused, verify that WA_TOKEN is identical in both .env sections (Dashboard API and WA Server). See Configuration.

Session goes to disconnected immediately after scanning

This usually means the phone number is already linked to another device via Linked Devices. On your phone, go to Settings → Linked Devices, remove any stale entries, and try scanning again.

Message send returns 401 Unauthorized

Your API key is missing or invalid. Double-check:

• The X-API-Key header is spelled correctly (capital X, capital A, capital K)
• The key has the messages:send permission
• The key is not scoped to a different session

Message send returns 404 Session not found

The sessionId in your request doesn't match any connected session. Fetch your session list to get the correct ID:

curl https://wa.yourdomain.com/api/sessions \
  -H "X-API-Key: YOUR_API_KEY"

SSL certificate error in browser

Traefik requests certificates on first visit. Wait 60 seconds and retry. If it persists, check:

docker compose logs traefik --tail=50

Look for unable to obtain ACME certificate — this usually means port 80 is blocked by your firewall or your domain's DNS hasn't propagated yet.

Next Steps

• Installation — detailed breakdown of every service and port
• Configuration — full environment variable reference
• Send Messages — all 14 message types with examples
• Webhooks — receive incoming messages in real time