Vai al contenuto
32 min read

Connettersi con la Meta Graph API

Indirizza un’integrazione esistente di WhatsApp Cloud API verso WizMessage senza riscriverla — i percorsi di Meta, i corpi di richiesta di Meta, l’envelope degli errori di Meta, i webhook nel formato di Meta e gli endpoint di gestione dell’account per modelli, profilo aziendale, codici QR e flussi.

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

Confronto tra l’API di WizMessage e l’API compatibile con Meta GraphScegli quella che corrisponde a ciò che hai giàWizMessage API/api/v1/externalvariabili dei modelli con nomeinterfaccia di mappatura nella dashboardcampo reference, verifica dello statoil nostro envelope JSON proprietarioideale se parti da zeroMeta Graph API/v26.0/{phone-number-id}/…corpi delle richieste di Metaenvelope degli errori di Metagestione di modelli e profilowebhook nel formato di Metaideale se hai già codice per la Cloud APIStesse chiavi, stessi permessi, stessi limiti di frequenza. Usale entrambe se vuoi.
Due superfici, un solo account. Nessuna delle due scomparirà.

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.
  • v26 da solo viene rifiutato. Il numero minor non è facoltativo. v26.0 va 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.

IntestazioneValore
AuthorizationBearer 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 190 con un 401. 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:

IntestazioneValore
X-Subscription-WarningSubscription 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"
	}
}
Cosa succede all’accesso API dopo la scadenza di un abbonamentouna chiave APInormalenessuna intestazionefinestra di tolleranza7 giorni, le chiamate hanno ancora successoX-Subscription-Warning su ogni rispostarifiutatocode 10 a 403prima chiamata dopo la scadenzail conteggio inizia quifine della finestranessun ulteriore avvisoIl rinnovo in qualsiasi momento ripristina l’accesso entro pochi minuti.
La scadenza in sé non cambia nulla. Il conteggio inizia alla tua prossima chiamata.

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à un 403.

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 to accetta 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.164 e 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 contacts di 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.

Come ti arriva un errore a seconda che sia stato generato da MetaUn errore su questa superficieRifiutato da Metainoltrato testualmentecodice e subcode di Metail fbtrace_id di Metaanche lo status è di MetaRifiutato da noiautenticazione, permessi, rate limitespresso nei codici di Metacosì un solo gestore copre entrambi401 · 403 · 429 · 400 · 500Non dare mai per scontato che type sia OAuthException — Meta ne usa diversi.
Gli errori di Meta vengono inoltrati intatti. I nostri prendono in prestito i codici di Meta.

Errori generati da noi

codeHTTPQuando
190401Chiave 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.
10403Alla chiave manca il permesso richiesto da questa chiamata (vedi Permessi), oppure l’abbonamento dell’account è scaduto oltre la finestra di tolleranza.
4429La quota al minuto o giornaliera della chiave è esaurita.
100400Richiesta non valida, un id nel percorso che non ti appartiene, oppure un endpoint non gestito da questa superficie.
2500Si è 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 type in questo esempio — GraphMethodException, non OAuthException. Meta utilizza diversi tipi di eccezione e noi non li normalizziamo. Esegui lo switch su error.code, che è un numero ed è stabile; tratta type come 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.

MetodoPercorsoCosa fa
POST/{version}/{phone-number-id}/mediaCarica un file. Multipart, restituisce {"id": "…"}.
GET/{version}/{media-id}L’oggetto con i metadati di Meta per il file.
GET/{version}/{media-id}/downloadI byte.
DELETE/{version}/{media-id}Lo elimina, restituisce {"success": true}.
Caricare un file una volta e inviarlo ripetutamentePOST /{v}/{pnid}/mediail file stesso{ id }riutilizzabilePOST /{v}/{pnid}/messagesfai riferimento all’idConsegnatogli stati arrivano tramite webhook
Il caricamento restituisce un id. L’id è ciò che inserisci in un messaggio.

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:

ChiamataPermesso
POST /{v}/{pnid}/messages con "type": "template"send_template
stessa chiamata, type di image, video, audio, document o stickersend_media
stessa chiamata, qualsiasi altra cosa — text, interactive, reaction, location, contacts, e mark-as-readsend_text
POST /{v}/{pnid}/media — caricamentosend_media
DELETE /{v}/{media-id}send_media
GET /{v}/{media-id} e /downloadview_messages

Gestione dell’account — vedi Gestione dell’account:

ChiamataPermesso
GET /{v}/{waba-id}/message_templatesview_templates
POST e DELETE /{v}/{waba-id}/message_templatesmanage_templates
GET /{v}/{waba-id}/template_analyticsview_analytics
GET su profilo aziendale, codici QR, impostazioni di commercio, elenco bloccati, impostazioni del telefono e flussiview_templates
POST su questi stessi seimanage_profile
DELETE /{v}/{pnid}/message_qrdls/{code} e DELETE /{v}/{pnid}/block_usersmanage_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 cui send_media regola 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 restituire 403, il motivo è questo.

Nota: view_templates controlla 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 restituire 403 con un messaggio sui modelli, un indizio per nulla utile.

Nota: Tre chip sono riservati esclusivamente a Meta Graph. manage_templates, manage_profile e view_analytics non 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.

Gli endpoint di gestione dell’account raggruppati per il permesso richiesto da ciascunoLettura di qualsiasi risorsatutte e otto le risorseprofilo, codici QR, commercioelenco di blocco, impostazioni, flussimodelliview_templatesScrittura dell’accountprofilo e presenzaprofilo aziendale, codici QRcommercio, elenco di bloccoimpostazioni, flussimanage_profileScrittura dei modellicreazione ed eliminazionemessage_templatesl’analisi è separatamanage_templatesL’analisi dei modelli ha un proprio chip: view_analytics.
La lettura corrisponde a un solo chip. La scrittura si suddivide in base a ciò che scrivi.

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 una DELETE viene 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 con DELETE non funzionerà.
  • La tua stringa di query viene inoltrata, a eccezione di access_token e appsecret_proof. Questi due parametri vengono rimossi, perché Meta dà la priorità a un token nella stringa di query rispetto all’intestazione Authorization e 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 100 descritto in Quando un ID non è tuo.

Nota: paging.next punta a Meta, non a noi. Le risposte vengono restituite esattamente come inviate da Meta, quindi un link next in una risposta impaginata è un URL graph.facebook.com — e la tua chiave API non consente di autenticarsi lì. Esegui la paginazione prendendo paging.cursors.after e 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
MetodoPermessoRestituisce
GETview_templates{ data, paging } di Meta
POSTmanage_templatesRisposta di creazione di Meta
DELETEmanage_templatesRisposta di eliminazione di Meta

GET accetta limit (1–100, valore predefinito 25) e after per la paginazione basata su cursore.

Nota: GET accetta solo limit e after. 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=APPROVED restituisce un 200 contenente tutti i modelli, approvati o meno. Filtra dal tuo lato, oppure usa after per 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 chiamano whatsapp_calling_settings — quel percorso non esiste su Meta e qui restituisce code 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.

Perché un endpoint potrebbe non essere disponibile su questa superficieun endpoint non presente quiLo rifiutiamo noiregistration, subscribed_appscomprometterebbe il tuo accountnessun workaroundLo rifiuta Metanon su un numero in coesistenzaconversational_automation, callsla risposta stessa di MetaNon esistequattro percorsi da mirror delle APIMeta risponde con code 2500usa il percorso realeUn quarto gruppo semplicemente non è ancora nel nostro elenco — vedi sotto.
Quattro motivi, e solo uno dipende da noi.

Rifiutati intenzionalmente

Questi vengono bloccati su qualsiasi metodo, prima ancora che venga inoltrato alcunché:

PercorsoMotivo
register, deregister, request_code, verify_codeUn 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_appsTutti 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_messagesGli invii di marketing passano attraverso gli strumenti delle campagne della dashboard, che applicano la frequenza di invio per account.
/{template-id}/unpauseMeta 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 POSTIl 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:

PercorsoRisposta di Meta
/{phone-number-id}/conversational_automationcode 100 — "Tried accessing nonexisting field"
/{phone-number-id}/callscode 100 — "Tried accessing nonexisting field"
/{phone-number-id}/groupscode 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 lettoCosa usare invece
POST /{phone-number-id}/mark_message_as_readPOST /{phone-number-id}/messages con un corpo status: "read" — vedi Contrassegnare un messaggio come letto
GET /{phone-number-id}/message_statusGli 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_componentsNiente — 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.

La scheda Webhook con il formato di payload impostato su WizMessage, che mostra le caselle di controllo degli eventi v1

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.

La scheda Webhook nel formato Meta Graph, che mostra il token di verifica e i nove nomi di campo di Meta a cui è possibile iscriversi

Prima di poterne salvare uno

Sono necessari tre elementi, e la dashboard ti segnalerà quale manca:

Cosa deve essere pronto prima di poter salvare un webhook Meta GraphSecret del webhookfunge da chiave per la firmaToken di verificadimostra che l’URL è tuoUn URL attivolo chiamiamo prima di salvareSalvatoiniziano le consegneUn URL che non risponde ancora non può essere salvato. Prima fai il deploy, poi configura.
Tutti e tre vengono verificati quando premi salva, in questo ordine.
  • 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=.

IntestazioneValore
X-Hub-Signature-256sha256= + HMAC-SHA256 del corpo grezzo, con il tuo secret del webhook come chiave, esadecimale minuscolo.
X-Webhook-Eventmeta.<field> — quale campo trasporta questa consegna.
X-Webhook-IdID univoco per questo tentativo di consegna. Usalo per deduplicare.
User-Agentfacebookplatform/1.0 (+http://developers.facebook.com)

Nota: Questa non è la stessa derivazione del formato WizMessage. Quello firma timestamp + "." + rawBody e 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.

CampoCosa arriva
messagesMessaggi in arrivo e stati di consegna. Leggi la nota qui sotto.
message_statusStati di consegna, come campo a sé stante.
smb_message_echoesMessaggi inviati dall’azienda dall’app WhatsApp Business sul proprio telefono.
smb_app_state_syncModifiche alla rubrica apportate su quel telefono.
user_id_updateL’identità WhatsApp di un contatto è cambiata.
message_template_status_updateUn modello è stato approvato, rifiutato o sospeso.
message_template_quality_updateIl punteggio di qualità di un modello è variato.
account_updateL’account WhatsApp è stato connesso, disconnesso, limitato o rimosso.
historyConversazioni 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: messages include già gli stati di consegna. Meta invia entrambi sotto "field": "messages" — i messaggi in arrivo in un array messages, le notifiche di consegna in un array statuses sullo stesso oggetto value. Quindi l’iscrizione predefinita è sufficiente per correlare il wamid ricevuto da un invio. message_status è un campo aggiuntivo, non quello necessario per il tracciamento di base dello stato. Leggi value.statuses prima 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.

Tre comportamenti che differiscono tra i due formati di webhookNessun filtro del chatbotconsegnato in ogni casola v1 richiede bot mode = WebhookGraph ignora tale impostazioneRicevi lo stato sente gli stati delle campagnela v1 esclude entrambiGraph inoltra tuttoNessun sent sinteticoal suo posto gli eventi di Metasmb_message_echoese gli statiAspettati più traffico sul formato Graph rispetto a quanto prodotto dallo stesso account sulla v1.
Tutti e tre fanno sì che il formato Graph consegni di più, non di meno.
  • 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.sent sintetico. Il formato WizMessage ne genera uno fittizio per i messaggi inviati dall’API, dalla dashboard o dal telefono. Meta copre lo stesso ambito con smb_message_echoes e lo stato sent, 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.

La finestra di dialogo Test API in modalità Meta Graph, che mostra l’endpoint dei messaggi in sola lettura e un corpo della richiesta 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.