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.

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.

1. ▶ Dove si trovano le tue chiavi API
2. ▶ Una chiave non ancora completa

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.

1. ▶ Passo 1 — Che cosa stai collegando?
2. ▶ Passo 2 — Scegli il messaggio
3. ▶ Passo 3 — Dove devono arrivare le risposte?
4. ▶ Passo 4 — Vai in produzione

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

1. ▶ Panoramica

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.

1. ▶ 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.

1. ▶ Template
2. ▶ Leggere le variabili — l’unica cosa su cui vale la pena rallentare

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

Osserva la card payment_failed_alert. Il suo messaggio presenta {{1}}, poi {{3}}, poi {{2}} — nel testo i segnaposto NON seguono l’ordine numerico. I chip sottostanti sono invece elencati in ordine numerico: customer_name riempie {{1}}, renewal_date riempie {{2}}, plan_name riempie {{3}}. Abbina i tuoi valori al NUMERO, mai all’ordine in cui i segnaposto compaiono nella frase. È l’errore più frequente con i template tradotti, dove l’ordine delle parole sposta i segnaposto.

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.

1. ▶ «Try it» — invia un test senza scrivere codice
2. ▶ Che cosa restituisce un invio simulato
3. ▶ «Get code» — la richiesta, già scritta per te
4. ▶ Cambiare linguaggio
5. ▶ «Edit» — cambia ciò che invia il tuo sistema
6. ▶ Test API — lo stesso strumento, qualsiasi endpoint
7. ▶ Webhook — ricevere le risposte

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. Nota che le variabili di questo template si chiamano ancora body_1, body_2, body_3 — è 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. Dalla scheda «Webhooks» indirizza un webhook verso un tuo endpoint HTTPS e WizMessage 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.

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.

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.

Riferimento API REST

Tutto quanto precede serve a configurare la chiave. Questo è ciò che i tuoi sviluppatori chiameranno davvero. L’URL di base è https://wizmessage.com/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.

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://wizmessage.com/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

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": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

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.

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.
• La chiave non ha send_media. Controlla i 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.

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.

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.

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