Conventions

These conventions apply to every endpoint. Read them once and the rest of the API Reference becomes predictable. All requests go to https://api.wuts.com.br and carry an Authorization: Bearer <token> header — see Authentication.

WhatsApp JIDs

A JID (Jabber ID) is WhatsApp's internal address for a chat. WUTS returns JIDs in responses (for example the chat_jid field on a send result) and accepts them where a recipient is expected. The server you address determines the kind of chat:

The part before the @ is the address:

• User JIDs carry the full phone number in international format (country code followed by the subscriber number), digits only.
• Group JIDs carry a numeric group identifier, typically 15–25 digits. It is assigned by WhatsApp when the group is created — you cannot choose it.
• Newsletter JIDs carry a numeric channel identifier.

Phone numbers

A phone number is the country code plus the national number, digits only, with no leading +. For a Brazilian mobile that is 55 (country) + 11 (area) + the subscriber number, e.g. 5511999999999.

When a number is supplied as the number field, WUTS normalises it before use: spaces, dashes, parentheses, and a leading + are stripped, so +55 (11) 99999-9999 and 5511999999999 are equivalent. After normalisation the number must be between 10 and 15 digits and match international (E.164) shape.

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 WUTS" }'

The number field also accepts a full JID directly when you already have one:

• 5511999999999@s.whatsapp.net — a specific user
• 120363039000000000@g.us — a group

Targeting a specific device

A single tenant can pair several WhatsApp devices. Each paired device has a device ID — a UUID returned when the device is created and listed by GET /devices:

{
  "success": true,
  "data": {
    "devices": [
      {
        "device_id": "8f2b6a1e-0c34-4d8a-9b21-7e0f1a2b3c4d",
        "connected": true,
        "last_seen": "2026-06-15T18:42:10Z"
      }
    ],
    "count": 1
  }
}

When you have more than one device, tell WUTS which one to act on. The same device identifier is read from any of the following, checked in this order:

1. The X-Device-ID request header.
2. The device_id query parameter on the URL.

# Header form
curl -X POST "https://api.wuts.com.br/send/text" \
  -H "Authorization: Bearer <token>" \
  -H "X-Device-ID: 8f2b6a1e-0c34-4d8a-9b21-7e0f1a2b3c4d" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5511999999999", "text": "Sent from a specific device" }'

# Query-parameter form
curl "https://api.wuts.com.br/qr?device_id=8f2b6a1e-0c34-4d8a-9b21-7e0f1a2b3c4d" \
  -H "Authorization: Bearer <token>"

The device ID must be a valid UUID and must belong to your tenant; otherwise the request is rejected. The device-pairing endpoints (GET /qr and the QR status endpoint) require device_id so they target the right pairing session — see Connect a device.

Message IDs

Every message WUTS sends or receives is identified by a WhatsApp message ID — an uppercase hexadecimal string. On a successful send, it is returned as message_id:

{
  "success": true,
  "message_id": "3EB0F8A1B2C3D4E5F6",
  "timestamp": "2026-06-15T18:42:11Z",
  "status": "sent",
  "chat_jid": "5511999999999@s.whatsapp.net"
}

Use this ID to correlate webhook events (delivery and read receipts arrive under the same ID) and to reference a message you are replying to. When you reply with quoted, the quoted.key.id field must hold the original message's ID:

{
  "number": "5511999999999",
  "text": "Replying to your message",
  "quoted": {
    "key": { "id": "3EB0F8A1B2C3D4E5F6" },
    "message": { "conversation": "Original text" }
  }
}

Timestamps

Responses and webhook payloads return timestamps as RFC 3339 strings in UTC (for example 2026-06-15T18:42:11Z). This applies to fields such as the send timestamp, a device's last_seen, and a QR code's expires_at and generated_at.

A few inputs are expressed in whole seconds rather than timestamps. On POST /send/text these are durations, not wall-clock times:

• delay — seconds to wait before sending (0 to 3600).
• typingDuration — seconds to show the typing indicator (0 to 30).

curl -X POST https://api.wuts.com.br/send/text \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5511999999999", "text": "Arrives in 5s", "delay": 5 }'

Next steps

• Quickstart — pair a device and send your first message.
• Errors — error shapes and validation responses.
• Rate limits — throughput limits and headers.
• Webhooks — receive inbound messages and receipts.