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.
| Method | Path | Purpose |
|---|---|---|
| POST | /instances | Create: { "name", "channel"?: "WHATSAPP" or "TELEGRAM" or "MAX" }. Returns the instance and its one-time token (201) |
| GET | /instances | List |
| GET | /instances/{id} | Get one |
| GET | /instances/{id}/capabilities | What this instance's channel can and cannot do (see Channels) |
| POST | /instances/{id}/connect | Start the session (202). Telegram and MAX: send { "botToken": "..." } |
| GET | /instances/{id}/qr | Current QR as a PNG data URL |
| POST | /instances/{id}/pairing-code | Link by phone number instead of a QR scan: { "phone": "2348012345678" } |
| POST | /instances/{id}/reboot | Restart without losing the link |
| POST | /instances/{id}/disconnect | Stop, keep credentials |
| POST | /instances/{id}/logout | Unlink the number and wipe stored credentials |
| POST | /instances/{id}/token/rotate | New instance token |
| GET | /instances/{id}/state | Current status and phone number |
| GET | /instances/{id}/state/history | Connection history |
| GET | /instances/{id}/events | Activity log |
| DELETE | /instances/{id} | Delete (204) |
StatusesLive
| Status | Meaning |
|---|---|
| CREATED | No session yet |
| QR_PENDING | Waiting for the QR scan |
| CONNECTING | Opening the session |
| CONNECTED | Linked and ready |
| DISCONNECTED | Down; retries automatically if linked, otherwise press Connect |
| LOGGED_OUT | The device was unlinked; a new QR scan is needed |
| FAILED | WhatsApp 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.
{ "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
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' : '');
});