Dopo aver registrato un account sviluppatore Meta e ottenuto la chiave API, per chiamare l’endpoint ufficiale (come https://graph.facebook.com/v19.0/<PHONE_NUMBER_ID>/messages) con una richiesta POST, è necessario includere le intestazioni Authorization: Bearer <ACCESS_TOKEN> e Content-Type: application/json e inviare il messaggio in formato JSON (es: {"messaging_product":"whatsapp","to":"886912345678","text":{"body":"Messaggio di prova"}}). Si noti che il limite di frequenza è di 200 messaggi al secondo.

Registrazione dell’account e ottenimento delle credenziali

Secondo i dati ufficiali di Meta, oltre 5 milioni di aziende utilizzano attualmente la WhatsApp Business API per la comunicazione con i clienti, con un tempo medio di risposta ridotto a​​meno di 3 minuti​​ e un tasso di apertura dei messaggi fino al​​98%​​. Il processo di registrazione richiede solitamente​​1-3 giorni lavorativi​​, ma la scelta di un canale rivenditore può ridurlo a​​meno di 2 ore​​. Di seguito sono riportati i dettagli operativi specifici:

Innanzitutto, vai alla piattaforma ufficiale per sviluppatori di Meta (developers.facebook.com), fai clic su “Crea App” e seleziona il tipo “Azienda”. Il sistema richiederà il nome dell’applicazione (si consiglia il nome inglese dell’azienda), l’e-mail di contatto (che deve corrispondere al dominio aziendale) e la selezione di “WhatsApp” come prodotto principale. È importante notare che il nome dell’applicazione, una volta inviato,​​non può essere modificato​​, e ogni account aziendale può creare al massimo​​5 applicazioni​​. Dopo la registrazione di base, la piattaforma genererà un​​ID app di 64 caratteri​​ (App ID) e un​​segreto app di 32 caratteri​​ (App Secret). Questi due codici devono essere scaricati e salvati immediatamente, poiché il segreto viene visualizzato una sola volta.

Il passo successivo è la verifica dell’azienda. L’azienda deve caricare documenti commerciali ufficiali (licenza commerciale, certificato di registrazione fiscale o certificato di registrazione della società). Il formato del file è limitato a PDF/JPG/PNG e la dimensione non deve superare i​​5MB​​. Il tempo di revisione è generalmente di​​24-72 ore​​, ma collaborando con un BSP (Business Solution Provider) certificato, è possibile saltare questo passaggio e utilizzare il loro canale veloce. Dopo l’approvazione, il sistema abiliterà l’accesso all’API e fornirà un​​Token di Accesso di base permanentemente valido​​ (Access Token). Questo token ha una validità predefinita di​​90 giorni​​, ma può essere esteso tramite un meccanismo di refresh periodico.

Dopo aver ottenuto il token di base, è necessario associare un numero di telefono. Ogni applicazione può associare un massimo di​​25 numeri​​, e il numero deve essere un numero fisico non ancora registrato con WhatsApp Business (si consiglia l’acquisto di una nuova SIM). Durante l’associazione, è necessario pagare una​​tariffa mensile fissa​​ (a seconda del paese, circa​​0,5-5 dollari USA​​) e ricevere un​​codice di verifica a 6 cifre​​ tramite SMS o chiamata vocale. Dopo aver completato l’associazione, la piattaforma genererà un​​URL endpoint API dedicato​​ (che include un parametro crittografato a 128 bit). Questo URL è la credenziale principale per tutte le chiamate API successive.

Infine, è necessario configurare Webhook per la ricezione dei messaggi. Il server deve supportare il​​protocollo HTTPS​​ e la crittografia​​TLS 1.2 o superiore​​, e l’intervallo minimo di push di ogni messaggio può essere impostato a​​100 millisecondi​​. Si consiglia di pre-configurare un bilanciatore di carico, poiché Meta richiede che il tempo di risposta del server sia inferiore a​​300 millisecondi​​, altrimenti attiverà un meccanismo di riprova (massimo 3 tentativi, con intervallo di 5 minuti ciascuno). Dopo aver completato tutte le impostazioni, ricordarsi di attivare la “Modalità di debug API” nel backend. Questa registrerà i​​dati JSON originali​​ di tutte le richieste, facilitando la successiva risoluzione dei problemi. Il costo totale dell’intero processo è di circa​​15-50 dollari USA​​ (esclusa la tariffa mensile del numero). Se gestito tramite un rivenditore, di solito viene aggiunta una​​tassa di servizio tecnico una tantum di 50-100 dollari USA​​.

Configurazione dei permessi di accesso API

Secondo le statistiche ufficiali di Meta, oltre il 30% dei fallimenti delle chiamate API deriva da errori di configurazione dei permessi. La corretta configurazione dei permessi può aumentare il tasso di consegna dei messaggi dal 75% medio al 99,8% e ridurre la velocità di risposta a meno di 500 millisecondi. La configurazione dei permessi include 4 livelli principali: Livello Aziendale (Business Level), Livello App (App Level), Livello Numero (Phone Level) e Livello Funzionalità (Feature Level). Ogni livello di permesso richiede una revisione indipendente, con un tempo totale di revisione di circa 2-6 ore. Di seguito sono riportati i dettagli operativi specifici:

Innanzitutto, accedi al backend Meta for Developers e trova la scheda “Permessi” in “Impostazioni App”. Qui verranno visualizzati 13 interruttori di permesso di base. I permessi fondamentali che devono essere abilitati includono:​​messages​​ (invio e ricezione di messaggi),​​contacts​​ (lettura dei contatti),​​webhooks​​ e​​message_templates​​ (messaggi modello). Dopo aver abilitato ciascun permesso, è necessaria una revisione separata. Il permesso per i messaggi modello è il più rigoroso, di solito richiede la fornitura di almeno 3 contenuti di messaggi predefiniti (massimo 1024 caratteri ciascuno) e la spiegazione della frequenza di invio (ad esempio, massimo 200 messaggi all’ora).

È necessario prestare particolare attenzione al processo di associazione del​​permesso del numero di telefono​​. Ogni numero deve essere associato ai corrispondenti permessi operativi API, tra cui: la possibilità di inviare file multimediali (immagini/video/documenti), la possibilità di effettuare chiamate vocali, la possibilità di inviare informazioni sulla posizione. Il permesso multimediale è disabilitato per impostazione predefinita. Per abilitarlo è necessario caricare una descrizione del tipo di file (ad esempio, limitato a formato jpg/png, dimensione singola non superiore a 16MB). Il permesso vocale è aperto solo agli account che hanno superato la verifica aziendale e ogni chiamata costa un minimo di 0,015 dollari USA.

La configurazione di Webhook è il nodo chiave nella configurazione dei permessi. È necessario inserire l’URL di callback HTTPS preparato in precedenza nel campo “Webhook” (si consiglia di utilizzare un server proxy inverso Nginx) e impostare 6 tipi di eventi da ricevere:​​message​​ (ricezione messaggi),​​status​​ (aggiornamento stato),​​template​​ (stato modello),​​contact​​ (cambio contatto),​​location​​ (aggiornamento posizione),​​error​​ (registro errori). Il server deve rispondere con un codice di stato 200 OK entro 3 secondi, altrimenti il server Meta attiverà un meccanismo di riprova (massimo 5 tentativi, con intervallo di 15 minuti ciascuno).

Di seguito sono riportati gli standard di configurazione dei parametri per le principali categorie di permessi:

Nelle “Impostazioni Avanzate” è possibile personalizzare il limite di chiamate API al minuto/ora/giorno. Il valore predefinito è 1000 richieste al minuto (può essere aumentato a 10000 richieste al minuto in base alle esigenze aziendali). Si consiglia di abilitare la​​modalità di scaling automatico​​. Quando il volume di richieste supera l’80% del valore impostato per 5 minuti consecutivi, il sistema aumenterà automaticamente la quota di capacità del 20%. Tutte le modifiche ai permessi vengono registrate in tempo reale nel registro di controllo, che può tracciare tutte le operazioni negli ultimi 180 giorni. Dopo aver completato la configurazione, assicurarsi di fare clic sul pulsante “Simulazione test permessi”. Il sistema eseguirà automaticamente 25 elementi di rilevamento, con un tempo di rilevamento di circa 8 minuti. Il tasso di superamento deve raggiungere il 100% per abilitare ufficialmente il servizio API.

Scrittura del codice per l’invio dei messaggi

Secondo i dati effettivi della WhatsApp Business API, il codice di invio correttamente ottimizzato può aumentare il tasso di consegna dei messaggi dal 92% al 99,7% e ridurre il tempo medio di risposta a meno di 800 millisecondi. Un modulo di invio standard include solitamente 5 moduli principali: Modulo di Autenticazione, Modulo di Costruzione del Payload, Modulo di Crittografia, Modulo di Invio (Dispatching) e Modulo di Riprova (Retry Mechanism). Il tempo di esecuzione di ciascun modulo dovrebbe essere controllato entro 200 millisecondi. Di seguito sono riportati i dettagli di implementazione specifici:

Nel Modulo di Autenticazione, è necessario includere 3 set di parametri chiave nell’intestazione di ogni richiesta HTTP: l’intestazione Authorization deve utilizzare il formato Bearer Token (lunghezza 64 caratteri), Content-Type deve essere impostato su application/json e deve includere il numero di versione API (ad esempio, v17.0). La validità del Token è solitamente di 24 ore. Dopo la scadenza, è necessario aggiornarlo tramite il processo OAuth 2.0 (il token di refresh ha una validità di 60 giorni). Si consiglia di implementare un meccanismo automatico di refresh del token nel codice. Quando viene rilevato il codice di errore 401, il processo di refresh viene attivato automaticamente. Questo processo richiede solitamente 1500 millisecondi per essere completato.

Il Modulo di Costruzione del Payload deve seguire rigorosamente la struttura JSON specificata da Meta. Un payload di messaggio di testo standard include 12 campi obbligatori e 8 campi opzionali, con una dimensione totale non superiore a 10KB. Di seguito è riportato un confronto della struttura dei principali tipi di messaggio:

Nota speciale: tutti i file multimediali devono essere prima caricati sul server Meta per ottenere un ID multimediale (lunghezza 26 caratteri). Questo processo di caricamento richiede solitamente 3-5 secondi (a seconda delle dimensioni del file). L’ID multimediale ottenuto è valido per 30 giorni e può essere riutilizzato.

Il Modulo di Crittografia richiede la crittografia end-to-end utilizzando il protocollo TLS 1.2 o superiore. Si consiglia di utilizzare l’algoritmo AES-256-GCM per crittografare il corpo del messaggio. La lunghezza della chiave deve raggiungere i 256 bit. Ogni richiesta deve generare un Vettore di Inizializzazione (IV, 12 byte di lunghezza) e un Tag di Autenticazione (Authentication Tag, 16 byte di lunghezza) univoci. Il processo di crittografia dovrebbe essere completato localmente e il ritardo aggiunto dall’intero processo di crittografia e decrittografia dovrebbe essere controllato entro 300 millisecondi.

Il Modulo di Invio deve gestire i problemi di instabilità della rete. Si consiglia di impostare un meccanismo di timeout a 3 livelli: Timeout di Connessione impostato a 3 secondi, Timeout di Scrittura impostato a 5 secondi e Timeout di Lettura impostato a 10 secondi. Quando il server restituisce un errore 5xx, il meccanismo di riprova dovrebbe essere attivato immediatamente (massimo 3 tentativi, con intervallo incrementale: 2 secondi per il primo, 4 secondi per il secondo, 8 secondi per il terzo). Allo stesso tempo, è necessario monitorare la frequenza delle chiamate API e aderire rigorosamente al limite di frequenza di base di 1 messaggio al secondo (può essere richiesto un aumento a 5 messaggi al secondo).

Test del flusso di invio dei messaggi

Secondo i dati effettivi del settore, i sistemi di invio di messaggi WhatsApp non sufficientemente testati presentano un tasso medio di fallimento di consegna del 12%, mentre i sistemi che hanno superato un processo di test completo possono ridurre il tasso di fallimento a meno dello 0,3%. Un ciclo di test completo richiede solitamente 72 ore e comprende 3 fasi principali: test unitari (la copertura deve raggiungere il 95%), test di integrazione (simulando 1000 utenti concorrenti) e test di stress (in esecuzione continua per 24 ore). Durante il processo di test, è necessario monitorare 17 indicatori chiave, i più importanti dei quali includono il tasso di successo della consegna, il tempo medio di risposta e il picco del tasso di errore. Di seguito sono riportati i dettagli specifici sull’implementazione dei test:

Innanzitutto, quando si imposta l’ambiente di test, è necessario utilizzare l’ambiente sandbox fornito da Meta. Questo ambiente è completamente isolato dall’ambiente di produzione ma identico nelle funzionalità. L’ambiente sandbox supporta la simulazione di un massimo di 50 numeri di test, e ogni numero può inviare 1000 messaggi di prova gratuiti al mese. Durante il test, è necessario configurare credenziali API dedicate. Queste credenziali sono valide per 30 giorni e possono essere utilizzate solo nell’ambiente sandbox. Si consiglia di utilizzare strumenti di test automatizzati per costruire script di test che simulino il comportamento reale degli utenti: invio di messaggi di testo (60% del totale), messaggi multimediali (25% del totale) e messaggi modello (15% del totale).

Impostazione delle soglie degli indicatori di test chiave: Tasso di successo della consegna deve essere ≥99,5%, Tempo medio di risposta deve essere ≤1200 millisecondi, Tasso di errore deve essere ≤0,2%, Disponibilità del sistema deve essere ≥99,9%. Per ogni indicatore è necessario impostare una soglia di avviso (allarme quando si raggiunge l’80% del limite) e una soglia di pericolo (interruzione immediata del test quando si raggiunge il 95% del limite).

Nella fase di test funzionale, è necessario verificare 8 scenari chiave: invio normale di messaggi, messaggi con allegati, invio di massa di messaggi, revisione dei messaggi modello, ricezione di callback di stato, meccanismo di gestione degli errori, attivazione del limite di frequenza e logica di riprova automatica. Ogni scenario deve essere eseguito con almeno 200 casi di test, per un totale di test non inferiore a 1600. È necessario prestare particolare attenzione al test dei messaggi modello, poiché ciò richiede la presentazione del modello per l’approvazione in anticipo (tempo di revisione 2-48 ore). Il test deve coprire tutti i formati di variabile supportati: variabili di testo (massimo 10), variabili di valuta (supporta 42 valute), variabili di data/ora (supporta 12 formati) e variabili multimediali (supporta immagini e documenti).

Il test delle prestazioni dovrebbe essere eseguito in tre livelli di intensità: prima un test di carico di base (simulando l’invio di 5 messaggi al secondo, della durata di 1 ora), poi un test di carico di picco (simulando 20 messaggi al secondo, della durata di 30 minuti), e infine un test di resistenza (simulando 10 messaggi al secondo, in esecuzione continua per 24 ore). Durante questo processo, devono essere registrati 17 indicatori di prestazione del sistema, tra cui: Utilizzo della CPU (dovrebbe essere inferiore al 70%), Utilizzo della memoria (dovrebbe essere inferiore all’80%), Throughput di rete (dovrebbe raggiungere 100Mbps), Tempo di risposta del database (dovrebbe essere inferiore a 50 millisecondi). Prestare particolare attenzione al comportamento del sistema quando raggiunge il limite di carico, assicurandosi che il tasso di errore non aumenti improvvisamente oltre il 5%.

La fase di test in ambiente reale deve scegliere 3 diversi periodi di tempo: dalle 10:00 alle 12:00 nei giorni feriali (periodo di punta), dalle 20:00 alle 22:00 (periodo di sub-punta) e dalle 2:00 alle 4:00 del mattino (periodo di bassa punta). Ogni periodo dura 2 ore e il volume totale di invio è controllato entro 500 messaggi. Durante il test, monitorare in tempo reale lo stato dei messaggi, registrando il tempo medio da inviato a consegnato (dovrebbe essere entro 3 secondi) e il tempo medio da consegnato a letto (solitamente fluttua entro 60 secondi). Allo stesso tempo, verificare il meccanismo di callback: assicurarsi che il 100% degli aggiornamenti di stato venga correttamente inviato a Webhook e che il ritardo di elaborazione sia inferiore a 500 millisecondi.