Collegare il tuo software a WhatsApp
La Gestione API è il modo in cui un altro sistema — il tuo software di fatturazione, il tuo negozio online, il tuo backend — invia messaggi WhatsApp tramite WizMessage. Qui gli assegni una chiave API, gli indichi quale template WhatsApp approvato può inviare e lo colleghi a un webhook per ricevere le risposte. Questa guida percorre l’intero tragitto e documenta poi l’API REST che i tuoi sviluppatori chiameranno.

Due modi per collegarsi
Tutto ciò che trovi in questa pagina riguarda la WizMessage API. Esiste una seconda superficie, la Meta Graph API, che riproduce la WhatsApp Cloud API di Meta in modo che il codice già scritto per Meta funzioni dopo aver cambiato l’URL di base e il token.
Scegli la WizMessage API se parti da zero — la mappatura dei template e il campo reference tolgono la maggior parte del lavoro. Scegli la Meta Graph API se hai già codice per la Cloud API, una libreria o uno sviluppatore che conosce le strutture di Meta.
La dashboard, le chiavi, i permessi e i limiti di velocità descritti sotto valgono per entrambe.
La dashboard
Dove si trovano le tue chiavi API
Ogni chiave che hai generato compare qui, nella sezione «API Keys». Ogni riga mostra lo stato della chiave, il suo prefisso pubblico (l’unica parte della chiave che venga mostrata di nuovo dopo la creazione) e quante chiamate ha effettuato oggi. «Manage» apre la chiave; l’interruttore la mette in pausa senza eliminarla.

Una chiave non ancora completa
Una chiave a cui non è mappato alcun template riporta il badge «Needs setup». Può autenticarsi, ma non può inviare un messaggio template finché non ne mappi uno — così un’integrazione configurata a metà si nota a colpo d’occhio, invece di fallire più tardi al momento dell’invio.

Configurazione guidata
Passo 1 — Che cosa stai collegando?
«Connect your software» apre una procedura guidata in quattro passi. Inizia dando alla chiave il nome del sistema che la userà e scegli il preset corrispondente. I preset si limitano a suggerire nomi di campo sensati — quello per la fatturazione propone invoice_number, amount, due_date, customer_name — ma non limitano ciò che puoi mappare.

Passo 2 — Scegli il messaggio
Scegli uno dei tuoi template WhatsApp approvati. I template risiedono su Meta, non qui — questo elenco viene recuperato in tempo reale dal tuo account WhatsApp collegato e possono essere inviati solo i template APPROVED. Questo passo è facoltativo: saltalo se la chiave invia esclusivamente testo semplice e mappa un template in un secondo momento.

Passo 3 — Dove devono arrivare le risposte?
Quando qualcuno risponde al tuo messaggio, o quando arriva una conferma di consegna, inviamo i dati in POST a un URL che controlli tu. Lascia disattivata questa opzione se il tuo sistema si limita a inviare. Puoi aggiungerla in seguito dalla scheda «Webhooks» della chiave — qui nulla è definitivo.

Passo 4 — Vai in produzione
È la pressione di «Next» nel passo precedente a creare effettivamente la chiave: questa schermata è la conferma. Copia subito tutti e tre i valori: la chiave API, il segreto API e il segreto di firma del webhook vengono mostrati una sola volta e non sono più recuperabili in seguito. Se perdi il segreto devi ruotarlo, il che comporta aggiornare qualunque sistema lo stesse usando.

Gestire una chiave
Panoramica
Aprendo una chiave si arriva alla scheda «Overview»: che cosa le è consentito fare, quanto viene utilizzata e quali endpoint può chiamare. I conteggi di utilizzo sono letti dal log delle richieste, quindi riflettono il traffico reale. I chip sono i permessi della chiave — send_text, send_template, send_media, view_templates e view_messages. Le nuove chiavi li hanno tutti e cinque, quindi restringerne una significa togliere deliberatamente una spunta, invece di dover ricordare di concedere qualcosa.

Che cosa può fare una chiave
I chip nella scheda Overview sono i permessi della chiave. Ciascuno controlla l’accesso a un gruppo di endpoint, e una chiamata a un endpoint per cui la chiave non ha il permesso viene rifiutata con un 403 prima di qualsiasi altra cosa.
La tabella qui sotto riguarda la WizMessage API. Gli stessi chip controllano anche la Meta Graph API. Lì l’unico endpoint di invio legge il proprio permesso dal corpo del messaggio — Meta mette ogni tipo di messaggio su un unico percorso — mentre tutto il resto lo legge dal percorso e dal metodo, come qui.
| Permesso | Che cosa controlla |
|---|---|
send_text | POST /messages/text, /messages/reaction, /messages/contacts, /messages/interactive/list, /messages/interactive/button |
send_template | POST /messages/template, /messages/template/send |
send_media | POST /messages/media |
view_templates | GET /templates, /templates/:name |
view_messages | GET /media/:media_id |
manage_templates | Solo Meta Graph API — creazione ed eliminazione dei template |
manage_profile | Solo Meta Graph API — profilo aziendale, codici QR, impostazioni commerce, elenco dei bloccati, impostazioni del telefono, flow |
view_analytics | Solo Meta Graph API — analisi dei template |
Le nuove chiavi vengono create con tutti e otto i permessi spuntati, e quelle esistenti sono state ampliate di conseguenza — quindi restringere una chiave significa togliere deliberatamente una spunta dal suo modulo di modifica, invece di dover ricordare di concedere qualcosa. Le reazioni non hanno un permesso proprio: riutilizzano send_text, partendo dal presupposto che chi può scrivere a un cliente può anche reagire ai suoi messaggi. Vedi Inviare una reazione dal tuo software.
Gli ultimi tre non controllano nulla su questa API. Esistono per gli endpoint di gestione dell’account sulla pagina della Meta Graph, e sono elencati qui perché compaiono sugli stessi chip, sulle stesse chiavi.
Nota: Due endpoint sono deliberatamente privi di controllo, cosa che sorprende chi verifica una chiave.
POST /media/uploadnon richiede alcun permesso —send_mediaregola l’invio di un file a un cliente, non il caricamento di uno sui server di Meta. NemmenoGET /messages/:uuidne richiede uno: consultare lo stato di un messaggio inviato da questa stessa chiave è sempre consentito. Nessuno dei due amplia ciò che la chiave può raggiungere, perché ogni endpoint resta comunque limitato all’account WhatsApp della chiave stessa.Questo vale solo per la WizMessage API. Sulla superficie Meta Graph, sia il caricamento sia l’eliminazione dei media richiedono
send_media— quella superficie adotta la linea più rigida. Se punti una chiave esistente verso di essa e i caricamenti iniziano a restituire403, il motivo è questo.
Una chiave ancora da configurare
Una chiave senza alcun template mappato si apre invece sulla scheda «Setup» — la stessa procedura guidata, integrata nella pagina. Nota che le schede differiscono dallo screenshot precedente: finché una chiave non ha almeno un template, «Templates» e «Webhooks» non vengono proposte, perché non avrebbero ancora nulla su cui agire.

Template
Ogni card della scheda «Templates» corrisponde a un template che questa chiave può inviare. Il testo del corpo è il messaggio così come è stato approvato da Meta, e i chip sottostanti sono i nomi delle variabili che il tuo sistema dovrà fornire. «Try it» invia un test, «Get code» genera una richiesta pronta all’uso in otto linguaggi.

Leggere le variabili — l’unica cosa su cui vale la pena rallentare
Osserva la card del promemoria di appuntamento. I chip sotto il messaggio sono le sue variabili, elencate in ordine numerico: customer_name riempie {{1}} e appointment_date riempie {{2}}. Abbina i tuoi valori al NUMERO, mai all’ordine in cui i segnaposto compaiono nella frase — in questo template per caso seguono l’ordine, ma i template tradotti spesso li spostano, ed è lì che le integrazioni sbagliano.

I tre pulsanti presenti su ogni template
«Try it» — invia un test senza scrivere codice
Il pulsante con l’aeroplanino di carta apre questo template precompilato con valori di esempio, uno per ogni nome di variabile. È il modo più rapido di verificare che una mappatura sia corretta prima ancora che i tuoi sviluppatori la tocchino. Nota l’interruttore: «Simulate Only» è l’impostazione predefinita e nulla esce davvero — il server ti restituisce il payload così com’è. Portalo su «Send Real Message» e parte un vero messaggio WhatsApp verso il numero indicato, che viene anche addebitato.

Che cosa restituisce un invio simulato
Premendo «Send Request» in modalità «Simulate Only» ottieni la richiesta così come la piattaforma l’ha ricevuta, con lo stato HTTP e il tempo di andata e ritorno. Leggilo come un controllo di forma, non come una prova generale: conferma che il tuo JSON è stato interpretato e che la chiave è stata accettata, ma NON verifica i nomi delle tue variabili rispetto alla mappatura e non contatta mai Meta. Un payload che si simula senza errori può comunque essere rifiutato nella realtà. Per dimostrare la mappatura vera e propria, attiva «Send Real Message» e invia al tuo telefono.

«Get code» — la richiesta, già scritta per te
Il pulsante con le parentesi angolari genera una richiesta funzionante per questo preciso template in otto linguaggi: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go e C#. Consegnala a chi sta scrivendo l’integrazione. Le variabili compaiono come {{placeholders}} con i nomi della tua mappatura, e le credenziali restano YOUR_API_KEY / YOUR_API_SECRET — questa finestra non stampa mai la tua chiave reale, quindi lo snippet si può incollare in un ticket senza rischi.

Cambiare linguaggio
Clicca su un linguaggio qualsiasi in alto e lo snippet viene riscritto per quel linguaggio — stessa chiamata, stessi header, il client HTTP di quel linguaggio. Ognuno viene generato al primo clic, quindi un breve indicatore di caricamento al primo cambio è normale. «Copy» prende lo snippet così come appare: è completo, import inclusi, e se questa chiave richiede le firme il passaggio di firma è già dentro.

«Edit» — cambia ciò che invia il tuo sistema
La matita apre la mappatura vera e propria. Il mockup di telefono in alto è il messaggio reale con i tuoi nomi attuali già sostituiti, così vedi che cosa leggerà il cliente. Sotto, ogni variabile rilevata può essere rinominata, riordinata, resa obbligatoria o tipizzata — una data, un importo, un’immagine. Rinominare una variabile la rinomina anche nel payload della tua API, quindi un sistema che invia ancora il vecchio nome inizierà a fallire: cambia entrambe le cose insieme.

Test API — lo stesso strumento, qualsiasi endpoint
«Test API», in cima alla scheda, è «Try it» senza il vincolo del template: scegli uno qualsiasi dei tre endpoint di invio, cambia template dal secondo menu a discesa e modifica liberamente il corpo. Usalo per verificare le chiamate grezze /messages/text o /messages/template, che non hanno una card propria perché non sono legate ad alcuna mappatura. Qui le variabili compaiono come body_1, body_2 — è così che si presenta un template non mappato, ed è esattamente ciò che «Edit» serve a sistemare.

Risposte
Webhook — ricevere le risposte
Inviare è solo metà di un’integrazione. Indirizza un webhook verso un tuo endpoint HTTPS e Wiz Message vi invierà in POST i messaggi in entrata e gli aggiornamenti di consegna. Il segreto di firma viene mostrato una sola volta al momento della generazione; verificalo a ogni consegna, così sai che la chiamata proviene davvero da noi.

Quali eventi ricevi
Seleziona gli eventi che questo endpoint deve ricevere. Ciascuno arriva come POST a sé stante.
| Evento | Quando si attiva |
|---|---|
message.received | Un cliente ti ha inviato un messaggio. |
message.reaction | Qualcuno ha aggiunto o rimosso una reazione emoji. Scatta in entrambe le direzioni — vedi Reazioni. |
message.sent | È uscito un messaggio — dall’API, dalla dashboard web o digitato sul telefono dell’azienda. data.source ti dice quale. |
message.delivered | Il messaggio ha raggiunto il dispositivo del destinatario. |
message.read | Il destinatario l’ha aperto. |
message.failed | L’invio o la consegna è fallita; data.error ne riporta il motivo. |
Nota:
message.receivede lemessage.reactionin entrata vengono consegnate solo quando il sistema chatbot dell’account è impostato su Webhook. Con qualsiasi altra impostazione i messaggi in arrivo vanno al bot e il tuo endpoint non viene mai chiamato — la scheda Webhooks ti avvisa quando è così. Le reazioni inviate dall’azienda stessa (direction: "outbound") non sono influenzate da questa impostazione.Questo controllo vale solo per il formato di payload WizMessage. Una chiave impostata sul formato Meta Graph riceve i messaggi in entrata indipendentemente dal sistema chatbot dell’account — lì basta configurare un URL e iscriversi a un campo.
Nota: Le reazioni che l’azienda invia dal proprio telefono arrivavano prima come
message.sentcon il body"[Unsupported message type]". Ora arrivano comemessage.reactioncondirection: "outbound". Spunta il nuovo evento se ci facevi affidamento.
Le consegne sono at-least-once. Deduplica su event insieme a data.message_id anziché sul solo header X-Webhook-Id, e rispondi 2xx rapidamente.
Nota: Vengono inviati solo gli eventi spuntati. Se il tuo endpoint riceve le risposte ma non i report di consegna, quasi sempre è per questo —
message.deliveredemessage.readsono spunte separate damessage.received.
message.received e message.sent portano entrambi un blocco media quando il messaggio era un file, ma i metadati al suo interno variano a seconda dell’origine. Un messaggio in entrata porta mime_type e di solito sha256. Un message.sent generato da una tua chiamata API non porta né l’uno né l’altro — il media l’hai fornito tu, quindi non te lo ripetiamo. Un message.sent rimandato dal telefono dell’azienda li porta solo quando WhatsApp li ha inclusi, il che non accade sempre. Leggi data.source per sapere quale hai in mano; non dedurre mai l’origine da quali campi risultano presenti.
Com’è fatto un messaggio in entrata
Questo è ciò che arriva al tuo endpoint quando un cliente ti invia un’immagine. Ogni messaggio in entrata ha questa forma — cambia solo il blocco message a seconda del tipo.
{
"version": 1,
"event": "message.received",
"timestamp": "2026-08-01T05:56:49.000+00:00",
"data": {
"message_id": "wamid.HBgMOTE4MjgxMTI2OTU2FQIAEhggQUNEMTQx…",
"to": "",
"message": {
"type": "image",
"image": {
"id": "4603890099896453",
"caption": "[Image]",
"mime_type": "image/jpeg",
"sha256": "k3XrOe9vQZ1sYb2Lp8mNc4TdWfHgJkRuAiOsDxFvBnE="
}
},
"from": "918281126956",
"user_id": "IN.983887744040064",
"contact": {
"name": "Priya Sharma",
"wa_id": "918281126956",
"user_id": "IN.983887744040064"
}
}
}
| Campo | Sempre presente? | Che cos’è |
|---|---|---|
data.message_id | Sì | Il wamid del messaggio in entrata. |
data.to | Sì — ma sempre vuoto | Vedi la nota qui sotto. |
data.message | Sì | Il blocco descritto in Quale blocco ricevi. |
data.from | Solo quando WhatsApp ha inviato un numero | Il numero di telefono del cliente. |
data.user_id | Solo quando WhatsApp ne ha inviato uno | L’id utente WhatsApp del cliente. |
data.username | Solo quando il cliente ne ha uno | Il nome utente WhatsApp del cliente. |
data.contact | Solo quando è nota una qualsiasi identità | name, più wa_id / user_id / username quando li abbiamo. name ripiega sul nome utente, poi sul numero di telefono, poi sull’id utente. |
Nota:
data.toè sempre una stringa vuota sumessage.received. Il destinatario è il tuo numero aziendale, che già conosci. Non usarlo come chiave e non generalizzare: sumessage.sentlo stesso campo porta il destinatario reale.
Quale blocco ricevi
Il blocco message prende il nome dal tipo, e le famiglie da gestire sono soltanto tre.
Per i media, il blocco porta l’identità del file — mai un URL:
| Campo | Su quali tipi | Che cos’è |
|---|---|---|
id | Tutti i media | L’ID media di Meta. Scarica i byte con esso — vedi Leggere i file che ti inviano. |
mime_type | Tutti i media | Il tipo reale, image/jpeg o application/pdf. |
sha256 | Tutti i media, quando WhatsApp lo invia | Hash del contenuto. Utile per deduplicare lo stesso file inviato due volte. |
filename | Solo documenti | Il nome com’era sul dispositivo del mittente. È il nome con cui salvare il file. |
caption | Tutti i media | La didascalia del mittente — o un segnaposto. Leggi la nota qui sotto prima di fidarti. |
Nota:
captionpuò essere un segnaposto che nessuno ti ha mai inviato. Su un’immagine o un video ottieni la didascalia vera quando c’era, e"[Image]"/"[Video]"quando non c’era. Su audio e sticker è sempre"[Audio]"/"[Sticker]"— WhatsApp su quei tipi non porta alcuna didascalia, quindi non è mai reale. Su un documento senza didascalia ottieni invece il nome del file, e solo"[Document]"quando non c’è nemmeno quello. Quindi su un documento,captionuguale afilenamesignifica che non c’era didascalia.
Nota: Posizioni e contatti non sono strutturati.
typeè"location", ma il payload portatext.bodycon una frase —Location: 12.97, 77.59 (Head office) - MG Road, dove le parti di nome e indirizzo compaiono solo se WhatsApp le ha inviate. I contatti arrivano allo stesso modo, comeContact: Priya Sharma, separati da virgole se più d’uno eUnknownper un contatto senza nome. Ramifica sul tipo; non aspettarti di ricavare campi dal corpo.
Verificare la firma
Ogni consegna è firmata con il segreto di firma del webhook che ti è stato mostrato alla creazione della chiave. Verificala a ogni richiesta: è l’unica cosa che dimostra che la chiamata viene da noi e non da qualcuno che ha indovinato il tuo URL.
| Header | Valore | Formati |
|---|---|---|
X-Webhook-Signature | HMAC-SHA256 di timestamp + "." + rawBody, con chiave il tuo segreto di firma del webhook, in esadecimale minuscolo. | Solo WizMessage |
X-Webhook-Timestamp | Timestamp Unix in secondi. Fa parte della stringa firmata — rifiuta le consegne più vecchie di qualche minuto per impedire i replay. | Solo WizMessage |
X-Webhook-Event | Il nome dell’evento, corrispondente alla tabella qui sopra. | Entrambi |
X-Webhook-Id | Id univoco di questo tentativo di consegna. | Entrambi |
Nota: Una chiave impostata sul formato Meta Graph firma in modo diverso —
X-Hub-Signature-256, sul corpo grezzo senza timestamp, esattamente come fa Meta. Gli ultimi due header qui sopra vengono comunque inviati, quindi il contratto di deduplicazione non cambia. Vedi Verificare la firma su quella pagina, e tieni separati i due verificatori se esegui entrambi i formati sullo stesso server.
Firma il corpo grezzo della richiesta esattamente come ricevuto. Interpretare il JSON e riserializzarlo cambia l’ordine delle chiavi e la spaziatura, e la firma non corrisponderà mai.
const crypto = require('node:crypto')
// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
const timestamp = req.get('X-Webhook-Timestamp')
const provided = req.get('X-Webhook-Signature')
const expected = crypto
.createHmac('sha256', WEBHOOK_SIGNING_SECRET)
.update(timestamp + '.' + req.body) // req.body is 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, 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
Nota: Questo è un segreto diverso e una derivazione della chiave diversa rispetto alla firma delle richieste descritta sopra. I webhook in uscita usano come chiave il segreto di firma del webhook stesso; le richieste API in entrata usano come chiave
SHA256(api_secret). Usare quello sbagliato è la causa abituale di una firma che non corrisponde mai.
Quando il tuo endpoint non restituisce 2xx
Attendiamo fino a 10 secondi per una risposta, e non seguiamo mai i reindirizzamenti.
| La tua risposta | Che cosa facciamo |
|---|---|
2xx | Consegnato. Fatto. |
5xx, 408, 429, timeout, errore di connessione | Riprovato — dopo 1 s, 5 s, 30 s, poi 5 min. Cinque tentativi in totale, poi l’evento viene abbandonato. |
Qualsiasi altro 4xx (400, 401, 403, 404…) | Errore permanente. Non viene riprovato. Se il tuo controllo della firma rifiuta una consegna, quell’evento è perso. |
410 Gone | I webhook vengono disattivati su questa chiave. Non viene inviato più nulla finché non li riattivi dalla dashboard. Restituiscilo solo se lo intendi davvero. |
Poiché un 4xx non viene mai riprovato, preferisci restituire 2xx e mettere il lavoro in coda dal tuo lato. Riserva il rifiuto agli input davvero errati.
Riferimento API REST
Tutto quanto precede serve a configurare la chiave. Questo è ciò che i tuoi sviluppatori chiameranno davvero. L’URL di base è /api/v1/external. Ogni endpoint richiede le intestazioni di autenticazione indicate di seguito ed è soggetto ai limiti di velocità della chiave.
Autenticazione
Invia la tua chiave API a ogni richiesta. Se sulla chiave è attiva l’opzione «Require signature», devi anche firmare la richiesta — e una chiave con questa opzione attiva rifiuta senza appello qualsiasi chiamata non firmata.
| Intestazione | Valore |
|---|---|
X-API-Key | La tua chiave API — il valore pk_live_… completo, non solo il prefisso mostrato nella dashboard. |
X-Timestamp | Timestamp Unix in secondi. Rifiutato se si discosta di oltre 5 minuti dall’ora del server. |
X-API-Signature | HMAC-SHA256 di timestamp + "." + rawBody, con chiave SHA256(api_secret), in esadecimale minuscolo. |
Nota: Le firme vengono verificate solo quando sulla chiave è attivo require_signature. In caso contrario, la sola chiave API è sufficiente per inviare messaggi — ed è esattamente per questo che la chiave è un segreto, non un identificatore. Trattala come una password: viene mostrata una sola volta e chiunque la possieda può scrivere ai tuoi clienti.
const crypto = require('node:crypto')
const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()
const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
.update(timestamp + '.' + body)
.digest('hex')
await fetch('https://your-host/api/v1/external/messages/text', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': API_KEY,
'X-Timestamp': timestamp,
'X-API-Signature': signature,
},
body,
})
Endpoint
| Metodo | Percorso | Scopo |
|---|---|---|
POST | /messages/text | Invia un messaggio di testo semplice. Funziona solo all’interno di una finestra di conversazione aperta di 24 ore. |
POST | /messages/template | Invia un template fornendo tu stesso l’array components grezzo di Meta. |
POST | /messages/template/send | Invia un template usando la mappatura che hai configurato nella dashboard. È questo l’endpoint da usare. |
POST | /messages/interactive/list | Invia un messaggio con elenco interattivo. |
POST | /messages/interactive/button | Invia fino a tre pulsanti di risposta. |
GET | /messages/:uuid | Verifica lo stato di consegna di un messaggio che hai inviato. |
POST | /media/upload | Carica un PDF, un’immagine o un video su Meta e ottieni un media_id da usare nell’intestazione di un template. |
GET | /templates | Elenca i template disponibili per questa chiave. |
GET | /templates/:name | Recupera i dettagli di un singolo template. |
Due id, e come distinguerli
Ogni invio riuscito restituisce entrambi gli id. Non sono intercambiabili, e il campo chiamato message_id non significa la stessa cosa in una risposta e in un webhook.
{
"success": true,
"data": {
"message_id": "85db3ac6-de11-48ed-9730-a38cc410dc79",
"whatsapp_message_id": "wamid.HBgMOTE4MjgxMTI2OTU2FQIAERgUQ0Uz…",
"status": "sent"
}
}
| Id | Che cos’è | A che cosa serve |
|---|---|---|
message_id | Nostro. L’identificativo sotto cui è archiviato questo invio. | GET /messages/:uuid — passa questo valore. |
whatsapp_message_id | L’id proprio di WhatsApp (un wamid). | Far combaciare i webhook: è ciò che arriva come data.message_id su message.sent, message.reaction, message.delivered, message.read e message.failed. |
Quindi il data.message_id di un webhook corrisponde al whatsapp_message_id della risposta, non al suo message_id. Se ne conservi uno solo, conserva whatsapp_message_id — oppure imposta un tuo reference, che viene restituito su ogni webhook ed è la cosa più semplice su cui indicizzare.
Nota: I webhook di stato possono portare anche
data.provider_message_id. WhatsApp ha iniziato a ricodificare gli id dei messaggi a metà della loro vita, quindi l’id che mette su un report di consegna non è sempre quello che ti aveva dato al momento dell’invio. Lo risolviamo noi per te —data.message_idè sempre l’id del momento dell’invio che già hai.provider_message_idè il valore grezzo di WhatsApp, utile per i ticket di assistenza; non usarlo per fare corrispondenze.
Inviare un template mappato
Questo è il payload che si abbina alla scheda «Templates». Le variabili si inviano per NOME — i nomi mostrati come chip sulla card del template — e la piattaforma assembla per te i components di Meta. È tutto qui il senso di mappare un template: il tuo sistema di fatturazione non ha bisogno di sapere nulla del formato dei componenti di Meta.
POST /api/v1/external/messages/template/send
{
"to": "+12025550147",
"template_name": "wiz_tutorial_appointment_reminder",
"language": "en",
"variables": {
"customer_name": "Ananya Iyer",
"appointment_date": "14 Nov, 11:30 AM"
},
"reference": "booking-2026-1114"
}
Nota: I nomi delle variabili devono corrispondere esattamente alla mappatura — un nome non riconosciuto viene ignorato, mentre l’assenza di uno obbligatorio comporta un rifiuto con 400.
referenceè a tua disposizione: viene restituito nei webhook, così puoi collegare una conferma di consegna a un record del tuo sistema.
Limiti di velocità
Ogni chiave ha i propri limiti, visibili nella scheda «Overview» — per impostazione predefinita 60 richieste al minuto e 1.000 messaggi al giorno. Le risposte indicano il margine residuo: rallenta quando si sta esaurendo, invece di ostinarti a riprovare contro un muro.
Inviare file con l’API
Entro una finestra aperta di 24 ore il tuo software può inviare un file direttamente — senza template e senza approvazione. Un solo endpoint copre documenti, immagini, video e audio.
Cosa puoi inviare
Il type indicato nella richiesta determina i limiti. Qualcosa di più grande, o in un formato non elencato, viene rifiutato prima di arrivare a WhatsApp.
| Tipo | Formati | Dimensione max | Didascalia | Nome file |
|---|---|---|---|---|
document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt | 100 MB | ✓ | ✓ |
image | jpg, jpeg, png, webp | 5 MB | ✓ | — |
video | mp4, 3gp | 16 MB | ✓ | — |
audio | aac, amr, mp3, ogg, m4a | 16 MB | — | — |
POST /api/v1/external/messages/media
{
"to": "+919876543210",
"type": "document",
"link": "https://example.com/invoice-2026-0817.pdf",
"filename": "Invoice 2026-0817.pdf",
"caption": "Your invoice for August",
"reference": "invoice-2026-0817"
}
Carica una volta, invia molte
Se invii ripetutamente lo stesso file — listino, catalogo, PDF di condizioni — caricalo una volta e conserva l’id. Resta valido 30 giorni ed evita a WhatsApp di riscaricare il tuo URL a ogni messaggio.
POST /api/v1/external/messages/media
{
"to": "+919876543210",
"type": "image",
"media_id": "1234567890",
"caption": "This month’s catalogue"
}
Quando un invio viene rifiutato
- Fuori dalla finestra di 24 ore. I media liberi richiedono una conversazione aperta. Invia invece un template approvato — vedi la guida alla casella condivisa per capire come funziona la finestra.
- La chiave non ha
send_media. Controlla i chip dei permessi nella scheda Overview della chiave. - Didascalia su un audio. WhatsApp non la mostra, quindi viene rifiutata anziché scartata in silenzio.
- Nome file su qualcosa che non sia un documento. Solo i documenti mostrano un nome.
- Né
media_idnélink. Ne serve esattamente uno.
Nota: Puoi provare tutto questo senza scrivere codice. Apri la chiave, premi Test API e scegli
POST /messages/mediadall’elenco degli endpoint — il body è precompilato e «Get code» scrive la stessa richiesta in otto linguaggi.
Leggere i file che ti inviano
Quando un cliente ti invia una foto o un PDF, il webhook ti dà un id media — non un link. Questo endpoint trasforma quell’id nel file vero e proprio.
Lo dice anche la scheda Webhooks della chiave, ogni volta che l’endpoint è iscritto a un evento che può portare un file.

Perché nel payload non c’è alcun URL
image.id è l’identificativo che Meta dà al file, ed è l’unica cosa che WhatsApp mette nel webhook. Trasformarlo in byte richiede due passaggi che non puoi eseguire da solo: chiedere a Meta un URL temporaneo, per cui serve il token aziendale del tuo account WhatsApp, e poi scaricare da quell’URL, per cui serve di nuovo lo stesso token. L’URL inoltre è valido solo per circa cinque minuti. Una chiave API non possiede né il token né l’URL, ed è proprio questo il divario che l’endpoint colma.
Scaricare il file
Il corpo della risposta è il file — non c’è alcuna busta JSON intorno. Gli errori sono comunque JSON, nella forma consueta, quindi ramifica sul codice di stato invece di provare a interpretare ogni risposta.
curl -sS -o invoice.pdf -D headers.txt \
-H "X-API-Key: $API_KEY" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-API-Signature: $SIGNATURE" \
https://wizmessage.com/api/v1/external/media/4603890099896453
| Header della risposta | Che cosa contiene |
|---|---|
Content-Type | Il tipo che Meta dà al file, oppure application/octet-stream quando Meta non ne ha inviato uno. |
Content-Length | Solo quando Meta ne ha dichiarato uno. Non pretenderlo — vedi la nota sul troncamento più sotto. |
Cache-Control | private, max-age=300. La risposta è specifica della tua chiave; non metterla mai in una cache condivisa. |
Content-Disposition | inline; filename="<the media id>" — non il nome originale del file. Per un documento il nome vero è arrivato sul webhook come document.filename; salva il file con quello. |
Quanto dura un id media
È il dettaglio che manda in crisi le integrazioni scritte mesi prima. L’id che ricevi su un webhook non dura quanto quelli che crei tu.
Scarica ciò che ti serve e conserva i byte dal tuo lato. Trattare l’id media come un riferimento permanente funziona per una settimana e poi smette in silenzio.
Quando un download viene rifiutato
Gli errori tornano nella busta standard — { "success": false, "error": { "code", "message" } }.
| Stato | code | Che cosa è successo |
|---|---|---|
400 | INVALID_MEDIA_ID | Non è un id media di Meta. Controllato prima di tutto il resto, quindi nulla è stato chiamato. |
401 | INVALID_API_KEY, INVALID_SIGNATURE, TIMESTAMP_EXPIRED… | I soliti errori di autenticazione, identici a ogni altro endpoint. |
403 | PERMISSION_DENIED | La chiave non ha view_messages. Spuntalo nel modulo di modifica della chiave. |
404 | MEDIA_NOT_FOUND | Sconosciuto, scaduto oltre i 7 giorni, o appartenente a un altro account. Sono deliberatamente indistinguibili — una risposta diversa per ciascuno confermerebbe che un id esiste. |
404 | COEXT_ACCOUNT_NOT_FOUND | L’account WhatsApp dietro questa chiave non esiste più. |
400 | COEXT_ACCOUNT_NOT_CONFIGURED, PHONE_NUMBER_ID_MISSING, BUSINESS_TOKEN_MISSING | L’account non è in uno stato che gli consenta di parlare con WhatsApp. Sistemalo nella dashboard — riprovare non servirà. |
413 | MEDIA_TOO_LARGE | Più grande del limite di 32 MB, quando la dimensione è nota in anticipo. Vedi sotto. |
429 | RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED | Un download consuma il margine della chiave esattamente come un invio. |
502 | MEDIA_DOWNLOAD_FAILED | L’host dei file di WhatsApp ha risposto con qualcosa che non era il file. Vale la pena riprovare. |
Nota: Il limite di dimensione produce un
413pulito solo quando WhatsApp ci comunica la dimensione in anticipo. Quando non lo fa, il limite viene applicato mentre il file è in streaming — e a quel punto il200e i suoi header sono già stati inviati, quindi la connessione semplicemente termina in anticipo. Ottieni un file troncato con stato200e nessun corpo di errore. Confronta i byte ricevuti conContent-Lengthogni volta che è presente, e tratta una lettura troncata come un fallimento, non come un file.
Altre tre cose da sapere prima di costruirci sopra:
- Il limite di 32 MB è più basso di quello di WhatsApp. Un documento può arrivare a 100 MB, quindi un file che puoi inviare con questa API non è necessariamente uno che puoi rileggere tramite essa.
- I download contano sulla tua quota — sia il limite al minuto sia quello giornaliero. Scaricare i media di mille messaggi in entrata esaurisce da solo la giornata di una chiave predefinita.
- Una
GETnon ha un corpo da firmare. Se la tua chiave richiede le firme, l’HMAC su questo endpoint copre il solo timestamp. Dimostra comunque che possiedi la chiave e limita i replay a cinque minuti, ma non autentica l’id media né il percorso.
Nota: A differenza degli endpoint di invio, questo non compare nella finestra Test API — quello strumento copre solo gli endpoint
POST. Per provarlo a mano, prendi un id media da un webhook che hai già ricevuto e usa ilcurlqui sopra; il file finisce in quello che indichi con-o.
Reazioni
Una reazione è l’emoji che qualcuno appoggia su un singolo messaggio — 👍 su una conferma d’ordine, ❤️ su una foto. Non è un messaggio a sé: ne indica uno. Il tuo software può leggere le reazioni mentre avvengono, e inviarne.
Un evento, tre origini
Una reazione può arrivare dal tuo cliente, dal titolare che la tocca sul telefono dell’app Business, o dal tuo software tramite l’API. Tutte e tre arrivano sullo stesso evento message.reaction, quindi un solo handler copre ogni caso — direction e source ti dicono quale hai davanti.
Com’è fatto un webhook di reazione
Qui un cliente aggiunge 👍 a un messaggio che gli hai inviato.
{
"version": 1,
"event": "message.reaction",
"timestamp": "2026-08-01T09:14:22.031Z",
"data": {
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjkz…",
"direction": "inbound",
"from": "+919876543210",
"to": "+911122334455",
"reaction": {
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
"emoji": "👍",
"action": "added"
},
"contact": {
"name": "Priya Sharma",
"wa_id": "919876543210"
}
}
}
In quel payload ci sono due message_id e non significano la stessa cosa. È il campo che merita una seconda lettura.
| Campo | Che cos’è |
|---|---|
data.message_id | L’id della reazione stessa — non quello del messaggio a cui si è reagito. |
data.reaction.message_id | Il wamid del messaggio a cui si è reagito. È quello da confrontare con i tuoi record. |
data.reaction.emoji | L’emoji. Stringa vuota quando la reazione è stata rimossa. |
data.reaction.action | added o removed. Deriva dall’emoji, quindi ci puoi ramificare direttamente sopra. |
data.direction | inbound — ha reagito il cliente. outbound — è stata l’azienda. |
data.source | Solo in uscita: mobile (telefono dell’app Business) o api (il tuo software). Assente in entrata. |
data.from / data.to | Relativi alla direzione, come per message.sent: in entrata è cliente → azienda, in uscita è azienda → cliente. |
data.reference | Solo sulle reazioni inviate dal tuo software, e solo se ne hai fornita una. |
data.contact, data.user_id, data.username | Solo in entrata — chi ha reagito. Assenti su ogni reazione in uscita. |
Nota:
data.fromdi solito è il numero di telefono del cliente, ma WhatsApp non ne invia sempre uno. Quando non lo fa, ricevi il suo id utente WhatsApp — tratta quindifromcome un identificatore, non come un numero che puoi sempre chiamare.
Aggiungere e rimuovere una reazione
Rimuovere una reazione è un evento a sé, con emoji vuoto e action: "removed".
{
"event": "message.reaction",
"data": {
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSN0U3…",
"direction": "inbound",
"reaction": {
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
"emoji": "",
"action": "removed"
}
}
}
Ogni tocco è un messaggio WhatsApp distinto, con un id proprio. Reagire con 👍, cambiarlo in ❤️ e poi toglierlo del tutto produce tre eventi, e nessuno sostituisce gli altri nel tuo archivio. Indicizza su data.reaction.message_id e tieni il più recente — quella è la reazione attuale del messaggio.
Inviare una reazione dal tuo software
Lo stesso endpoint aggiunge e rimuove. Quale delle due dipende soltanto dal fatto che tu invii un’emoji.
POST /api/v1/external/messages/reaction
{
"to": "+919876543210",
"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
"emoji": "👍",
"reference": "invoice-2026-0817"
}
Qui message_id è l’id di WhatsApp — il whatsapp_message_id di una risposta di invio, o il data.reaction.message_id di un webhook. Non è mai uno dei nostri uuid; vedi Due id, e come distinguerli se non sei sicuro di quale hai in mano. Le reazioni usano il permesso send_text, quindi qualsiasi chiave che può scrivere al cliente può reagire.
Nota: Una reazione non produce mai
message.deliverednémessage.read. WhatsApp non li emette per una reazione — l’unico evento successivo possibile èmessage.failed, quando la reazione viene rifiutata. Cercarla conGET /messages/:uuidfunziona come per qualsiasi altro invio.
Quando una reazione viene rifiutata
Alcuni rifiuti avvengono qui, prima che qualcosa raggiunga WhatsApp. Restituiscono un errore alla tua chiamata API e non producono alcun webhook — non c’è nulla da riferire, perché non è stato inviato nulla.
- Alla chiave manca
send_text.403. Le reazioni riutilizzano quel permesso; non ce n’è un altro da concedere. tonon è in formato E.164.422. Lo stesso formato+…di ogni altro endpoint.message_idmanca o è vuoto.422. Fino a 255 caratteri.emojimanca.422. Per rimuovere una reazione invia"emoji": ""— invia il campo vuoto, non ometterlo. Fino a 16 caratteri.
Il resto avviene su WhatsApp, dopo che abbiamo accettato la chiamata. Ricevi prima un 200 e un webhook message.reaction, poi un message.failed con l’errore 131009 quando WhatsApp la rifiuta.
- Il messaggio ha più di 30 giorni. È il limite di WhatsApp per reagire, non il nostro — noi non controlliamo l’età.
- Il messaggio non appartiene a questa conversazione. Un
wamiddi un’altra chat, o uno dei nostri uuid passato per errore. - Il messaggio è stato eliminato, o è a sua volta una reazione. Non si può reagire a una reazione.
Nota: Se l’invio fallisce subito invece di essere rifiutato dopo, ricevi un
500e unmessage.failedil cuidata.message_idè il nostro uuid, non unwamid— non c’è alcun id WhatsApp da riferire, perché WhatsApp non l’ha mai accettato.
Nota: Come per ogni altro endpoint, puoi provarlo senza scrivere codice. Apri la chiave, premi Test API e scegli
POST /messages/reaction— reagisci a un messaggio sul tuo telefono e guarda arrivare il webhook.
Inviare schede contatto
Una scheda contatto è una vCard: un nome, più tutto ciò che gli associ — numeri di telefono, e-mail, un indirizzo postale, un’azienda. WhatsApp la mostra come una scheda che il destinatario può toccare per salvarla sul telefono. Presentare a un cliente il suo referente, la filiale più vicina o il tecnico reperibile è proprio a questo che serve, ed è meglio che digitare un numero in un messaggio di testo dove potrebbe non essere nemmeno toccabile.
L’unico campo obbligatorio
name.formatted_name — il nome mostrato sulla scheda. È tutto ciò che serve. Tutto il resto, numero di telefono compreso, per WhatsApp è facoltativo.
Troverai guide che insistono sul fatto che debba accompagnarlo un nome o un cognome. Quella regola appartiene alla vecchia API on-premises di Meta, ormai dismessa. Sulla Cloud API una scheda che porta solo formatted_name viene accettata e consegnata.
Se il destinatario può rispondere
Un campo facoltativo cambia ciò che la scheda può fare. phones[].wa_id è l’id WhatsApp del contatto — il numero di telefono senza + né spazi. Se lo fornisci, la scheda acquisisce un pulsante Message che apre una chat con quella persona. Se lo ometti, la scheda può solo essere salvata.
Inviarne una
Questo endpoint accetta senza modifiche il corpo della richiesta di Meta. Una chiamata contacts scritta per la Cloud API — dalla documentazione di Meta, o da codice che già esegui — viene inviata qui senza cambiare altro che l’URL.
POST /api/v1/external/messages/contacts
{
"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" }
}
],
"reference": "ticket-88214"
}
Ottieni la stessa busta di ogni altro invio — message_id, whatsapp_message_id, status — e seguono i soliti webhook message.sent, message.delivered e message.read. Il payload di message.sent porta message.type: "contacts" e le schede che hai inviato, quindi un handler che registra ciò che è uscito non ha bisogno di casi speciali oltre alla lettura di quel campo.
| Campo | Obbligatorio | Che cos’è |
|---|---|---|
messaging_product | no | whatsapp. Di Meta, e qui ridondante — l’URL dice già che cos’è. Accettato perché un corpo Graph non richieda modifiche; rifiutato se dice altro. |
recipient_type | no | individual. Stessa storia. |
type | no | contacts. Stessa storia. Un corpo che dichiara un altro tipo viene rifiutato anziché corretto in silenzio. |
to | sì | Il destinatario. O le sole cifre di Meta (919876543210) o +E.164 (+919876543210) — questo endpoint accetta entrambi. |
contacts | sì | Un array. Da una a dieci schede per messaggio. |
contacts[].name.formatted_name | sì | Il nome sulla scheda. Fino a 255 caratteri. |
contacts[].name.* | no | first_name, last_name, middle_name, prefix, suffix. |
contacts[].phones[] | no | phone, type, wa_id. type è un’etichetta libera — WORK, HOME, CELL, quella che usi. |
contacts[].emails[] | no | email, type. |
contacts[].addresses[] | no | street, city, state, zip, country, country_code, type. |
contacts[].urls[] | no | url, type. |
contacts[].org | no | company, department, title. |
contacts[].birthday | no | YYYY-MM-DD. WhatsApp rifiuta qualsiasi altro formato. |
reference | no | Un tuo id, restituito sui webhook di questo invio. |
Nota: Dieci schede per messaggio è un limite nostro, non di WhatsApp — WhatsApp ne accetta fino a 257 ma consiglia di inviarne molte meno, perché un muro di schede sembra spam e si guadagna il blocco che ne segue. Se te ne servono davvero di più, invia più messaggi.
Nota: I campi che non riconosciamo vengono scartati anziché rifiutati. Un refuso come
nicknameomobilenon fa fallire la chiamata — la scheda semplicemente arriva senza quel dato. Controlla la tabella qui sopra se qualcosa che hai inviato manca sul telefono.
Quando un invio di contatti viene rifiutato
Alcuni rifiuti avvengono qui, prima che qualcosa raggiunga WhatsApp. Restituiscono un errore alla tua chiamata API e non producono alcun webhook message.sent — non è stato inviato nulla.
- Fuori dalla finestra di 24 ore. Una scheda contatto è un messaggio libero e non esiste un template per i contatti, quindi non può aprire una conversazione — può solo continuarne una. Invia prima un template approvato.
- Alla chiave manca
send_text.403. Le schede contatto riutilizzano quel permesso; non ce n’è un altro da concedere, e nulla da cambiare sulle chiavi esistenti. tonon è un numero di telefono.422. Cifre, con o senza un+iniziale; niente spazi, trattini o parentesi. Nota che questo endpoint è più indulgente degli altri, che pretendono il+.- La busta si contraddice.
422.type: "image"omessaging_product: "sms"su questo percorso è un errore che vale la pena segnalarti, quindi viene rifiutato anziché sovrascritto. contactsè vuoto, o ne contiene più di dieci.422.- Una scheda non ha
name.formatted_name.422. È l’unico campo che pretendiamo.
Il resto avviene su WhatsApp, dopo che abbiamo accettato la chiamata. Tornano come un 500 che porta il messaggio di WhatsApp stesso, e un webhook message.failed — un birthday malformato e un wa_id rifiutato finiscono qui anziché essere intercettati prima.
Nota: A differenza degli altri endpoint, questo non è ancora in Test API né in Get code — quelli coprono solo testo, template e media. Finché non lo sarà, invia una richiesta reale verso un numero che possiedi per provarlo.