Documentation

Instances & QR

Lifecycle, statuses, the QR code, bot tokens, phone pairing and live updates.

EndpointsLive

Paths are relative to https://api.sendjade.com/api/v1. Roles: create, log out, delete and rotate need Admin; connect, reboot, stop and the QR need Member. With an API key, instances:write covers the writes and instances:read the reads.

MethodPathPurpose
POST/instancesCreate: { "name", "channel"?: "WHATSAPP" or "TELEGRAM" or "MAX" }. Returns the instance and its one-time token (201)
GET/instancesList
GET/instances/{id}Get one
GET/instances/{id}/capabilitiesWhat this instance's channel can and cannot do (see Channels)
POST/instances/{id}/connectStart the session (202). Telegram and MAX: send { "botToken": "..." }
GET/instances/{id}/qrCurrent QR as a PNG data URL
POST/instances/{id}/pairing-codeLink by phone number instead of a QR scan: { "phone": "2348012345678" }
POST/instances/{id}/rebootRestart without losing the link
POST/instances/{id}/disconnectStop, keep credentials
POST/instances/{id}/logoutUnlink the number and wipe stored credentials
POST/instances/{id}/token/rotateNew instance token
GET/instances/{id}/stateCurrent status and phone number
GET/instances/{id}/state/historyConnection history
GET/instances/{id}/eventsActivity log
DELETE/instances/{id}Delete (204)

StatusesLive

StatusMeaning
CREATEDNo session yet
QR_PENDINGWaiting for the QR scan
CONNECTINGOpening the session
CONNECTEDLinked and ready
DISCONNECTEDDown; retries automatically if linked, otherwise press Connect
LOGGED_OUTThe device was unlinked; a new QR scan is needed
FAILEDWhatsApp refused or the session is invalid; needs attention

On Green-compatible routes getStateInstance maps these to authorized, starting, blocked and notAuthorized.

Telegram and MAX: bot token instead of a QR codeBeta

These channels have no QR code. Create the instance with "channel": "TELEGRAM" (or "MAX"), then POST /instances/{id}/connect with { "botToken": "..." }. The token is checked with the channel first (400 invalid_bot_token and nothing stored if it is rejected), then stored encrypted and never returned or logged. Later connects, reboots and server restarts reuse it; log out deletes it. The bot's @username shows as the account name (accountLabel). Full setup steps are on the Channels page.

The QR codeLive

After connect, poll GET /qr every few seconds, or listen on the realtime socket. The code refreshes automatically; if it is not scanned in time the instance returns to DISCONNECTED and you press Connect again. QR generation is verified against WhatsApp; the scan itself needs a phone.

GET /instances/{id}/qr
{ "data": { "status": "QR_PENDING", "qr": "data:image/png;base64,iVBOR...", "ageSeconds": 4 } }

Pairing code instead of a QRLive, phone check

Press Connect first, then request a code for the phone number and enter it in WhatsApp under Linked devices, Link with phone number. Green-style: POST getAuthorizationCode with { "phoneNumber": 2348012345678 }.

Live updates (Socket.IO)Live

Browser or mobile app
import { io } from 'socket.io-client';

const socket = io('https://api.sendjade.com', {
  withCredentials: true,        // browser: session cookie
  // auth: { token: '<bearer>' } // mobile / script mode
});
socket.on('instance.update', ({ instance, qr }) => {
  console.log(instance.status, qr ? 'new QR' : '');
});