API di WhatsApp per sviluppatori
WAIA Connect è un'API REST sopra l'API ufficiale di WhatsApp di Meta (Cloud API e Coexistence). Invii un POST /v1/messages con la tua chiave, noi lo mettiamo in coda e lo consegniamo a Meta a un ritmo sicuro, e i messaggi in arrivo ti arrivano su un webhook firmato. Fornitore di tecnologia verificato da Meta, con documentazione pubblica, OpenAPI ed esempi in quattro linguaggi.
Cosa risolve l'API al posto tuo
- Coda di uscita con tentativi ripetuti: l'invio viene confermato con
202e consegnato a Meta rispettando il ritmo di ogni numero. Un rifiuto di Meta resta nello stato del messaggio con un codice stabile. - Idempotenza: l'intestazione
Idempotency-Keyevita di inviare due volte lo stesso messaggio se riprovi. - Webhook firmati con HMAC su data e corpo (protezione contro i reinvii), più un'intestazione statica opzionale per strumenti no-code come n8n.
- Modelli: crearli, sincronizzarli e verificarli prima di inviarli a Meta, con il motivo e la correzione se qualcosa verrebbe rifiutato. Anche caroselli da 2 a 10 schede con foto o video, e sapere quale scheda e quale pulsante ha toccato ogni contatto (Modelli carosello).
- Media: inviare immagine, documento, audio e video tramite link, e scaricare i media in arrivo tramite un proxy.
- Letto e «sta scrivendo…»: segnare come letto un messaggio ricevuto (spunte blu) e mostrare «sta scrivendo…» mentre il tuo sistema prepara la risposta. Non consuma quota.
- Webhook tramite API (
/v1/webhooks): crearli, provarli e cambiarne il segreto con la tua chiave; e il link di attivazione può portare il webhook del numero, che nasce firmato con il segreto che hai già. - Com'è finita ogni attivazione:
onboarding.completedeonboarding.failed(con il motivo e il codice di Meta) arrivano al tuo webhook, o lo chiedi conGET /v1/onboarding-links?externalId=; e anche lo scollegamento passa per l'API (DELETE /v1/connections/{id}, con il tuoexternalId): il suo webhook si spegne da solo e riceviconnection.disconnected. - La cronologia della coesistenza: se la scegli al collegamento, ricevi fino a 6 mesi di chat via webhook (
history.batch) o la chiedi tramite l'API (GET /v1/connections/{id}/history). Non consuma quota. - Messaggi modificati ed eliminati:
message.editedporta la versione finale con l'id dell'originale (sui numeri solo Cloud API Meta segnala la modifica senza il testo:textAvailable: false) emessage.revoked, l'eliminazione. - Errori di Meta tradotti in un catalogo di codici stabili, con cosa fare in ogni caso.
- Stato di invio prima di una campagna:
GET /v1/connections/{id}/sending-statusdice se un numero può avviare conversazioni e perché no — il verdetto e i codici originali di Meta (141006,141010,131042), la verifica dell'azienda, il pagamento (senza dati della carta) e il limite giornaliero, condiviso da tutto il portafoglio; ciò che Meta non lascia leggere arrivaunknown. Ogni cambio arriva al tuo webhook comeconnection.sending_status_changed(Stato di invio). - Avvisi via email e Novità: ogni avviso dei tuoi numeri (scollegato, modello approvato, webhook che fallisce…) resta in
GET /v1/noticescon lo stesso testo dell'email; scegli tu se arriva anche via email, per tutto l'account (PATCH /v1/account/settings) o numero per numero.
Come si presenta
Un invio è una richiesta HTTP con la tua chiave API. Il numero si indica con l'identificativo di connessione (conn_…) che restituisce GET /v1/connections.
Esempi pronti da copiare in cURL, Node.js, PHP e Python: Inviare un messaggio. Tutto il contratto: OpenAPI.
Tutto quello che fa l'API, endpoint per endpoint
| Endpoint | Cosa fa |
|---|---|
POST /v1/messages | Inviare un messaggio: testo, modello, immagine, documento, audio o video. Confermato con 202 e spedito dalla coda. Limite per numero (Coesistenza 20/s, Cloud API 80/s) e per account. |
GET /v1/messages/{id} | Lo stato di un invio (in coda, inviato, consegnato, letto, fallito) e il motivo se è fallito. Mai il contenuto. |
POST /v1/messages/read | Segnare come letto un messaggio ricevuto (spunte blu) e, se vuoi, mostrare «sta scrivendo…». Non consuma quota. |
GET /v1/connections | I tuoi numeri collegati, con il loro identificativo conn_…, lo stato e la modalità (Cloud API o coesistenza). |
PATCH /v1/connections/{id} | Dare a un numero il tuo nome, il tuo identificativo esterno, note, un limite mensile di invii e se i suoi avvisi ti arrivano via email. |
DELETE /v1/connections/{id} | Scollegare un numero (per conn_… o il tuo identificativo esterno), come «Scollega» nel pannello: libera il posto nel tuo piano e non cancella niente in Meta. |
GET /v1/connections/{id}/history | Leggere, a pagine, la cronologia della coesistenza che hai scelto di ricevere al collegamento. Leggere non cancella nulla. |
POST /v1/connections/{id}/history/{batchId}/ack | Confermare di aver ricevuto un blocco della cronologia: WAIA Connect lo cancella subito. |
GET /v1/account/settings | Vedere se gli avvisi dei tuoi numeri e delle tue attivazioni ti arrivano via email (emailNotices). |
PATCH /v1/account/settings | Accendere o spegnere quegli avvisi via email per tutto l'account. Fatturazione, sicurezza e assistenza arrivano sempre. |
GET /v1/notices | Le Novità: ogni avviso dei tuoi numeri, partito via email o no, con lo stesso testo, nella tua lingua. Filtri per numero e per non letti. |
POST /v1/notices/{id}/read | Segnare un avviso come letto (anche nel pannello). |
POST /v1/notices/read-all | Segnare tutti gli avvisi come letti in una volta (anche nel pannello). |
GET /v1/usage | Quanto hai consumato nel periodo attuale, i tuoi numeri e l'extra stimato del ciclo. |
GET /v1/connections/{id}/sending-status | Questo numero può avviare conversazioni? canSend, i codici di Meta per entità, verifica, pagamento (senza carta) e limite giornaliero; ciò che Meta non lascia leggere, unknown. |
POST /v1/connections/{id}/sending-status/refresh | Rileggere lo stato di invio da Meta (sola lettura), una volta per numero ogni 10 min. |
GET /v1/connections/{id}/usage | I numeri di un numero: totali, serie giornaliera e salute. |
GET /v1/usage/by-connection | I totali di tutti i tuoi numeri in un periodo, a colpo d'occhio. |
GET /v1/accounts/oversubscription | Se stai vendendo più numeri di quelli inclusi nel tuo piano. |
GET /v1/branding | Il tuo marchio (nome, logo, colore) per la pagina di attivazione che vedono i tuoi clienti. |
PUT /v1/branding | Modificare il tuo marchio. |
POST /v1/onboarding-links | Creare un link di attivazione perché il tuo cliente colleghi il suo numero senza darti le credenziali di Meta. Con webhook, il numero nasce con il suo webhook. |
GET /v1/onboarding-links | I tuoi link di attivazione e com'è finito ciascuno (outcome). Con ?externalId=, quelli di un cliente. |
GET /v1/onboarding-links/{id} | Un link di attivazione con il suo esito: in attesa, completato (con il conn_… e il webhook) o fallito, con il motivo e il codice di Meta. |
PATCH /v1/onboarding-links/{id} | Cambiare la pagina introduttiva di un link attivo: intro: "minimal" (un pulsante e una riga) o full; null = quella dell'account. |
GET /v1/onboarding-cases | I casi di attivazione dei tuoi clienti (A-<n>): cosa hanno scritto, il codice di Meta e la diagnosi; ?status=open|acked|all. |
POST /v1/onboarding-cases/{id}/ack | Segnare un caso come gestito (idempotente). Una consegna del webhook non conta. |
DELETE /v1/onboarding-links/{id} | Annullare un link di attivazione. |
POST /v1/webhooks | Creare un webhook dell'account o di un numero (con conn_… o il tuo externalId). Il segreto di firma si mostra una sola volta. |
GET /v1/webhooks | I tuoi webhook, tutti o quelli di un numero (filtra per conn_… o externalId). Mai il segreto. |
GET /v1/webhooks/{id} | Un webhook e il suo stato: attivo, errori consecutivi, ultima risposta. |
PATCH /v1/webhooks/{id} | Cambiare l'URL o gli eventi, accenderlo o spegnerlo, o spostarlo su un altro numero. |
DELETE /v1/webhooks/{id} | Eliminare un webhook. |
POST /v1/webhooks/{id}/test | Inviargli subito un evento di prova firmato e vedere cosa ha risposto il tuo server. |
POST /v1/webhooks/{id}/rotate-secret | Cambiare il segreto di firma: il nuovo si mostra una volta e il vecchio smette di valere subito. |
GET /v1/media/{mediaId} | Scaricare l'immagine, l'audio o il documento che ti hanno inviato, senza esporre il token di Meta. |
GET /v1/templates | I tuoi modelli e il loro stato in Meta. |
POST /v1/templates | Creare un modello in Meta, verificato prima di inviarlo: con immagine, video, documento o posizione in alto, e pulsanti, oppure un carosello da 2 a 10 schede. |
POST /v1/templates/media | Caricare il file di esempio che Meta revisiona per un modello con immagine, video o documento. Restituisce l'handle per crearlo. |
POST /v1/templates/validate | Validare un modello senza inviare nulla a Meta: tutti gli errori insieme, ognuno con il suo campo, nella tua lingua. |
POST /v1/templates/preview | L'anteprima di un modello, in JSON o come nuvoletta di WhatsApp in HTML da mostrare al tuo cliente. |
GET /v1/templates/{id} | Un modello. |
PATCH /v1/templates/{id} | Modificare un modello dove Meta lo consente (approvato, rifiutato o in pausa), entro il suo limite. |
DELETE /v1/templates/{id} | Eliminare un modello. |
POST /v1/templates/sync | Portare da Meta i modelli e il loro stato attuale. |
POST /v1/templates/precheck | Verificare una bozza prima di inviarla: se Meta la rifiuterà, il motivo e come correggerla. |
POST /v1/templates/generate-examples | Proporre esempi per le variabili di un modello (Meta li chiede). |
GET /v1/templates/catalog | Il catalogo di modelli per settore, scritti per essere approvati da Meta. |
POST /v1/templates/seed | Caricare modelli del catalogo su un numero. |
GET /v1/templates/bulk-targets | A quali numeri si può applicare un modello in una volta. |
POST /v1/templates/bulk | Creare lo stesso modello su più numeri in una volta. |
GET /v1/templates/drafts | I modelli proposti dai tuoi clienti, da rivedere. |
GET /v1/templates/drafts/count | Quante proposte aspettano la revisione. |
POST /v1/templates/drafts/{id}/approve | Approvare una proposta: viene verificata e creata in Meta. |
PUT /v1/templates/drafts/{id} | Correggere una proposta prima di approvarla (l'originale resta). |
POST /v1/templates/drafts/{id}/reject | Rifiutare una proposta. |
POST /v1/templates/drafts/bulk-approve | Approvare più proposte insieme; se una fallisce, le altre vanno avanti. |
POST /v1/template-links | Creare un link perché il tuo cliente ti proponga modelli per il suo numero. |
GET /v1/template-links | I tuoi link per proporre modelli. |
DELETE /v1/template-links/{id} | Annullare un link per proporre modelli. |
Il dettaglio di ciascuno, con i suoi errori: OpenAPI.
Cosa non fa
- Non è una casella di chat per rispondere con un team: per quello c'è WAIA, il nostro prodotto chiavi in mano.
- Non conserva file: per inviare un tuo file, lo ospiti tu e invii il link.
- Non ti esonera dalle regole di Meta: la finestra di 24 ore, i modelli approvati e i limiti di invio continuano a valere. Te li spieghiamo in Prima di collegarti.
Quanto costa
Una tariffa fissa per numero collegato, senza limite di messaggi. Inizi con 14 giorni di prova; il piano più piccolo è Starter (US$ 12 al mese).
- Starter — US$ 12 al mese, 1 numero
- Studio — US$ 25 al mese, 5 numeri
- Agencia — US$ 45 al mese, 12 numeri
- Escala — US$ 99 al mese, 30 numeri, più US$ 3 per ogni numero extra
Meta addebita a parte i suoi messaggi, sulla tua carta; noi non aggiungiamo ricarichi. Il confronto con chi invece lo fa: WAIA Connect vs Twilio.
Domande frequenti
Usa l'API ufficiale di Meta?
Sì. WAIA Connect è un fornitore di tecnologia verificato da Meta e gestisce la Cloud API e la coesistenza (Coexistence). Non usa librerie non ufficiali che simulano WhatsApp Web.
Come ricevo i messaggi in arrivo?
Registri un URL https e ti arrivano via POST, firmati con HMAC. La guida alla verifica della firma ha esempi in quattro linguaggi.
Cosa succede se invio due volte la stessa richiesta?
Con la stessa Idempotency-Key il messaggio viene inviato una sola volta e la seconda risposta restituisce lo stesso identificativo.
C'è un limite mensile di messaggi?
In WAIA Connect no: il piano si paga per numero collegato. Meta invece ha i suoi limiti per avviare conversazioni con modelli, che dipendono dal tuo account Meta.
La documentazione è pensata per essere letta con un'IA?
Sì: ogni modulo è disponibile anche in Markdown, c'è un llms.txt nella radice del sito e il contratto completo è in OpenAPI.
Per continuare
Collega il tuo primo numero oggi
Fornitore di tecnologia verificato da Meta. Coexistence in un clic.
Inizia