WhatIsUp.dev
Get started

Quickstart

Goal: get from "no account" to "WhatsApp message sent" in five steps. We'll use curl here. The same calls work from any HTTP client.

You'll need a real WhatsApp account to scan the QR. Use a secondary number — Baileys opens a Web session on it just like the WhatsApp Web tab in your browser.

1 · Get an API key

Sign in to the dashboard at https://app.whatisup.dev (or your self-hosted origin), then Settings → API keys → Create. Copy the key — it's only shown once. Set it as an env var so the snippets below work as-is:

export WHATISUP_API_KEY=zpk_live_••••••••
export WHATISUP_API=https://api.whatisup.dev

2 · Create an instance

An instance is one logical WhatsApp connection. Each gets its own QR.

curl -sX POST "$WHATISUP_API/v1/instances" \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"primary"}'

You'll get back something like:

{
  "id": "inst_01J...",
  "name": "primary",
  "status": "pending",
  "created_at": "2026-05-01T12:34:56.000Z"
}

The status: "pending" means the gateway hasn't started a session yet. Take note of the id — you'll use it everywhere below as INSTANCE_ID.

3 · Get the QR code

Call the QR endpoint until it returns one. The instance starts a session on first QR fetch.

curl -s "$WHATISUP_API/v1/instances/inst_01J.../qr" \
  -H "Authorization: Bearer $WHATISUP_API_KEY"

The response carries a base64-encoded PNG and a wire-format string:

{
  "qr": "data:image/png;base64,iVBORw0KGgo...",
  "raw": "2@dPBI4Tg9Mc...,vlD4Pmkr...",
  "expires_at": "2026-05-01T12:35:25.000Z"
}

Open the data URL in your browser, or pipe .qr through a renderer. Scan it from WhatsApp → Settings → Linked devices → Link a device.

The dashboard UI does this for you in real time over SSE. If you'd rather not deal with QR plumbing yourself, point the dashboard at your gateway and click Pair.

4 · Wait for connected

Poll the instance until status flips to connected:

watch -n2 "curl -s '$WHATISUP_API/v1/instances/inst_01J...' \
  -H 'Authorization: Bearer $WHATISUP_API_KEY' | jq .status"

Or — much better — subscribe to Server-Sent Events and react to instance.connected:

curl -N "$WHATISUP_API/v1/events?token=$WHATISUP_API_KEY"

5 · Send your first message

curl -sX POST "$WHATISUP_API/v1/instances/inst_01J.../messages" \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","body":{"type":"text","text":"hello from WhatIsUp.dev"}}'

to is an MSISDN — country code + national number, no +. The response acknowledges receipt; the actual delivery state ships as a message.delivered webhook.

Where to next