Documentazione

API REST per il middleware WhatsApp waboom.

Autenticazione

Ogni chiamata usa un Bearer token. La org API key (wbo_…, creabile da console → Impostazioni → API keys) opera a livello di organizzazione: crea istanze e usa tutte le istanze dell'org — è ciò che serve per fare tutto headless da un'app esterna. In alternativa, un token istanza per una singola istanza, o la ADMIN_API_KEY super-admin.

# header su ogni richiesta
Authorization: Bearer <token>

Bootstrap headless (org API key)

Con una org API key: crea l'istanza, mostra il QR, attendi la connessione, invia — senza pannello.

POST /v1/instances
Crea un'istanza nella tua org. Ritorna id e token. Org API key (admin+).
GET /v1/instances/:id/qr
QR di accoppiamento (data URL) da mostrare all'utente.
GET /v1/instances/:id/status
Poll finché connection: open.
curl -X POST https://api.waboom.it/v1/instances \
  -H "Authorization: Bearer $ORG_KEY" \
  -d '{"name":"cliente-acme"}'

Istanze

POST /instances
Crea un'istanza. Org API key (nella sua org) o admin key. Ritorna id e token.
GET /instances
Elenca le istanze. Org API key → solo la sua org; admin key → tutte.
DELETE /instances/:id
Rimuove un'istanza. Org API key (sua org) o admin key.

Connessione

GET /instances/:id/status
{ connection, me, hasCreds }. In console il campo health aggiunge last_connected_at e disconnected_since.
GET /instances/:id/qr
QR per accoppiare il numero (data URL immagine).
POST /instances/:id/pair
{ phone } (cifre internazionali) — accoppia con codice al telefono invece del QR: risposta { code } da inserire in WhatsApp > Dispositivi collegati > Collega con numero di telefono. Valido solo se non ancora accoppiato.

Salute & alert: se un'istanza resta disconnessa, waboom invia un'email di avviso all'organizzazione e la console mostra lo stato "Disconnesso da…". Le transizioni sono anche notificate via webhook instance.state.

Messaggi

GET /instances/:id/chats
Elenco chat con nomi risolti.
GET /instances/:id/chats/:jid/messages
Storia messaggi. Query limit, beforeTs.
GET /instances/:id/messages/:jid/:msgId/media
Media decifrato (binario).
POST /instances/:id/send/text
{ jid, text, quotedId? }
POST /instances/:id/send/media
{ jid, type, base64, caption? }
POST /instances/:id/send/template
{ templateId, jid, variables? } — invia un template dell'org interpolando {{variabile}} con i valori in variables. I template si creano in console (Template) o via API org.

Messaggi interattivi

POST /instances/:id/send/buttons
{ jid, text, footer?, buttons: [{ id, text }] } — bottoni a risposta rapida. La scelta arriva come evento message.received con replyId.
POST /instances/:id/send/list
{ jid, text, buttonText, title?, footer?, sections: [{ title?, rows: [{ id, title, description? }] }] } — menu a lista. La riga scelta arriva con replyId.

Nota: la resa dei messaggi interattivi dipende dalla versione del client WhatsApp del destinatario e non è garantita su tutti i dispositivi.

POST /instances/:id/check
{ numbers: ["39333…", …] } — verifica se i numeri sono su WhatsApp prima di inviare (max 100). Risposta: { results: [{ input, exists, jid }] }.

Opt-out & consenso

GET /instances/:id/optouts
Elenco dei contatti che hanno chiesto di non essere contattati.
POST /instances/:id/optouts
{ jid } — aggiunge un contatto alla lista opt-out.
DELETE /instances/:id/optouts/:jid
Rimuove un contatto dalla lista (re-consenso). jid URL-encoded.

Chi scrive STOP (o basta, cancellami, annulla, unsubscribe…) viene aggiunto in automatico. Gli invii verso un contatto in opt-out rispondono 403 recipient_opted_out e i broadcast lo saltano.

Webhook

PUT /instances/:id/webhook
{ url, events } — eventi: message.received, message.status, message.reaction, message.edited, message.deleted, group.update, instance.state, call.received, oppure ["*"]. Le risposte ai bottoni/liste arrivano in message.received con replyId. Gli ordini/carrello dal catalogo arrivano in message.received con type: "order"/"product" e il campo commerce. Puoi aggiungere headers (mappa) per header HTTP personalizzati su ogni consegna (es. token del ricevente); gli header riservati content-type/x-waboom-* non sono sovrascrivibili.

Risorse: OpenAPI · Postman collection · llms.txt.

MCP (agenti AI)

Server MCP ufficiale @waboom/mcp: collega waboom a Claude, Cursor e qualsiasi client MCP. Espone tool per inviare messaggi, reazioni, media, verificare numeri e leggere le chat. Config (env): WABOOM_TOKEN (org API key o instance token), WABOOM_INSTANCE_ID, WABOOM_BASE_URL (opzionale).

{
  "mcpServers": {
    "waboom": {
      "command": "npx",
      "args": ["-y", "@waboom/mcp"],
      "env": { "WABOOM_TOKEN": "wbo_...", "WABOOM_INSTANCE_ID": "..." }
    }
  }
}

Esempio

curl -X POST https://api.waboom.it/instances/$ID/send/text \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jid":"39333...@s.whatsapp.net","text":"Ciao da waboom"}'