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