Connettersi con la Meta Graph API
Ci sono due modi per inviare messaggi WhatsApp tramite WizMessage. L’API di WizMessage è quella a cui affidarsi se parti da zero — ti offre variabili di modello con nome, un’interfaccia di mappatura e un campo reference a cui associare i tuoi record.
Questa pagina documenta l’altra. Rispecchia la WhatsApp Cloud API di Meta così fedelmente che il codice già scritto per Meta funziona qui dopo aver modificato due cose: l’URL di base e il token. Stessi percorsi, stessi corpi di richiesta, stessi corpi di risposta, stesso envelope degli errori. Se hai già un’integrazione esistente, una libreria o uno sviluppatore che conosce già la Cloud API, questa è la strada più breve.
Non è soltanto una superficie di invio. Oltre alla messaggistica include gli endpoint di gestione dell’account — creazione ed eliminazione dei modelli, lettura e riscrittura del profilo aziendale, codici QR, impostazioni di commercio, elenco dei numeri bloccati, impostazioni del telefono e flussi — tutti sui percorsi proprietari di Meta. Gestione dell’account è il catalogo, e Cosa non è disponibile qui è l’altra metà, altrettanto importante.
Entrambe le superfici utilizzano le stesse chiavi API, gli stessi permessi e gli stessi limiti di frequenza. Nulla è deprecato — scegli per ciascuna integrazione e puoi usarle entrambe contemporaneamente.
Quale fa al caso tuo
Le basi
URL di base e la versione nel percorso
https://wizmessage.com/v26.0/{phone-number-id}/messages
Il segmento della versione è reale e obbligatorio, ma il suo valore non cambia nulla. Lo verifichiamo come v{major}.{minor} e poi lo ignoriamo: la piattaforma decide con quale versione di Graph comunicare a monte.
Due conseguenze utili da sapere:
- Fissare una vecchia versione continua a funzionare. Quando Meta ritira la versione impostata nel codice, le chiamate qui continuano a funzionare. Nulla da pianificare.
v26da solo viene rifiutato. Il numero minor non è facoltativo.v26.0va bene,v26è un 404.
L’{phone-number-id} deve essere il numero WhatsApp associato alla chiave API in uso. Qualsiasi altra cosa viene rifiutata — vedi Quando un ID non è tuo.
Autenticazione
Invia la tua chiave API come bearer token, esattamente come invieresti un token di accesso a Meta.
| Intestazione | Valore |
|---|---|
Authorization | Bearer pk_live_… — la tua chiave API completa, non il prefisso mostrato nella dashboard. |
Anche X-API-Key è accettato qui, quindi una chiave che già funziona con l’API WizMessage non richiede alcuna modifica dell’intestazione. Bearer è la forma da preferire: è ciò che invia un SDK di Meta non modificato, che è proprio lo scopo di questa interfaccia.
Nota: «Richiedi firma» deve essere disattivata sulla chiave. Non si tratta di una preferenza in questo caso. Una chiave con questa opzione abilitata non può salvare un webhook di Meta Graph — la dashboard rifiuta con «L’applicazione della richiesta firmata non è compatibile con il formato Graph — disabilitala prima su questa chiave» — e ogni chiamata non firmata effettuata su questa interfaccia viene rifiutata come
code 190con un401. Un client Cloud API pronto all’uso non può produrre la nostra firma della richiesta, quindi le due cose si escludono a vicenda per progettazione.
Il tuo abbonamento
Il modulo API richiede un abbonamento attivo a Wiz Bot o Wiz Pro. Questo vale per entrambe le interfacce — l’API WizMessage e questa — e viene verificato a ogni chiamata, non solo quando la chiave viene creata.
Se l’abbonamento scade, l’API non si blocca all’istante. La prima chiamata dopo la scadenza avvia una finestra di sette giorni e viene lasciata passare, e ogni risposta durante tale finestra include un’intestazione:
| Intestazione | Valore |
|---|---|
X-Subscription-Warning | Subscription inactive. API access ends in 5 day(s). |
Al termine della finestra, le chiamate vengono rifiutate con il code 10 di Graph e un 403:
{
"error": {
"message": "(#10) Access denied. The API module requires an active Wiz Bot or Wiz Pro subscription. Renew at /subscriptions to restore access.",
"type": "OAuthException",
"code": 10,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
Tre dettagli che determinano se te ne accorgi in tempo:
- Il conteggio parte dalla prima chiamata, non dalla data di fatturazione. Una chiave che rimane inattiva per due settimane dopo una scadenza riceve comunque i suoi sette giorni completi, a partire dal momento della chiamata successiva.
- La finestra è per singola chiave API, non per account. Ogni chiave avvia il proprio conteggio a partire dalla sua prima chiamata, quindi una chiave usata per i test e una chiave attiva in produzione scadranno in giorni diversi. Controlla l’intestazione sulla chiave che conta.
- Il rifiuto arriva senza alcun preavviso sulla richiesta che lo attiva.
X-Subscription-Warningè l’unico preavviso disponibile — registralo nei log, altrimenti la prima cosa che scoprirai sarà un403.
Nota: il rinnovo richiede alcuni minuti per avere effetto, non secondi. La verifica dei diritti di accesso viene memorizzata nella cache per cinque minuti e lo stato dell’abbonamento sottostante per altri cinque, quindi un rinnovo effettuato mentre un’integrazione sta fallendo non si sbloccherà al tentativo immediatamente successivo. Attendi qualche minuto prima di concludere che non abbia funzionato.
Inviare un messaggio
POST /{version}/{phone-number-id}/messages, con il corpo previsto da Meta. Non effettuiamo alcuna convalida oltre a verificare che si tratti di un messaggio WhatsApp — Meta è l’autorità su come si presenta un messaggio valido, e i suoi errori sono migliori di qualsiasi cosa potremmo inventare noi.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "text",
"text": { "preview_url": false, "body": "Your order has shipped." }
}
Nota: qui
toaccetta sole cifre —919876543210, senza+. Questo è il formato di Meta, ed è l’errore più comune quando ci si sposta tra le due interfacce: l’API WizMessage richiede+E.164e rifiuta qualsiasi altra cosa, mentre questa passa il valore direttamente a Meta. L’unica eccezione èPOST /messages/contacts, che accetta entrambi i formati proprio per consentire la migrazione intatta di un corpo Graph.
Anche l’invio di un modello segue la struttura di Meta — componenti posizionali, non variabili con nome. Non esiste un livello di mappatura su questa interfaccia, ed è questo il compromesso che accetti in cambio della compatibilità.
{
"messaging_product": "whatsapp",
"to": "919876543210",
"type": "template",
"template": {
"name": "payment_failed_alert",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Priya Sharma" },
{ "type": "text", "text": "12 Aug 2026" },
{ "type": "text", "text": "Wiz Pro" }
]
}
]
}
}
Inviare una scheda di contatto
type: "contacts" è una vCard — un nome e qualsiasi altra cosa tu voglia allegare. Ha sempre funzionato su questa interfaccia e continua a farlo, con il corpo di Meta invariato.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919876543210",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "Priya Sharma",
"first_name": "Priya",
"last_name": "Sharma"
},
"phones": [
{ "phone": "+911122334455", "type": "WORK", "wa_id": "911122334455" }
],
"emails": [
{ "email": "[email protected]", "type": "WORK" }
],
"org": { "company": "Acme Retail", "department": "Support", "title": "Account Manager" }
}
]
}
name.formatted_name è l’unico campo richiesto da WhatsApp. phones[].wa_id è comunque quello che vale la pena aggiungere: con esso la scheda include un pulsante Messaggio che apre una chat con quella persona; senza di esso la scheda può solo essere salvata.
Questo stesso identico corpo può essere inviato anche a POST /messages/contacts sull’API WizMessage — chiavi dell’envelope, to con sole cifre e tutto il resto. È l’unico endpoint su quell’interfaccia che accetta questo formato, ed esiste perché i due vantaggi che questo percorso non può offrirti sono preziosi: un invio qui non viene registrato sotto un message_id, quindi non c’è alcuno stato da consultare né alcun webhook message.sent da associare, e il corpo viene a malapena controllato prima di raggiungere Meta. Cambiare l’URL è l’intera migrazione.
Nota: l’invio di più schede in un unico messaggio corrisponde all’array
contactsdi Meta, e Meta ne accetta fino a 257. L’endpoint di WizMessage fissa il limite a dieci — quindi un invio di schede multiple che funziona qui è uno dei pochi corpi che non potrà essere trasferito senza modifiche.
Contrassegnare un messaggio come letto
Le conferme di lettura e gli indicatori di digitazione inviano richieste allo stesso endpoint, con un corpo che non include né to né type. Il metodo markAsRead() di ogni SDK per la Cloud API fa affidamento su questo funzionamento, pertanto è supportato esattamente come specificato da Meta.
POST https://wizmessage.com/v26.0/106540352242922/messages
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…"
}
La risposta è {"success": true} — non l’envelope di invio riportato sotto. Gestisci i rami logici in base alla chiamata effettuata, invece di tentare di leggere messages[0].id da ogni risposta.
Cosa viene restituito
La risposta di Meta, senza modifiche:
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…" }]
}
Quel wamid è il tuo unico riferimento per il messaggio. Questa interfaccia non ha deliberatamente alcun campo reference e nessun endpoint per la ricerca dello stato — entrambi sono aggiunte di WizMessage che l’API di Meta non possiede, quindi includerli romperebbe la compatibilità per cui questa interfaccia esiste.
Per seguire l’esito di un messaggio, confronta il wamid con gli stati di consegna in arrivo sul tuo webhook. Se preferisci disporre di un campo personalizzato su cui basarti, è proprio a questo che serve il campo reference dell’API WizMessage.
Errori
Gli errori vengono restituiti nella busta di Meta, mai nella nostra. L’origine dell’errore determina quanta parte di esso sia nostra.
Errori generati da noi
code | HTTP | Quando |
|---|---|---|
190 | 401 | Chiave mancante, sconosciuta, revocata, sospesa o scaduta — oppure una chiamata senza firma a una chiave che richiede le firme. Generato anche quando l’account WhatsApp stesso ha perso la connessione con Meta; vedi la nota in basso. |
10 | 403 | Alla chiave manca il permesso richiesto da questa chiamata (vedi Permessi), oppure l’abbonamento dell’account è scaduto oltre la finestra di tolleranza. |
4 | 429 | La quota al minuto o giornaliera della chiave è esaurita. |
100 | 400 | Richiesta non valida, un id nel percorso che non ti appartiene, oppure un endpoint non gestito da questa superficie. |
2 | 500 | Si è verificato un errore dal nostro lato. Riprova. |
Nota: Due problemi diversi restituiscono
190, e richiedono soluzioni opposte. Se il messaggio menziona la chiave, ruota o reinserisci la chiave. Se riporta "the connection to this WhatsApp Business Account needs to be renewed", la chiave è a posto e l’account ha perso il collegamento con Meta — riconnettilo dalla dashboard. Ruotare una chiave funzionante in risposta a questo secondo caso fa sprecare un pomeriggio e non cambia nulla.
Errori generati da Meta
Inoltrati esattamente come ricevuti, con lo status HTTP di Meta. Tutto ciò che Meta ha inviato viene preservato — error_subcode, error_data.details e lo stesso fbtrace_id di Meta:
{
"error": {
"message": "Unsupported post request. Object with ID '106540352242922' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
"code": 100,
"type": "GraphMethodException",
"error_subcode": 33,
"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
}
}
Nota: Nota il
typein questo esempio —GraphMethodException, nonOAuthException. Meta utilizza diversi tipi di eccezione e noi non li normalizziamo. Esegui lo switch suerror.code, che è un numero ed è stabile; trattatypecome un’etichetta per le persone.
Quando un id non ti appartiene
Ogni id nel percorso — l’id del numero di telefono, l’id WABA, l’id di un file multimediale — viene verificato rispetto all’account associato alla tua chiave prima di qualsiasi altra operazione. Una mancata corrispondenza restituisce il codice 100, formulato nello stesso modo in cui Meta descrive un oggetto che non puoi vedere:
Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.
Questa formulazione è intenzionale da parte di Meta e viene riprodotta intenzionalmente qui: un id che esiste ma appartiene a qualcun altro e un id che non esiste affatto devono essere indistinguibili, altrimenti l’errore diventerebbe un modo per scoprire i numeri di telefono di altre persone.
Media
Quattro endpoint, che corrispondono a quelli di Meta.
| Metodo | Percorso | Cosa fa |
|---|---|---|
POST | /{version}/{phone-number-id}/media | Carica un file. Multipart, restituisce {"id": "…"}. |
GET | /{version}/{media-id} | L’oggetto con i metadati di Meta per il file. |
GET | /{version}/{media-id}/download | I byte. |
DELETE | /{version}/{media-id} | Lo elimina, restituisce {"success": true}. |
L’unica differenza intenzionale
GET /{version}/{media-id} restituisce l’oggetto con i metadati di Meta — messaging_product, mime_type, sha256, file_size, id — ma l’url punta a noi, non all’host lookaside di Meta.
Deve farlo. L’URL del file multimediale di Meta può essere recuperato solo con il token aziendale dell’account WhatsApp, che risiede dal nostro lato e non lo lascia mai. Quindi ti forniamo un URL che puoi recuperare: l’endpoint di download indicato sopra, sullo stesso host e segmento di versione che hai chiamato, autenticato con lo stesso bearer token che hai già inviato.
I client trattano quell’URL come opaco ed eseguono semplicemente una GET su di esso con il loro token, motivo per cui un SDK non modificato non se ne accorge. Se il tuo codice gestisce il nome host come caso speciale, questo è l’unico punto in cui sarà necessaria una modifica.
Permessi
Gli stessi chip dei permessi dell’API WizMessage, sulle stesse chiavi. Il punto da cui il permesso viene letto dipende dalla chiamata: l’endpoint di invio lo ricava dal corpo della richiesta, perché Meta inserisce ogni tipo di messaggio su un unico percorso; in qualsiasi altro punto proviene dal percorso e dal metodo.
Invio e media:
| Chiamata | Permesso |
|---|---|
POST /{v}/{pnid}/messages con "type": "template" | send_template |
stessa chiamata, type di image, video, audio, document o sticker | send_media |
| stessa chiamata, qualsiasi altra cosa — text, interactive, reaction, location, contacts, e mark-as-read | send_text |
POST /{v}/{pnid}/media — caricamento | send_media |
DELETE /{v}/{media-id} | send_media |
GET /{v}/{media-id} e /download | view_messages |
Gestione dell’account — vedi Gestione dell’account:
| Chiamata | Permesso |
|---|---|
GET /{v}/{waba-id}/message_templates | view_templates |
POST e DELETE /{v}/{waba-id}/message_templates | manage_templates |
GET /{v}/{waba-id}/template_analytics | view_analytics |
GET su profilo aziendale, codici QR, impostazioni di commercio, elenco bloccati, impostazioni del telefono e flussi | view_templates |
POST su questi stessi sei | manage_profile |
DELETE /{v}/{pnid}/message_qrdls/{code} e DELETE /{v}/{pnid}/block_users | manage_profile |
Queste sono le uniche due DELETE sul lato della gestione. Non esiste alcuna operazione di eliminazione per profilo aziendale, impostazioni di commercio, impostazioni del telefono o flussi — una DELETE verso uno qualsiasi di essi viene rifiutata con code 100, esattamente come per un endpoint che non esiste.
Nota: Il caricamento dei media qui richiede
send_media. Sull’API WizMessage non richiede alcun permesso, in base al principio secondo cuisend_mediaregola l’invio di un file a un cliente anziché il suo caricamento sui server di Meta. Questa superficie adotta la linea più rigorosa. Se stai trasferendo una chiave e i caricamenti iniziano a restituire403, il motivo è questo.
Nota:
view_templatescontrolla molto più dei soli modelli. La lettura di profilo aziendale, codici QR, impostazioni di commercio, elenco bloccati, impostazioni del telefono e flussi si trova tutta dietro questo permesso. Il nome è storico — precede tutto ciò che è presente nella seconda tabella. Se lo deselezioni mentre restringi i permessi di una chiave, sei letture del tutto non correlate inizieranno a restituire403con un messaggio sui modelli, un indizio per nulla utile.
Nota: Tre chip sono riservati esclusivamente a Meta Graph.
manage_templates,manage_profileeview_analyticsnon controllano nulla sull’API WizMessage — esistono per gli endpoint in questa pagina. A ogni chiave già esistente sono stati concessi tutti e tre, quindi nulla di ciò che funzionava si è interrotto; restringerli richiede di deselezionarli intenzionalmente nel modulo di modifica della chiave.
Un rifiuto è il code 10 di Graph con 403 — mai il nostro PERMISSION_DENIED. Un unico gestore degli errori copre interamente questa superficie.
La proprietà viene verificata prima dei permessi. Se l’id nel percorso non è quello associato alla tua chiave, la risposta è code 100 e non rivela mai quale permesso ti mancava — altrimenti l’errore stesso diventerebbe un modo per sondare gli account di altre persone.
Gestione dell’account
Oltre all’invio, questa superficie ospita gli endpoint di gestione dell’account di Meta sui percorsi proprietari di Meta. Otto risorse, e il permesso necessario dipende dal fatto che tu stia leggendo o scrivendo.
Tre aspetti valgono per ogni endpoint di questa sezione, e sono la ragione stessa per cui può esistere:
- Il corpo della richiesta è quello di Meta, inoltrato invariato e non convalidato. Non documentiamo nuovamente qui i corpi di Meta e non li controlliamo. La documentazione di riferimento di Meta è la specifica, e l’errore di Meta è ciò che viene restituito se ne sbagli uno — un errore migliore di qualsiasi altro potremmo inventare.
- Il corpo viene inviato solo su
POST. Un corpo allegato a unaDELETEviene scartato prima che la richiesta lasci i nostri server. L’eliminazione dei modelli di Meta accetta?name=o?hsm_id=come parametri di query, non un corpo, quindi funziona come documentato; qualsiasi altra operazione che si aspetti un corpo conDELETEnon funzionerà. - La tua stringa di query viene inoltrata, a eccezione di
access_tokeneappsecret_proof. Questi due parametri vengono rimossi, perché Meta dà la priorità a un token nella stringa di query rispetto all’intestazioneAuthorizatione lasciarli passare renderebbe facoltativo il tuo token bearer. Un client che si autentica tramite stringa di query la vedrà silenziosamente ignorata — usa l’intestazione.
Nota: L’ID WABA e l’ID del numero di telefono in questi percorsi devono essere quelli associati alla tua chiave. Questo controllo viene effettuato prima che qualsiasi richiesta lasci la nostra rete, e una mancata corrispondenza genera lo stesso
code 100descritto in Quando un ID non è tuo.
Nota:
paging.nextpunta a Meta, non a noi. Le risposte vengono restituite esattamente come inviate da Meta, quindi un linknextin una risposta impaginata è un URLgraph.facebook.com— e la tua chiave API non consente di autenticarsi lì. Esegui la paginazione prendendopaging.cursors.aftere inviando nuovamente la richiesta verso questo host con?after=.
Modelli
GET https://wizmessage.com/v26.0/{waba-id}/message_templates?limit=25
POST https://wizmessage.com/v26.0/{waba-id}/message_templates
DELETE https://wizmessage.com/v26.0/{waba-id}/message_templates?name=order_shipped
| Metodo | Permesso | Restituisce |
|---|---|---|
GET | view_templates | { data, paging } di Meta |
POST | manage_templates | Risposta di creazione di Meta |
DELETE | manage_templates | Risposta di eliminazione di Meta |
GET accetta limit (1–100, valore predefinito 25) e after per la paginazione basata su cursore.
Nota:
GETaccetta sololimiteafter. Gli altri filtri di Meta su questo edge —name,status,fields,language,category,name_or_content— vengono ignorati silenziosamente, non rifiutati. Una richiesta per?status=APPROVEDrestituisce un200contenente tutti i modelli, approvati o meno. Filtra dal tuo lato, oppure usaafterper scorrere l’elenco completo. Questo è l’unico punto in questa pagina in cui un client migrato riceve una risposta errata anziché un errore, quindi vale la pena verificare il proprio codice.
Analisi dei modelli
GET https://wizmessage.com/v26.0/{waba-id}/template_analytics
Richiede view_analytics. Meta esige start e risponde con code 100 — "(#100) The parameter start is required" — se non viene fornito. granularity e i restanti parametri sono quelli di Meta; inoltrali e arriveranno invariati.
Profilo aziendale
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile
GET richiede view_templates e restituisce { data } di Meta. POST richiede manage_profile.
Codici QR
GET https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
POST https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
DELETE https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls/{code}
GET richiede view_templates e restituisce { data } di Meta. POST e DELETE richiedono manage_profile.
Il percorso /{code} è solo DELETE. Non esiste GET o POST su un singolo codice — leggi la raccolta e seleziona da lì.
Impostazioni di commercio
GET https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
GET richiede view_templates e restituisce { data } di Meta. POST richiede manage_profile.
Clienti bloccati
GET https://wizmessage.com/v26.0/{phone-number-id}/block_users
POST https://wizmessage.com/v26.0/{phone-number-id}/block_users
DELETE https://wizmessage.com/v26.0/{phone-number-id}/block_users
GET richiede view_templates e restituisce { data } di Meta. POST e DELETE richiedono manage_profile. Nota che lo sblocco è una DELETE inviata alla raccolta stessa, non a un percorso per singolo cliente.
Impostazioni del numero di telefono
GET https://wizmessage.com/v26.0/{phone-number-id}/settings
POST https://wizmessage.com/v26.0/{phone-number-id}/settings
GET richiede view_templates e restituisce { calling, storage_configuration }. POST richiede manage_profile.
Nota: Il percorso è
/settings. Alcune documentazioni di API di terze parti lo chiamanowhatsapp_calling_settings— quel percorso non esiste su Meta e qui restituiscecode 2500, perché noi lo inoltriamo e Meta lo rifiuta. Vedi Che cosa non è disponibile qui.
Flussi
GET https://wizmessage.com/v26.0/{waba-id}/flows
POST https://wizmessage.com/v26.0/{waba-id}/flows
GET richiede view_templates e restituisce { data, paging } di Meta. POST richiede manage_profile.
Che cosa non è disponibile qui
Tutto ciò che precede è stato verificato su un account WhatsApp attivo. Lo stesso vale per tutto quanto segue — motivo per cui questa sezione può dirti perché un endpoint sia assente, e di solito è proprio questo a determinare che cosa fare dopo.
Che cosa restituisce un endpoint non disponibile. Tutto ciò che non figura nell’elenco precedente risponde con la dicitura stessa di Meta per un percorso che non intende gestire — code 100 con 400:
Unsupported get request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.
Un percorso che è supportato ma viene chiamato con un metodo che non rende disponibile restituisce lo stesso codice con un messaggio più breve: «Unsupported delete request.» Entrambi sono deliberatamente indistinguibili da un oggetto che semplicemente non puoi vedere — un errore che confermasse quali endpoint esistono sarebbe un modo per mappare la superficie.
Rifiutati intenzionalmente
Questi vengono bloccati su qualsiasi metodo, prima ancora che venga inoltrato alcunché:
| Percorso | Motivo |
|---|---|
register, deregister, request_code, verify_code | Un numero in coesistenza non deve mai essere registrato sulla Cloud API. Farlo è esattamente il modo in cui un account finisce per fallire ogni invio con l’errore 133010, e non è reversibile da parte tua. |
subscribed_apps | Tutti i metodi, compreso GET. Un DELETE qui annullerebbe l’iscrizione dei nostri webhook dal tuo account WhatsApp e comprometterebbe silenziosamente la tua integrazione; non offriamo neanche la lettura, piuttosto che lasciare un percorso in cui una singola svista possa provocare questo. |
marketing_messages | Gli invii di marketing passano attraverso gli strumenti delle campagne della dashboard, che applicano la frequenza di invio per account. |
/{template-id}/unpause | Meta identifica il modello tramite un semplice ID senza alcun account nel percorso, quindi non possiamo dimostrare che il modello sia tuo prima di intervenire su di esso. Rimuovi la pausa dalla dashboard. |
messages su qualsiasi metodo eccetto POST | Il percorso di invio include il limitatore di frequenza e la gestione della sospensione dell’account. Viene instradato solo POST |
Non disponibili su un numero in coesistenza
Le risposte dirette di Meta, verificate su un account attivo il 10 agosto 2026:
| Percorso | Risposta di Meta |
|---|---|
/{phone-number-id}/conversational_automation | code 100 — "Tried accessing nonexisting field" |
/{phone-number-id}/calls | code 100 — "Tried accessing nonexisting field" |
/{phone-number-id}/groups | code 131000 con un 500 |
Queste sono restrizioni di Meta sui numeri utilizzati in coesistenza con l’app WhatsApp Business, non nostre — noi inoltriamo la richiesta ed è questo ciò che viene restituito. Di tanto in tanto Meta amplia la disponibilità, quindi se una di queste ti interessa vale la pena effettuare un nuovo test anziché fare affidamento su questa tabella a tempo indefinito.
Percorsi che non esistono da nessuna parte
Ciascuno di questi compare nelle documentazioni API di terze parti e non è un endpoint di Meta. Tutti e quattro restituiscono code 2500, «Unknown path components»:
| Cosa potresti aver letto | Cosa usare invece |
|---|---|
POST /{phone-number-id}/mark_message_as_read | POST /{phone-number-id}/messages con un corpo status: "read" — vedi Contrassegnare un messaggio come letto |
GET /{phone-number-id}/message_status | Gli stati di consegna arrivano sul tuo webhook; vedi Scegliere cosa ricevere |
/{phone-number-id}/whatsapp_calling_settings | /{phone-number-id}/settings |
/{phone-number-id}/conversational_components | Niente — il percorso reale più vicino è conversational_automation, che non è disponibile su un numero in coesistenza |
Reali su Meta, non nel nostro elenco
GET /{waba-id}/phone_numbers funziona su Meta e qui non viene né bloccato né inoltrato, quindi risponde con code 100. È uno dei primi endpoint chiamati da un client della Cloud API, quindi vale la pena citarlo: la tua chiave associa già esattamente un unico numero di telefono, e il suo ID è quello che inserisci in ogni percorso di questa pagina. Puoi leggerlo dalla scheda Panoramica della chiave nella dashboard.
Letture di singoli nodi
GET /{v}/{waba-id}?fields=… e GET /{v}/{phone-number-id}?fields=… funzionano su Meta ma non qui. Un percorso a segmento singolo su questa superficie è un ID del media — questo è ciò che significa GET /{v}/{media-id} — quindi un ID WABA in quella posizione viene cercato come media e l’operazione fallisce.
Il fallimento è fuorviante se non te lo aspetti: controlla prima view_messages, quindi una chiave priva di tale autorizzazione riceve un 403 che cita un’autorizzazione priva di qualsiasi attinenza con quanto richiesto. Usa invece le forme edge — /{waba-id}/message_templates, /{phone-number-id}/settings e il resto di Gestione dell’account.
Webhook nel formato di Meta
La scheda Webhook della dashboard si apre su un formato di payload. WizMessage (v1) è il payload documentato nell’altra pagina; è quello utilizzato da una chiave finché non lo modifichi.

Scegli Meta Graph e il tuo endpoint smette di ricevere il nostro payload {version, event, timestamp, data} e inizia a ricevere l’involucro che Meta ci ha inviato, inoltrato testualmente — una consegna per ogni modifica.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"time": 1770000123,
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [{ "profile": { "name": "Priya Sharma" }, "wa_id": "919876543210" }],
"messages": [
{
"from": "919876543210",
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg…",
"timestamp": "1770000123",
"type": "text",
"text": { "body": "Has it shipped yet?" }
}
]
},
"field": "messages"
}
]
}
]
}
Se disponi già di un gestore per i webhook di Cloud API, questa è la struttura per cui è stato scritto.
Cambiare formato modifica anche ciò che la scheda ti richiede: le caselle di selezione degli eventi vengono sostituite dai nomi dei campi di Meta e compare un token di verifica.

Prima di poterne salvare uno
Sono necessari tre elementi, e la dashboard ti segnalerà quale manca:
- Un secret del webhook. È l’unico elemento che funge da chiave per
X-Hub-Signature-256, quindi senza di esso una consegna risulterebbe non firmata e non verificabile. Generane uno nella scheda Webhook della chiave. - Un token di verifica. Qualsiasi stringa a tua scelta; anche il tuo endpoint deve conoscerla.
- Un URL che risponde già. Vedi sotto.
L’handshake di verifica
Quando salvi, chiamiamo il tuo URL esattamente come farebbe Meta:
GET https://your-server.example/webhooks
?hub.mode=subscribe
&hub.verify_token=<the token you set>
&hub.challenge=482910337
Il tuo endpoint deve verificare che hub.verify_token corrisponda a quanto hai configurato, quindi rispondere 200 con hub.challenge come intero corpo della risposta — nessun wrapper JSON, nessuna virgoletta, nient’altro. Il challenge è un numero a 9 cifre, quindi un gestore che esegue parseInt prima di restituirlo in eco lo reinvia invariato.
Se il challenge non viene restituito esattamente identico, il salvataggio viene rifiutato e non viene memorizzato nulla. Questo impedisce a chiunque di puntare la nostra coda di consegna verso un URL che non controlla.
// express
app.get('/webhooks', (req, res) => {
if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === VERIFY_TOKEN) {
return res.status(200).send(req.query['hub.challenge'])
}
res.sendStatus(403)
})
Verifica della firma
Ogni consegna include X-Hub-Signature-256, calcolato come lo calcola Meta: HMAC-SHA256 del corpo grezzo della richiesta, con il secret del tuo webhook come chiave, in esadecimale, preceduto da sha256=.
| Intestazione | Valore |
|---|---|
X-Hub-Signature-256 | sha256= + HMAC-SHA256 del corpo grezzo, con il tuo secret del webhook come chiave, esadecimale minuscolo. |
X-Webhook-Event | meta.<field> — quale campo trasporta questa consegna. |
X-Webhook-Id | ID univoco per questo tentativo di consegna. Usalo per deduplicare. |
User-Agent | facebookplatform/1.0 (+http://developers.facebook.com) |
Nota: Questa non è la stessa derivazione del formato WizMessage. Quello firma
timestamp + "." + rawBodye invia il timestamp in una propria intestazione; questo firma il solo corpo, senza alcun timestamp. Se stai eseguendo entrambi i formati sullo stesso server, mantieni separati i due verificatori — uno condiviso fallirà su quello per cui non è stato scritto.
Firma i byte grezzi esattamente come ricevuti. Eseguire il parsing del JSON e riserializzarlo modifica l’ordine delle chiavi e gli spazi, e la firma non corrisponderà mai.
const crypto = require('node:crypto')
// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
const provided = req.get('X-Hub-Signature-256') || ''
if (!provided.startsWith('sha256=')) return false
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body) // the raw Buffer, not a parsed object
.digest('hex')
// Constant-time compare — a plain === leaks timing information.
const a = Buffer.from(expected, 'hex')
const b = Buffer.from(provided.slice('sha256='.length), 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
Scegliere cosa ricevere
Il formato WizMessage ti fa selezionare gli eventi. Questo ti fa selezionare i nomi dei campi di Meta, corrispondenti a ciò a cui ti iscriveresti nella App Dashboard di Meta.
| Campo | Cosa arriva |
|---|---|
messages | Messaggi in arrivo e stati di consegna. Leggi la nota qui sotto. |
message_status | Stati di consegna, come campo a sé stante. |
smb_message_echoes | Messaggi inviati dall’azienda dall’app WhatsApp Business sul proprio telefono. |
smb_app_state_sync | Modifiche alla rubrica apportate su quel telefono. |
user_id_update | L’identità WhatsApp di un contatto è cambiata. |
message_template_status_update | Un modello è stato approvato, rifiutato o sospeso. |
message_template_quality_update | Il punteggio di qualità di un modello è variato. |
account_update | L’account WhatsApp è stato connesso, disconnesso, limitato o rimosso. |
history | Conversazioni passate, durante la sincronizzazione iniziale. Payload di grandi dimensioni — abilitalo solo se li desideri. |
I nuovi webhook Graph partono con la sottoscrizione al solo campo messages. Deselezionare tutti i campi disattiva le consegne senza eliminare la configurazione.
Nota:
messagesinclude già gli stati di consegna. Meta invia entrambi sotto"field": "messages"— i messaggi in arrivo in un arraymessages, le notifiche di consegna in un arraystatusessullo stesso oggetto value. Quindi l’iscrizione predefinita è sufficiente per correlare ilwamidricevuto da un invio.message_statusè un campo aggiuntivo, non quello necessario per il tracciamento di base dello stato. Leggivalue.statusesprima di presumere che ti manchi un’iscrizione.
Tre aspetti che differiscono dal formato WizMessage
Vale la pena leggerli se stai migrando un’integrazione, perché ciascuno di essi modifica silenziosamente ciò che viene ricevuto.
- La consegna non è vincolata al sistema di chatbot. Nel formato WizMessage, i messaggi in arrivo raggiungono il tuo endpoint solo quando il sistema di chatbot dell’account è impostato su Webhook. Il formato Graph ignora completamente questa impostazione — configurare un URL e iscriversi a un campo costituisce l’intera abilitazione.
- Ricevi
status: "sent"e gli stati delle campagne. Il formato WizMessage scarta deliberatamente entrambi. Qui ricevi ciò che Meta ha inviato, il che si traduce in un traffico di stati sensibilmente maggiore su un account che esegue campagne massive. - Non esiste alcun
message.sentsintetico. Il formato WizMessage ne genera uno fittizio per i messaggi inviati dall’API, dalla dashboard o dal telefono. Meta copre lo stesso ambito consmb_message_echoese lo statosent, quindi qui non viene inventato nulla.
Consegna, tentativi e disattivazione
Identico al formato WizMessage — si applica la stessa tabella. In breve: attendiamo 10 secondi, non seguiamo mai i reindirizzamenti, ritentiamo cinque volte per 5xx/408/429/timeout con backoff, non ritentiamo mai altri 4xx e consideriamo 410 Gone come «disattiva questo webhook».
Le consegne avvengono con logica at-least-once. Deduplica in base a X-Webhook-Id e rispondi rapidamente con un 2xx.
Provarlo senza scrivere codice
La finestra di dialogo Test API della chiave presenta un controllo Formato API. Impostalo su Meta Graph e il selettore dell’endpoint viene sostituito dalla destinazione reale per il tuo account — POST /v26.0/{your phone number id}/messages — con un corpo precompilato nel formato di Meta.

«Simula solo» restituisce la richiesta senza contattare Meta; passare a «Invia messaggio reale» la invia e ti mostra la risposta effettiva di Meta, con tanto di envelope dell’errore.
La finestra di dialogo punta a POST /{phone-number-id}/messages e a nient’altro, quindi gli endpoint di gestione dell’account non sono raggiungibili da qui — provali con curl o con un tuo client.
Ottieni codice include lo stesso controllo, quindi lo snippet generato punta a qualunque superficie tu scelga, in ciascuno degli otto linguaggi. Lascia disattivata l’opzione «Richiedi firma» su una chiave che intendi usare qui — se è attiva, lo snippet Graph generato firma anche la richiesta, che è l’unica cosa che un client Cloud API non modificato non può fare.