Chiavi API e Client ID

Una chiave API permette al tuo software, e a strumenti come Zapier, n8n, Make e il plugin WordPress, di inviare messaggi WhatsApp dai numeri del tuo spazio di lavoro. Il tuo codice invia la chiave in un header Authorization: Bearer; le integrazioni chiedono due valori della pagina Chiavi API: il Client ID del tuo spazio di lavoro e una delle sue chiavi. La stessa pagina contiene il secret che firma i nostri webhook.

Chi può farlo: solo i Proprietari – tutti i Proprietari dello spazio di lavoro, non solo il suo creatore. I Proprietari vedono, creano, copiano ed eliminano tutte le chiavi dello spazio di lavoro, chiunque le abbia create. Editor e Analisti non vedono Chiavi API né nella barra laterale né nella pagina Impostazioni, e per loro un link a questa scheda apre Profilo (vedi Ruoli e autorizzazioni). Le chiavi funzionano con ogni piano, compresa la prova gratuita; ciò che invii con esse usa i messaggi dello spazio di lavoro.

Apri Chiavi API in Integrazioni nella barra laterale, oppure vai su Impostazioni → Chiavi API.

Ogni chiave mostra il nome, quando è stata creata (Creata il …), gli ultimi quattro caratteri della chiave (ad esempio •••• 7f3a), Copia chiave ed Elimina. La chiave più recente compare per prima.

Creare una chiave API#

1. Fai clic su Crea chiave

   In Impostazioni → Chiavi API, fai clic su Crea chiave in alto a destra del riquadro.

2. Dalle un nome (facoltativo)

   In Nome (facoltativo), scrivi l'app che la userà, ad esempio n8n o Sito web (fino a 50 caratteri). Se lo lasci vuoto, riceve un nome come "API Key 3", come indica il suggerimento sotto il campo.

3. Creala

   Fai clic su Crea chiave.

   

4. Copia la chiave

   La tua nuova chiave API mostra la chiave completa: "Copiala ora – non vedrai più la chiave completa. In seguito, “Copia chiave” la copia senza mostrarla." Fai clic su Copia ("Chiave copiata."), incolla la chiave nella tua app o integrazione, poi fai clic su Fatto.

   

• Fino a 10 chiavi per spazio di lavoro. Con 10 chiavi, Crea chiave è grigio e, se ci passi sopra con il puntatore, mostra "Puoi avere al massimo 10 chiavi API. Eliminane una per crearne un’altra."
• Le chiavi non scadono, e non si possono rinominare né disattivare: una chiave funziona finché non viene eliminata.
• Una chiave per app. Dai a ogni chiave il nome dell'app che la usa, così puoi sostituirne o eliminarne una senza bloccare le altre.
• Quale spazio di lavoro: una chiave appartiene allo spazio di lavoro selezionato quando l'hai creata, e ogni richiesta fatta con essa agisce su quello spazio di lavoro: i suoi numeri, i suoi messaggi e il suo piano. Per inviare da un altro spazio di lavoro, passa a quello e crea lì una chiave.

Cosa inserire nella tua app#

Dove vanno:

• Il tuo codice: in un header Authorization: Bearer YOUR_API_KEY in ogni richiesta (consigliato). La chiave indica il suo spazio di lavoro, quindi client_id si può omettere; se lo invii, deve comunque essere quello di questo spazio di lavoro. Vedi Inviare la chiave in un header, e Invia messaggio per un primo messaggio in cURL, Python, Node.js e PHP.
• Zapier: il Client ID e la chiave API, quando colleghi il tuo account.
• n8n: i campi Client ID, API Key e WhatsApp Client ID della credenziale WbizTool.
• Make, Pabbly Connect e altri strumenti: il corpo di una richiesta HTTP.
• WordPress: WbizTool → Settings, in API Configuration.

Google Sheets e Shopify si configurano nella dashboard e non richiedono una chiave.

Inviare la chiave in un header#

Ogni endpoint /api/v1/ accetta la chiave in un header Authorization, come farà la prossima API v2:

Authorization: Bearer YOUR_API_KEY

• client_id è facoltativo con l'header: è la chiave a decidere lo spazio di lavoro. Se invii anche client_id, deve essere il Client ID di questo spazio di lavoro, come prima.
• Invia la chiave in un solo punto. Con l'header, ometti api_key dal corpo, oppure invia la stessa chiave. Se sono diverse, viene usata la chiave dell'header quando è una chiave valida; se l'header contiene altro (per esempio il token di un altro strumento), viene usata la api_key del corpo.
• Le chiavi nel corpo funzionano ancora (client_id e api_key come JSON o campi di un modulo), quindi non cambia nulla per le app e le integrazioni che le inviano. L'header è migliore perché i corpi delle richieste finiscono in log, proxy e cronologie dei form builder più spesso degli header.
• Campi di un modulo, upload multipart e corpi JSON funzionano tutti con l'header.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Provare la chiave#

Chiama Verifica credenziali (POST /api/v1/me/) con la tua chiave e, se vuoi, un whatsapp_client. "status": 1 con "message": "Okay" significa che funzionano insieme. Non invia nulla e non usa messaggi, ma non controlla che ti restino messaggi né che il numero sia collegato.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Una chiave funzionante risponde {"status": 1, "message": "Okay", "name": "…"}.

Copiare di nuovo una chiave#

Fai clic su Copia chiave accanto alla chiave. La chiave completa va negli appunti senza essere mostrata nella pagina; vedi, ad esempio, "“Zapier” copiata." e il pulsante mostra Copiato ✓ per un attimo. Non ti serve una nuova chiave perché hai perso quella vecchia.

Per scoprire quale chiave usa un'app, confronta gli ultimi quattro caratteri della sua chiave con l'elenco.

Eliminare una chiave#

1. Fai clic su Elimina

   Fai clic su Elimina accanto alla chiave.

2. Conferma

   La finestra "Eliminare “…”?" avverte: "Tutto ciò che usa questa chiave smette subito di funzionare: Zap in Zapier, scenari di n8n e Make, il plugin WordPress e le tue chiamate API. Assegna prima un’altra chiave. L’operazione non può essere annullata." Fai clic su Elimina chiave. Vedi "“…” eliminata."

Da quel momento, le richieste con quella chiave ricevono Auth Error: invalid api key. Ciò che ha fatto prima resta: i messaggi che ha messo in coda partono comunque (annullali in Report se serve), e i promemoria che ha creato continuano a funzionare. Anche un trigger Incoming WhatsApp Message di Zapier configurato con essa continua a ricevere messaggi, perché il suo webhook è già sul numero: disattiva lo Zap in Zapier per fermarlo.

Sostituire una chiave#

Sostituisci una chiave quando potrebbe essere stata esposta, quando se ne va qualcuno che poteva copiarla, o di tanto in tanto. Non c'è un pulsante per ruotarla: crea prima la nuova chiave, così nel frattempo non si ferma nulla.

1. Crea una nuova chiave

   Crea una chiave e copiala. Con 10 chiavi, elimina prima una che non usi più.

2. Aggiorna le tue app

   Incolla la nuova chiave in ogni app e integrazione che usava quella vecchia, e verifica ciascuna, ad esempio con Verifica credenziali.

3. Elimina la vecchia chiave

   Eliminala. Smette subito di funzionare.

4. Controlla eventuali abusi (dopo una fuga)

   Cerca in Report i messaggi che non hai inviato e annulla quelli ancora in attesa. In Promemoria, elimina i promemoria che non hai creato, perché continuano a funzionare. Rimuovi i numeri che non hai aggiunto in Numeri WhatsApp. Con il componente aggiuntivo Unibox, cerca in Numeri inbox un badge Zapier o un webhook che non riconosci.

Proteggere le chiavi#

Una chiave non ha autorizzazioni proprie: chiunque ne abbia una può fare nel tuo spazio di lavoro tutto ciò che può fare l'API, qualunque sia il suo ruolo. Questo include inviare messaggi da uno qualsiasi dei suoi numeri (usando i suoi messaggi), leggere la cronologia dei messaggi, annullare i messaggi in attesa, gestire promemoria e file multimediali, verificare numeri e collegarne di nuovi.

• Tieni le chiavi sul tuo server, in una variabile d'ambiente o nell'archivio delle credenziali della tua integrazione. Non metterne mai una nel JavaScript di un sito web, in un'app mobile, in un foglio condiviso o in codice che pubblichi.
• Non inviare le chiavi via email o chat. Incollale direttamente nell'app che ne ha bisogno.
• Usa una chiave per app ed elimina le chiavi che non usi più.
• Sostituisci le chiavi di tanto in tanto, e subito se una potrebbe essere stata esposta.

Il Client ID da solo non è un segreto, ma tratta ogni chiave come una password.

Chiavi API v2#

API v2 ha chiavi proprie, che crei nella scheda Chiavi API v2 della stessa pagina. Sono più sicure delle chiavi descritte sopra:

• Mostrate una sola volta. La chiave completa (wbz_live_…) viene mostrata solo quando la crei; WbizTool ne conserva solo un'impronta. Se la perdi, revocala e creane una nuova.
• Solo ciò che serve. Spunta cosa può fare la chiave (inviare messaggi, leggere messaggi, promemoria, numeri, file multimediali, verifiche dei numeri), limitala ad alcuni dei tuoi numeri e, se vuoi, assegnale una data di scadenza.
• Chiavi di test. Una chiave di test (wbz_test_…) controlla ogni richiesta come una chiave live ma non invia nulla – per sviluppare e provare un'integrazione.
• Ultimo utilizzo. Per ogni chiave vedi quando e da dove è stata usata l'ultima volta. Revoca la blocca subito, insieme agli endpoint webhook configurati con essa.

Le chiavi descritte sopra funzionano solo con l'API v1, e le chiavi API v2 solo con la v2. Vedi Passare dalla v1 alla v2.

Firme dei webhook#

WbizTool firma ogni webhook che ti invia, così il tuo endpoint può verificare che una richiesta arrivi davvero da noi e non sia stata modificata lungo il percorso: il webhook di stato dei messaggi (inviato, non riuscito, annullato, scaduto), gli eventi di connessione dei numeri e i webhook dell'Inbox. I corpi restano gli stessi; si aggiungono due header:

La firma copre esattamente i byte che inviamo: i campi del modulo così come arrivano, l'intero corpo multipart quando è allegata l'immagine di un codice QR, e il JSON dei webhook dell'Inbox. I destinatari che ignorano gli header continuano a funzionare.

Ottenere il secret di firma#

In Impostazioni → Chiavi API, la scheda Secret di firma dei webhook sotto le tue chiavi mostra gli ultimi quattro caratteri del secret, per esempio •••• b70d. Ogni spazio di lavoro ha un solo secret per tutti i suoi webhook; viene creato con il primo webhook che ti inviamo.

1. Fai clic su Mostra nuovo secret

   Fai clic su Mostra nuovo secret (o su Crea secret se lo spazio di lavoro non ne ha ancora uno). La finestra "Sostituire il secret di firma?" avvisa che il secret attuale smette subito di funzionare. Fai clic su Genera nuovo secret.

2. Copialo

   Il tuo secret di firma dei webhook mostra il secret completo una sola volta. Fai clic su Copia e conservalo dove il tuo ricevitore di webhook può leggerlo, per esempio in una variabile d'ambiente. Non lo vedrai più: se lo perdi, generane uno nuovo.

Solo i Proprietari vedono la scheda. Un nuovo secret sostituisce subito quello vecchio, quindi aggiorna i tuoi ricevitori subito dopo: i webhook inviati nel frattempo non superano la tua verifica.

Verificare un webhook#

Calcola la firma dal corpo grezzo (prima che il tuo framework lo analizzi), confrontala con l'header in tempo costante e rifiuta i timestamp più vecchi di 5 minuti, così una vecchia richiesta non può essere riprodotta:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Rispondi 2xx quando la verifica riesce e 401 quando non riesce. I webhook dell'Inbox di un numero con un proprio secret del webhook contengono ancora anche X-Wbiztool-Signature; WbizTool-Signature usa lo stesso schema su ogni webhook.

Risoluzione dei problemi#

Pagine correlate#

• Primi passi con l'API
• Panoramica dell'API v2
• API Verifica credenziali
• API Invia messaggio
• App e integrazioni
• Impostazioni dello spazio di lavoro, membri del team e ruoli
• Collega il tuo numero WhatsApp