WhatsApp Business API

Fino a qualche tempo fa le WhatsApp business API erano destinate unicamente ad aziende di grandi dimensioni. Per accedervi era necessario utilizzare servizi di terze parti: Zapier, Twillio e simili. Oggi è possibile integrare soluzioni basate su WhatsApp Business Api virtualmente per ogni tipo di impresa, l’unica limitazione è l’attitudine tecnica per l’implementazione.

Per prima cosa cominciamo a definire i requirements…

• Un numero telefonico dedicato a WhatsApp Business API (Può essere benissimo un numero telefonico Virtuale ma deve supportare integrazione con WhatsApp).
• Un Webhook al quale WhatsApp invia al backend dell’utente i messaggi inviati dall’interlocutore.
• Una logica di invio dei messaggi da parte dell’utente all’API di Meta.

L’implementazione delle WhatsApp API parte dal portale sviluppatori di meta: https://developers.facebook.com

Qui lo sviluppatore deve accedere con i suoi dati di accesso a facebook, o con i dati di accesso della sua impresa o alternativamente, se lavora per un’impresa, questa deve condividere le risorse di amministrazione del profilo WhatsApp API con il profilo facebook dello sviluppatore.

Una volta effettuato l’accesso bisogna creare una nuova App.

Aggiungiamo un nuovo numero di telefono e lo autentichiamo (riceveremo un messaggio contenente un codice da inserire nella sezione developers).

Io consiglio sempre di avere un file di enviroment variables (.env) protetto da scrittura e lettura pubblica incapsulato in modo che solamente il backend possa accedervi attraverso un metodo dedicato.

Sviluppando in PHP vi consiglio la libreria composer vlucas/phpdotenv

Si richiama all’interno della classe in questo modo:


use DotenvDotenv;
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();


Una volta registrato il numero dobbiamo recuperare questi parametri:

WHATSAPP_VERIFY_TOKEN={un token che creiamo noi arbitrariamente ma che ci servirà per iscriverci al servizio}
WHATSAPP_ACCESS_TOKEN=(il token staccato dal developers portal di facebook)
WHATSAPP_PHONE_NUMBER_ID=(l’id che facebook associa al nostro numero di telefono precedentemente registrato)
WHATSAPP_NUMBER=(il numero di telefono che abbiamo registrato)

Una nota importante… Il numero di telefono registrato su WhatsApp Business API non può essere poi utilizzato anche per utilizzare WhatsApp su Cellulare.
L’utente a quel punto può scegliere se memorizzare i messaggi su database per rispondere attraverso un’interfaccia Web oppure se aggiungere un LLM addestrato che si occupi di rispondere autonomamente all’interlocutore.

In questo articolo vedremo proprio questa casualità.

Una volta ottenuti tutti questi dati, dobbiamo andare a inviare il nostro primo messaggio verso una numerazione telefonica (ad esempio il nostro numero personale).

Nella console di Facebook developers bisognerà recarsi nel menù WhatsApp -> Configurazione API (dove abbiamo creato il nostro token).
Apro qui una breve parentesi. Il token di accesso staccato da questa interfaccia è un token a scadenza della durata di 60 giorni. Se si vuole generare un Token dalla durata illimitata bisogna registrare l’utente come Utente di Sistema da business.facebook.com concedergli le risorse di amministrazione per l’app che abbiamo creato in developers e staccare un token con scadenza illimitata.

Da qui inseriamo il nostro prefisso telefonico e il numero del nostro cellulare personale dove vogliamo ricevere il primo messaggio e cliccando su Invia Messaggio se tutto è stato impostato correttamente dovremmo ricevere il messaggio WhatsApp.

In basso, al passaggio 2 facebook fornisce anche una istruzione cURL per l’invio dei messaggio che possiamo riutilizzare per creare un metodo di invio dei messaggi con cURL verso l’endpoint di WhatsApp API.

Abbiamo gestito la parte in cui siamo noi ad inviare un messaggio. Dobbiamo gestire la parte in cui è l’utente a mandare un messaggio a noi.

Ci spostiamo su Webhook e nella select selezioniamo come Product: Whatsapp Business Account

Qui dovremo inserire il nostro URL di Callback che corrisponde all’URI del nostro Webhook.

Come token di verifica inseriamo il token che abbiamo creato nella variabile d’ambiente WHATSAPP_VERIFY_TOKEN nel file .env.

Cliccando su verifica e salva WhatsApp chiamerà la nostra API per verificare che il Webhook sia attivo e funzionante ed iscriverlo correttamente al servizio.

Se vogliamo osservare cosa ci sta inviando WhatsApp consiglio di utilizzare tecniche di reverse-proxy, ad esempio utilizzando Ngrok e sostituendo l’indirizzo del Webhook con quello fornito da Ngrok.

Il Webhook è il punto in cui avviene la magia. Possiamo limitarci a scrivere i messaggi ricevuto in un database con un timestamp, oppure possiamo istruire una rete neurale in OpenAI per far rispondere un LLM alle domande dell’utente per le quali il modello custom trained è stato istruito. A seconda della natura del tema di cui dovrà occuparsi è possibile anche utilizzare i modelli nativi di OpenAI (per compiti non troppo impegnativi consiglio il modello 4o-mini che è il meno costoso. Il costo è di circa 0.15 euro per milione di Token di Input e di 0.60 euro per milione di Token di output alla data odierna. In una semplice chat si arriva a spendere un euro dopo migliaia di messaggi scambiati considerando una media di 500 token totali per ogni richiesta.

Non abbiamo ancora parlato dei costi di WhatsApp…

Per le chat aperte dai clienti, il servizio è completamente gratuito in una sessione di 24 ore. In WhatsApp infatti le sessione che vengono aperte hanno una durata di 24 ore prima di scadere. Se siamo noi ad aprire una chat verso un cliente il costo per sessione è di circa 5 centesimi di euro per sessione aperta verso un numero univoco. Una volta aperta la sessione non ha importanza il numero di messaggi inviati. WhatsApp conteggia unicamente la sessione.

Per fare un esempio pratico… Se un nostro cliente richiede informazioni al nostro bot alle 13:00 del 12 aprile 2025 è lui che sta aprendo una sessione che sarà gratuita e che scadrà alle 12:59:59 del 13 aprile 2025. Se risponderemo al messaggio dopo questo orario apriremo noi una nuova sessione che diventa a pagamento (5 centesimi di euro) per poter scambiare tutti i messaggi che vogliamo fino alle 24 ore successive. Se al termine delle 24 ore invieremo un ulteriore messaggio verrà aperta una nuova sessione al costo di 5 centesimi.

In buona sostanza il costo delle conversazioni su WhatsApp Business API dipende unicamente da chi sta aprendo la sessione. Un cliente? Costo zero. Noi che sfruttiamo le API? 5 centesimi a sessione di 24 ore.

Sulle API di WhatsApp è inoltre possibile avviare delle procedure guidate, ad esempio è possibile identificare l’utente che sta richiedendo informazioni attraverso un form di login. Questa procedura sfrutta i WhatsApp Flows che saranno argomento di un articolo dedicato.

[starbox]