Quickstart

This quickstart takes you from zero to a delivered WhatsApp message in four steps: get your API token, create a device, pair it via QR code or pair code, and send your first text. Every request below is real cURL against https://api.wuts.com.br.

Step 1 — Get your API token

Your token is a UUID issued when your tenant is created. It is the credential for every call in this guide. You authenticate by passing it in the Authorization header as a Bearer token. The token does not expire automatically.

You can confirm the token works at any time by calling a protected endpoint. A quick sanity check is GET /status, which reports the connection state of your device:

curl -X GET "https://api.wuts.com.br/status" \
  -H "Authorization: Bearer <token>"

A valid token returns 200 OK. An invalid or missing token returns 401:

{
  "success": false,
  "error": "Invalid token"
}

For the full breakdown of token types, headers, and tenant isolation, see Authentication.

Step 2 — Create or pick a device

A device is a logical WhatsApp connection slot inside your tenant. You can register one explicitly with POST /devices, or let the pairing step create one for you on the fly.

curl -X POST "https://api.wuts.com.br/devices" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"WhatsApp Loja 01"}'

A successful response is 201 Created and returns the new device_id. Save it — you will need it to poll the QR status in Step 3:

{
  "success": true,
  "message": "Device created successfully",
  "data": {
    "device_id": "4d0add2c-fdd1-4ee0-9d33-6a8898ce30e3",
    "name": "WhatsApp Loja 01"
  }
}

To see the devices already attached to your token, call GET /devices, which returns a devices array (each with device_id, connected, and last_seen) plus a count.

Step 3 — Pair the device

Pairing links your WhatsApp account to the device. Pick one of two methods: scan a QR code, or type a short pair code into the WhatsApp app. The device must not already be connected.

Option A — QR code

Request a QR with GET /qr. The API connects in the background and returns both the raw QR string and a ready-to-render PNG data URL:

curl -X GET "https://api.wuts.com.br/qr" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "qr_code": "AAEBEiFo...",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "cached": false,
    "expires_at": "2025-03-02T13:55:42Z",
    "ttl": 30
  }
}

Render the image value and scan it from WhatsApp → Linked devices → Link a device. QR codes expire fast (around 30 seconds, see ttl), so display it immediately.

To check whether a generated QR is still valid for a device, poll GET /qr/status with the device_id from Step 2:

curl -X GET "https://api.wuts.com.br/qr/status?device_id=4d0add2c-fdd1-4ee0-9d33-6a8898ce30e3" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "exists": true,
    "generated_at": "2025-03-02T13:55:12Z"
  }
}

When the QR has expired or was never generated, exists is false. Request a fresh GET /qr and scan again.

Option B — Pair code

If you cannot scan a QR, request a numeric pair code with POST /paircode. The phone field is the full number in international format:

curl -X POST "https://api.wuts.com.br/paircode" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5511999999999"}'

{
  "success": true,
  "paircode": "RE1J-AH9M",
  "expires_in": 300,
  "device_id": "4d0add2c-fdd1-4ee0-9d33-6a8898ce30e3"
}

In WhatsApp, go to Linked devices → Link a device → Link with phone number instead, and enter the code. Allow 10–15 seconds for the session to sync.

Confirm the connection

After scanning the QR or entering the pair code, poll GET /status until the device is logged in:

curl -X GET "https://api.wuts.com.br/status" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "connected": true,
    "device_id": "4d0add2c-fdd1-4ee0-9d33-6a8898ce30e3",
    "is_logged_in": true,
    "jid": "5511999999999@s.whatsapp.net",
    "phone_number": "5511999999999",
    "status": "connected"
  }
}

Wait for is_logged_in: true before sending anything.

Step 4 — Send your first text message

With the device connected, send a message with POST /send/text. Only number and text are required. The number accepts an international phone or a group JID (120363039000000000@g.us).

curl -X POST "https://api.wuts.com.br/send/text" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from the WUTS API!"
  }'

A successful send returns 200 OK with the WhatsApp message_id, a sent status, and the resolved chat_jid:

{
  "success": true,
  "message_id": "3EB0F8A1B2C3D4E5F6",
  "timestamp": "2025-06-26T21:30:15Z",
  "status": "sent",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "metadata": {
    "device_id": "4d0add2c-fdd1-4ee0-9d33-6a8898ce30e3",
    "presence_sent": true,
    "processing_time_ms": 1247
  }
}

If the device is not connected, you get 503 with error_code: DEVICE_DISCONNECTED — return to Step 3. Text is limited to 4096 characters and supports native WhatsApp formatting: *bold*, _italic_, ~strikethrough~, and ```monospace```.

Next steps

• Receive messages and Webhooks to handle inbound events.
• Working with media to send images, audio, and documents.
• Group management to message and administer groups.
• Conventions, Errors, and Rate limits for API-wide behavior.