Quickstart

1. Run the gateway

You need Bun (or Node 22), PostgreSQL and Chrome or Chromium.

cd wa-gateway
cp .env.example .env     # set DATABASE_URL, ADMIN_EMAILS, RESEND_API_KEY, RESEND_FROM_EMAIL
bun install
bun start

Open http://localhost:3000 and sign in with your email. A one-time code is emailed to you. Without the two Resend settings (outside production) the code is printed in the server log and shown on the sign-in page.

2. Create an app

In the dashboard choose New app, or call the Admin API:

curl -X POST http://localhost:3000/api/apps \
  -H "x-admin-key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support bot","webhookUrl":"https://example.com/hook"}'

The response contains apiKey and webhookSecret. They are shown only once, so store them now.

3. Pair a WhatsApp number

APP_KEY="wa_..."
curl -s http://localhost:3000/api/qr -H "x-api-key: $APP_KEY"

Scan the returned QR code (a PNG data URL) in WhatsApp under Linked devices. Poll GET /api/status until status is ready. See Pairing a number for the phone-number alternative.

4. Send a message

curl -X POST http://localhost:3000/api/messages \
  -H "x-api-key: $APP_KEY" -H "Content-Type: application/json" \
  -d '{"to":"15557654321","text":"Hello from my app!"}'

{ "messageId": "true_15557654321@c.us_3EB0...", "to": "15557654321@c.us", "status": "sent" }

5. Receive messages

Replies arrive as message.received events at your webhook URL. Read Webhooks to verify the signature, or poll GET /api/messages while developing. examples/echo-bot/ is a small bot that does exactly that.