Quasi tutto ciò che si chiede a un'API WhatsApp si riduce a quattro cose: inviare un messaggio, cercare un dato, modificare un record ed essere avvisati quando succede qualcosa. Spun le offre tutte e quattro su semplice HTTP, sullo stesso numero a cui il tuo team risponde nella casella, con una chiave che crei tu e limiti esattamente a ciò che serve all'integrazione.
Questa pagina è la versione pratica: quali sono gli endpoint, come funzionano autenticazione e ambiti, cosa succede se la tua linea WhatsApp è offline proprio nel momento in cui chiami, e dove si trova il contratto leggibile dalle macchine.
Chiavi, ambiti e quanto danno può fare una chiave trapelata
L'autenticazione usa un token Bearer. Crei una chiave nell'app, ti viene mostrata una sola volta, e ogni richiesta la porta in un'intestazione Authorization. Spun conserva solo un hash della chiave, quindi una chiave persa non si può recuperare, solo sostituire.
La parte su cui vale la pena spendere un minuto sono gli ambiti. Una chiave non è semplicemente “accesso all'account”: porta con sé un elenco di ambiti, e ogni endpoint verifica l'ambito specifico di cui ha bisogno. Una chiave con il solo read_contacts non può inviare un messaggio. Una chiave con il solo send_message non può elencare i tuoi contatti. Oltre agli ambiti, una chiave può avere una data di scadenza e un elenco di IP consentiti, così una chiave rilasciata a un server con un indirizzo fisso smette di funzionare nel momento in cui viene usata da qualsiasi altro posto.
- send_message copre l'invio di testo e media, e la lettura di un invio in coda.
- read_contacts, read_messages e read_labels sono il lato lettura, assegnabili separatamente.
- manage_contacts e manage_labels coprono creazione, aggiornamento ed etichettatura.
- check_phone indica se un numero è raggiungibile su WhatsApp.
- manage_webhooks crea, elenca ed elimina le sottoscrizioni webhook.
Richiesta
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'Risposta
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}Le chiavi create per il server MCP di Spun vengono rifiutate di proposito da questa API, anche quando sono chiavi valide. Le due interfacce hanno logiche di approvazione diverse, e una chiave rilasciata per una non diventa utilizzabile di nascosto sull'altra.
Vedi anche: Collegare un assistente IA invece di scrivere codice
Cosa coprono davvero gli endpoint dell'API WhatsApp
L'interfaccia è volutamente piccola e stabile, non una copia completa del prodotto. Esiste perché un sistema esterno possa fare ciò che i sistemi esterni hanno davvero bisogno di fare.
- Invio: un messaggio di testo, oppure media come URL o in base64, con una didascalia facoltativa.
- Contatti: creare un contatto, aggiornarlo ed elencare i contatti con paginazione a cursore.
- Etichette: elencare le etichette dello spazio di lavoro, applicarne una a una conversazione, rimuoverla.
- Messaggi: elencare i messaggi con paginazione a cursore, per sincronizzarli in un data warehouse o in un CRM.
- Verifica del numero: confermare che un numero è su WhatsApp prima di costruirci attorno una lista.
- Coda: consultare un invio messo in coda perché la linea era offline.
- Webhook: creare, elencare ed eliminare le sottoscrizioni.
Il contratto leggibile dalle macchine è pubblicato su /api/integrations/openapi.json e si legge senza chiave, così chi sviluppa un nodo n8n, chi costruisce un'app Zapier o il tuo generatore possono scaricare la specifica prima che a qualcuno vengano rilasciate le credenziali.
Cosa succede quando la linea WhatsApp è offline
È la parte che sorprende, quindi vale la pena essere espliciti. Spun invia tramite una sessione WhatsApp attiva, e una sessione attiva può essere giù proprio nel secondo in cui il tuo codice chiama. L'API non finge il contrario, e si comporta in modo diverso per il testo e per i media, di proposito.
Un invio di testo verso una linea offline restituisce 202 invece di un errore, con un id di coda. Il messaggio viene trattenuto e consegnato quando la linea si ricollega, e puoi interrogare l'endpoint della coda per sapere che fine ha fatto. Un invio di media verso una linea offline restituisce invece un conflitto, e non invia nulla. L'asimmetria è voluta: la coda smaltisce i messaggi come testo, quindi un'immagine in coda arriverebbe come una didascalia senza foto. Fallire in modo evidente è il risultato migliore, e a decidere è la tua logica di ripetizione.
Il limite di frequenza è di 60 richieste al minuto per chiave, con le intestazioni standard di rate limit su ogni risposta, così un client può rallentare in base alle intestazioni invece che per un 429 che non si aspettava.
Webhook: essere avvisati invece di interrogare
Interrogare a intervalli regolari un endpoint dei messaggi è la forma sbagliata per una conversazione, quindi l'API può fare il contrario e inviarti i dati. Registri un URL e gli eventi che ti interessano, e Spun gli invia un corpo JSON man mano che accadono.
Ogni consegna porta nelle intestazioni il nome dell'evento e un id di consegna univoco e, quando la sottoscrizione ha un segreto di firma, una firma HMAC-SHA256 del corpo esatto. Verifica la firma prima di fidarti del contenuto: è l'unica cosa che separa il tuo endpoint da chiunque venga a conoscenza dell'URL. Il segreto viene restituito una sola volta, quando crei la sottoscrizione, e mai più.
- Eventi dei messaggi, in entrata e in uscita.
- Contatto creato, aggiornato ed eliminato.
- Etichetta assegnata.
- Flusso di chat completato, invio in coda elaborato, lead qualificato.
- Conversazione chiusa, chiamata completata e fase della pipeline cambiata.
Vedi anche: Collegare Spun a Zapier e Make · Collegare Spun a n8n · Collegare un helpdesk: Zendesk, Zoho Desk, Freshdesk, HubSpot Service Hub, Jira
Limiti e avvertenze oneste
- Questa non è la WhatsApp Business API. È l'API di Spun davanti al tuo numero collegato, quindi non ci sono modelli di messaggio da far approvare né costi per messaggio, e allo stesso modo nessuna garanzia ufficiale di Meta.
- Sessanta richieste al minuto per chiave. Il lavoro in blocco spetta alle campagne, che regolano il proprio ritmo come si deve, non a un ciclo API serrato.
- L'elenco di endpoint qui sopra è oggi l'intera interfaccia. Ciò che non vi compare non è esposto, e non bisogna fare affidamento su nessun endpoint non documentato.
- Una chiave ha i suoi ambiti ma non è legata a un singolo utente. Trattala come una credenziale dello spazio di lavoro e sostituiscila quando se ne va qualcuno che vi aveva accesso.
- Scrivere a persone che non hanno mai dato il consenso porterà WhatsApp a limitare il numero, qualunque sia la strada seguita dal messaggio.
Vedi anche: Come Spun si collega a WhatsApp