Funzionalità

Un'API WhatsApp sul numero che usi già

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"
}
Invio di un messaggio. La chiave di idempotenza è facoltativa: se ripeti la stessa chiamata con la stessa chiave ricevi l'id del messaggio originale invece di un secondo invio.

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

Domande frequenti

Mi serve la WhatsApp Business API per usarla?

No. È l'API REST di Spun, che sta davanti al numero che hai collegato scansionando il QR code. Nessuna richiesta a Meta, nessuna coda di approvazione dei modelli e nessuna fatturazione per messaggio.

Come ottengo una chiave API?

Un manager dell'account ne crea una nell'app, sceglie i suoi ambiti e, se vuole, imposta una data di scadenza e un elenco di IP consentiti. La chiave in chiaro viene mostrata una sola volta, alla creazione; dopo, Spun ne conserva solo un hash.

Esiste una specifica OpenAPI?

Sì, pubblicata su /api/integrations/openapi.json e leggibile senza chiave, così gli strumenti possono generare un client prima ancora che esistano le credenziali.

Cosa succede se invio due volte la stessa richiesta?

Passa una chiave di idempotenza. Una chiamata ripetuta con la stessa chiave restituisce l'id del messaggio originale e segna la risposta come idempotente, invece di inviare un secondo messaggio. Senza chiave, due chiamate sono due messaggi.

Come verifico che un webhook arrivi davvero da Spun?

Dai alla sottoscrizione un segreto di firma e controlla l'intestazione della firma, che è un HMAC-SHA256 del corpo grezzo della richiesta nella forma sha256 seguito dal digest esadecimale. Confrontala con il tuo calcolo sugli stessi identici byte che hai ricevuto, prima di fare il parsing.

Costruisci sul numero a cui i tuoi clienti scrivono già

Chiavi con ambiti, un'interfaccia piccola e stabile, webhook che ti avvisano invece di costringerti a interrogare, e nessun contatore per messaggio.

Inizia gratis: 7 giorni con tutto incluso

Tutte le funzionalità di Spun