Vai al contenuto
42 min read

Collegare il tuo software a WhatsApp

Genera una chiave API, mappa un template WhatsApp approvato, indirizza un webhook verso il tuo server e chiama l’API REST — la guida completa alla Gestione API.

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.

Video guidato — 18 passi, 1:18. Scegli un passo per passare direttamente a quella parte.

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.

Le due superfici API e quando scegliere ciascunaWizMessage APIdocumentata in questa paginavariabili del template con nomeinterfaccia di mappatura, campo referenceendpoint di consultazione dello statoMeta Graph APIha una pagina a partecorpi ed errori di Metawebhook nel formato di Metanessun livello di mappaturaNessuna delle due è deprecata. Un account può usarle entrambe contemporaneamente.
Stesse chiavi, stessi permessi, stessi limiti di velocità. Scegli per ogni integrazione.

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.

Dove si trovano le tue chiavi API

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.

Una chiave non ancora completa

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 1 — Che cosa stai collegando?

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 2 — Scegli il messaggio

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 3 — Dove devono arrivare le risposte?

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.

Passo 4 — Vai in produzione

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.

Panoramica

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.

PermessoChe cosa controlla
send_textPOST /messages/text, /messages/reaction, /messages/contacts, /messages/interactive/list, /messages/interactive/button
send_templatePOST /messages/template, /messages/template/send
send_mediaPOST /messages/media
view_templatesGET /templates, /templates/:name
view_messagesGET /media/:media_id
manage_templatesSolo Meta Graph API — creazione ed eliminazione dei template
manage_profileSolo Meta Graph API — profilo aziendale, codici QR, impostazioni commerce, elenco dei bloccati, impostazioni del telefono, flow
view_analyticsSolo 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/upload non richiede alcun permesso — send_media regola l’invio di un file a un cliente, non il caricamento di uno sui server di Meta. Nemmeno GET /messages/:uuid ne 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 restituire 403, 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.

Una chiave ancora da configurare

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.

Template

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.

Leggere le variabili — l’unica cosa su cui vale la pena rallentare

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.

«Try it» — invia un test senza scrivere codice

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.

Che cosa restituisce un invio simulato

«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.

«Get code» — la richiesta, già scritta per te

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.

Cambiare linguaggio

«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.

«Edit» — cambia ciò che invia il tuo sistema

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.

Test API — lo stesso strumento, qualsiasi endpoint

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.

Webhook — ricevere le risposte

Quali eventi ricevi

Seleziona gli eventi che questo endpoint deve ricevere. Ciascuno arriva come POST a sé stante.

EventoQuando si attiva
message.receivedUn cliente ti ha inviato un messaggio.
message.reactionQualcuno 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.deliveredIl messaggio ha raggiunto il dispositivo del destinatario.
message.readIl destinatario l’ha aperto.
message.failedL’invio o la consegna è fallita; data.error ne riporta il motivo.

Nota: message.received e le message.reaction in 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.sent con il body "[Unsupported message type]". Ora arrivano come message.reaction con direction: "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.delivered e message.read sono spunte separate da message.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"
		}
	}
}
CampoSempre presente?Che cos’è
data.message_idSìIl wamid del messaggio in entrata.
data.toSì — ma sempre vuotoVedi la nota qui sotto.
data.messageSìIl blocco descritto in Quale blocco ricevi.
data.fromSolo quando WhatsApp ha inviato un numeroIl numero di telefono del cliente.
data.user_idSolo quando WhatsApp ne ha inviato unoL’id utente WhatsApp del cliente.
data.usernameSolo quando il cliente ne ha unoIl nome utente WhatsApp del cliente.
data.contactSolo 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 su message.received. Il destinatario è il tuo numero aziendale, che già conosci. Non usarlo come chiave e non generalizzare: su message.sent lo 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.

Le tre forme che può assumere il blocco di un messaggio in entrataSimile al testotext · interactive · buttonleggi text.bodyMediaimage · video · audiodocument · stickerun blocco con il nome del tipoche contiene un id mediaPosizione · contattiil tipo lo indicama il corpo è prosain text.bodySolo la famiglia dei media porta un id che puoi scaricare. Le altre due sono testo da leggere direttamente.
Ramifica su message.type, poi leggi il blocco che quel tipo indica.

Per i media, il blocco porta l’identità del file — mai un URL:

CampoSu quali tipiChe cos’è
idTutti i mediaL’ID media di Meta. Scarica i byte con esso — vedi Leggere i file che ti inviano.
mime_typeTutti i mediaIl tipo reale, image/jpeg o application/pdf.
sha256Tutti i media, quando WhatsApp lo inviaHash del contenuto. Utile per deduplicare lo stesso file inviato due volte.
filenameSolo documentiIl nome com’era sul dispositivo del mittente. È il nome con cui salvare il file.
captionTutti i mediaLa didascalia del mittente — o un segnaposto. Leggi la nota qui sotto prima di fidarti.

Nota: caption può 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, caption uguale a filename significa che non c’era didascalia.

Nota: Posizioni e contatti non sono strutturati. type è "location", ma il payload porta text.body con 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, come Contact: Priya Sharma, separati da virgole se più d’uno e Unknown per 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.

HeaderValoreFormati
X-Webhook-SignatureHMAC-SHA256 di timestamp + "." + rawBody, con chiave il tuo segreto di firma del webhook, in esadecimale minuscolo.Solo WizMessage
X-Webhook-TimestampTimestamp Unix in secondi. Fa parte della stringa firmata — rifiuta le consegne più vecchie di qualche minuto per impedire i replay.Solo WizMessage
X-Webhook-EventIl nome dell’evento, corrispondente alla tabella qui sopra.Entrambi
X-Webhook-IdId 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 rispostaChe cosa facciamo
2xxConsegnato. Fatto.
5xx, 408, 429, timeout, errore di connessioneRiprovato — 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 GoneI 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.

IntestazioneValore
X-API-KeyLa tua chiave API — il valore pk_live_… completo, non solo il prefisso mostrato nella dashboard.
X-TimestampTimestamp Unix in secondi. Rifiutato se si discosta di oltre 5 minuti dall’ora del server.
X-API-SignatureHMAC-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

MetodoPercorsoScopo
POST/messages/textInvia un messaggio di testo semplice. Funziona solo all’interno di una finestra di conversazione aperta di 24 ore.
POST/messages/templateInvia un template fornendo tu stesso l’array components grezzo di Meta.
POST/messages/template/sendInvia un template usando la mappatura che hai configurato nella dashboard. È questo l’endpoint da usare.
POST/messages/interactive/listInvia un messaggio con elenco interattivo.
POST/messages/interactive/buttonInvia fino a tre pulsanti di risposta.
GET/messages/:uuidVerifica lo stato di consegna di un messaggio che hai inviato.
POST/media/uploadCarica un PDF, un’immagine o un video su Meta e ottieni un media_id da usare nell’intestazione di un template.
GET/templatesElenca i template disponibili per questa chiave.
GET/templates/:nameRecupera 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"
	}
}
IdChe cos’èA che cosa serve
message_idNostro. L’identificativo sotto cui è archiviato questo invio.GET /messages/:uuid — passa questo valore.
whatsapp_message_idL’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.

I due modi per allegare un file a un messaggio mediaPOST /messages/medialinkun URL pubblico che passiamo a WhatsAppscaricato a ogni invioideale per file che già ospitimedia_idcarica il file una volta, riusa l’idvalido 30 giorniideale per lo stesso file inviato spessoIl link deve essere raggiungibile pubblicamente: è WhatsApp a scaricarlo, non il tuo server a inviarlo.
Ogni invio media ne porta esattamente uno. Se li invii entrambi, vince media_id.

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.

TipoFormatiDimensione maxDidascaliaNome file
documentpdf, doc, docx, xls, xlsx, ppt, pptx, txt100 MB✓✓
imagejpg, jpeg, png, webp5 MB✓—
videomp4, 3gp16 MB✓—
audioaac, amr, mp3, ogg, m4a16 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.

Caricare un file una volta e inviarlo ripetutamentePOST /media/uploadil file stessomedia_idvalido 30 giorniPOST /messages/mediainvialo quante volte vuoiConsegnatoi webhook riportano l’esito
L’id è riutilizzabile fino alla scadenza; si ripete solo il passaggio di invio.
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_id né link. Ne serve esattamente uno.

Nota: Puoi provare tutto questo senza scrivere codice. Apri la chiave, premi Test API e scegli POST /messages/media dall’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.

L’elenco degli eventi webhook con una nota che spiega che gli eventi media portano un id da scaricare, non un link

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.

Trasformare in file un id media ricevuto da un webhookmessage.receivedun cliente invia un fileid mediaun identificativo, non un linkGET /media/:media_idla tua chiave API, il tuo permessoIl filebyte grezzi, tipo di MetaRichiede view_messages. Il token WhatsApp dell’account non lascia mai la nostra parte.
L’id è tutto ciò che ti dà il webhook. Una sola chiamata autenticata lo trasforma in byte.

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 rispostaChe cosa contiene
Content-TypeIl tipo che Meta dà al file, oppure application/octet-stream quando Meta non ne ha inviato uno.
Content-LengthSolo quando Meta ne ha dichiarato uno. Non pretenderlo — vedi la nota sul troncamento più sotto.
Cache-Controlprivate, max-age=300. La risposta è specifica della tua chiave; non metterla mai in una cache condivisa.
Content-Dispositioninline; 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.

Per quanto tempo ogni tipo di id media resta scaricabileQuanto tempo hai per scaricarloDa un webhookun cliente ti ha inviato un filescaricabile per 7 giorniconserva il file, non l’idDa /media/uploadl’hai caricato turiutilizzabile per 30 giornisi può conservare e reinviareDipende dalla conservazione di Meta, non dalla nostra — sul lato webhook è stata ridotta da 30 a 7 giorni nell’ottobre 2025.
Due tipi di id media, due durate diverse.

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" } }.

StatocodeChe cosa è successo
400INVALID_MEDIA_IDNon è un id media di Meta. Controllato prima di tutto il resto, quindi nulla è stato chiamato.
401INVALID_API_KEY, INVALID_SIGNATURE, TIMESTAMP_EXPIRED…I soliti errori di autenticazione, identici a ogni altro endpoint.
403PERMISSION_DENIEDLa chiave non ha view_messages. Spuntalo nel modulo di modifica della chiave.
404MEDIA_NOT_FOUNDSconosciuto, scaduto oltre i 7 giorni, o appartenente a un altro account. Sono deliberatamente indistinguibili — una risposta diversa per ciascuno confermerebbe che un id esiste.
404COEXT_ACCOUNT_NOT_FOUNDL’account WhatsApp dietro questa chiave non esiste più.
400COEXT_ACCOUNT_NOT_CONFIGURED, PHONE_NUMBER_ID_MISSING, BUSINESS_TOKEN_MISSINGL’account non è in uno stato che gli consenta di parlare con WhatsApp. Sistemalo nella dashboard — riprovare non servirà.
413MEDIA_TOO_LARGEPiù grande del limite di 32 MB, quando la dimensione è nota in anticipo. Vedi sotto.
429RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDEDUn download consuma il margine della chiave esattamente come un invio.
502MEDIA_DOWNLOAD_FAILEDL’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 413 pulito 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 il 200 e i suoi header sono già stati inviati, quindi la connessione semplicemente termina in anticipo. Ottieni un file troncato con stato 200 e nessun corpo di errore. Confronta i byte ricevuti con Content-Length ogni 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 GET non 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 il curl qui 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.

Le tre origini di una reazione e i campi che identificano ciascunaIl tuo clienteha reagito a tedirection: inboundnessun campo sourcecontact dice chi è statoIl telefono Businesslo ha toccato il titolaredirection: outboundsource: mobileIl tuo softwarehai chiamato l’APIdirection: outboundsource: apireference torna indietroSolo le reazioni in entrata portano i dati di contatto — una in uscita è l’azienda, che già conosci.
Un evento, tre origini. Leggi prima direction, poi source.

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.

CampoChe cos’è
data.message_idL’id della reazione stessa — non quello del messaggio a cui si è reagito.
data.reaction.message_idIl wamid del messaggio a cui si è reagito. È quello da confrontare con i tuoi record.
data.reaction.emojiL’emoji. Stringa vuota quando la reazione è stata rimossa.
data.reaction.actionadded o removed. Deriva dall’emoji, quindi ci puoi ramificare direttamente sopra.
data.directioninbound — ha reagito il cliente. outbound — è stata l’azienda.
data.sourceSolo in uscita: mobile (telefono dell’app Business) o api (il tuo software). Assente in entrata.
data.from / data.toRelativi alla direzione, come per message.sent: in entrata è cliente → azienda, in uscita è azienda → cliente.
data.referenceSolo sulle reazioni inviate dal tuo software, e solo se ne hai fornita una.
data.contact, data.user_id, data.usernameSolo in entrata — chi ha reagito. Assenti su ogni reazione in uscita.

Nota: data.from di 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 quindi from come 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.

Come lo stesso endpoint di reazione aggiunge e rimuove una reazionePOST /messages/reactionun’emojil’emoji che vuoi mostrareuna per persona e messaggioaggiunge la reazioneun’emoji vuotacancella quella inviata primainvia il campo, ma vuotola rimuovePer rimuovere una reazione invia emoji come stringa vuota. Omettere il campo viene rifiutato.
Un endpoint, due esiti. Decide il campo 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.delivered né message.read. WhatsApp non li emette per una reazione — l’unico evento successivo possibile è message.failed, quando la reazione viene rifiutata. Cercarla con GET /messages/:uuid funziona 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.
  • to non è in formato E.164. 422. Lo stesso formato +… di ogni altro endpoint.
  • message_id manca o è vuoto. 422. Fino a 255 caratteri.
  • emoji manca. 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 wamid di 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 500 e un message.failed il cui data.message_id è il nostro uuid, non un wamid — 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.

Come wa_id cambia ciò che una scheda contatto può farePOST /messages/contactsphones[].wa_id fornitoWhatsApp conosce questa personail numero, senza + né spaziSalva contatto e Messagewa_id omessosolo i dati di contattonulla con cui aprire una chatSolo salva contattowa_id non viene convalidato da noi. Uno sbagliato produce un pulsante che apre una chat con la persona sbagliata, o con nessuno.
La stessa scheda, con e senza wa_id.

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.

CampoObbligatorioChe cos’è
messaging_productnowhatsapp. Di Meta, e qui ridondante — l’URL dice già che cos’è. Accettato perché un corpo Graph non richieda modifiche; rifiutato se dice altro.
recipient_typenoindividual. Stessa storia.
typenocontacts. Stessa storia. Un corpo che dichiara un altro tipo viene rifiutato anziché corretto in silenzio.
tosìIl destinatario. O le sole cifre di Meta (919876543210) o +E.164 (+919876543210) — questo endpoint accetta entrambi.
contactssìUn array. Da una a dieci schede per messaggio.
contacts[].name.formatted_namesìIl nome sulla scheda. Fino a 255 caratteri.
contacts[].name.*nofirst_name, last_name, middle_name, prefix, suffix.
contacts[].phones[]nophone, type, wa_id. type è un’etichetta libera — WORK, HOME, CELL, quella che usi.
contacts[].emails[]noemail, type.
contacts[].addresses[]nostreet, city, state, zip, country, country_code, type.
contacts[].urls[]nourl, type.
contacts[].orgnocompany, department, title.
contacts[].birthdaynoYYYY-MM-DD. WhatsApp rifiuta qualsiasi altro formato.
referencenoUn 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 nickname o mobile non 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.
  • to non è 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" o messaging_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.