Inviare messaggi con WhatsApp Cloud API

Da Maggio 2022 Meta ha rilasciato, per la sua piattaforma WhatsApp Business, le Cloud API consentendo alle aziende di tutte le dimensioni di integrare il famoso sistema di messaggistica in base alle proprie necessità.

On-premise API VS Cloud API

La grande differenza tra le On-premise API e le Cloud API sta principalmente nell-hosting che ospita le WhatsApp Business API.

Quando parliamo di On-premise API stiamo parlando di una soluzione tecnica ospitata in un server BSP (Business Solutions Provider) che, generalmente, era gestito da aziende partner di WhatsApp. Questo era il tipo di modello disponibile inizialmente e prevedeva che l’azienda che necessita del servizio, si rivolgesse direttamente a un BSP per ottenere WhatsApp API .
Ovviamente, con questo tipo di soluzione, si andavano ad aggiungere ai costi dell’invio dei messaggi, anche i costi del BSP.

Da qui Meta ha deciso di rendere disponibili le WhatsApp Business API in modo diretto, tramite le Cloud API. Questo modello ospita le API direttamente sul server Cloud di Meta e, in questo modo, non è necessario l’intervento di terze parti come i BSP. In questo caso anche i costi si ridurranno, perchè si dovranno pagare solamente le tariffe per messaggio inviato o conversazione, mentre i costi di hosting sono a carico di Meta.
Qui è possibile trovare la lista dei prezzi basati sulle conversazioni: link.

In  questa guida, per ovvi motivi, prenderemo in considerazione le WhatsApp Cloud API.

Cosa ci serve

Prima di tutto è necessario specificare una cosa molto importante, ossia la registrazione di un numero di telefono per l’utilizzo con le WhatsApp API rende impossibile l’utilizzo dell’applicazione WhatsApp (o WhatsApp Business). Le API non forniscono un’interfaccia di front-end. Le aziende che utilizzano queste API, per utilizzare un’interfaccia per la chat, devono utilizzare soluzioni sviluppate in loco oppure da servizi esterni. Questo perchè, ricordiamolo, la soluzione Cloud API è dedicata alle aziende medio-grandi e fornisce funzionalità specifiche che non sono presenti nella versione WhatsApp classica, come la possibilità di inviare template in modo massivo, oppure la possibilità di avere un team di collaboratori o agenti di vendita che utilizzano lo stesso numero di telefono nella stessa azienda.

Chiarito questo, veniamo al sodo. Cosa ci serve per inviare un primo messaggio con WhatsApp?

• Un account Meta
• Un Business Manager aziendale verificato e con associato un metodo di pagamento
• L’accesso alla piattaforma Meta for Developers
• Un numero di telefono non associato a WhatsApp

Vediamo nel dettaglio i passaggi per configurare il tutto.

Configurazione App in Meta

Per configurare l’API Cloud di WhatsApp, accedi o registrati all’account Facebook per sviluppatori e fai clic su Crea app.

Seleziona Business dall’elenco del tipo di applicazione che vogliamo creare.
Di seguito fornisci informazioni base sulla tua attività commerciale. Se non ne hai uno, puoi lasciare la casella di selezione Account Business Manager non selezionata.

Fai clic su Crea app per essere reindirizzato alla dashboard Meta.

Seleziona WhatsApp e fai clic su Configura

Per poter utilizzare l’API Cloud di WhatsApp è necessario accettare i termini e le condizioni del servizio. Se non si possiede un account Business Manager, non è necessario selezionarlo, come già fatto in precedenza, poiché Facebook creerà automaticamente un account aziendale successivamente.

Per verificare che l’integrazione dell’API sia avvenuta correttamente, WhatsApp invierà un messaggio di prova al numero che inserirai nel menù “To” utilizzando il numero di test che vedi nel menù “From” dello Step 1.

Per procedere con il test puoi cliccare sul bottone Send message dello Step 2.

Nota: questo test è semplicemente una prova di invio da un numero fittizio al tuo numero personale tramite Cloud API per verificare il corretto funzionamento e invio tramite questo canale. Procedi nella lettura per scoprire come associare un numero di telefono alle Cloud API e poter inviare messaggi tramite questo.

La fase successiva è quella decisiva, perchè andremo finalmente a  registrare il numero di telefono che vuoi utilizzare per inviare messaggi tramite API.

Scorri fino allo Step 5 della schermata e fai clic su Aggiungi numero di telefono per collegare un numero di telefono al tuo account API Cloud WhatsApp.

Per continuare la configurazione dell’API Cloud WhatsApp, è necessario inserire tutte le informazioni relative alla tua attività commerciale e premere su Avanti. Durante la procedura sarà necessario completare tutti i campi richiesti, fino a quando non ti verrà chiesto di associare un numero di telefono all’account dell’API Cloud WhatsApp.

META ti invierà un codice di verifica a 6 cifre per confermare il numero di telefono associato. Una volta ricevuto, è necessario inserirlo per completare la procedura di verifica.

Ora vai allo Step 1. Se tutto è stato impostato correttamente dovresti trovare nell’elenco il nuovo numero aggiunto.

Ripassa allo Step 2 della procedura per inviare un messaggio template di prova dal numero che hai aggiunto. Se ricevi il messaggio da questo numero, allora significa che è in grado di inviare messaggi WhatsApp tramite le Cloud API!

Ben fatto, abbiamo terminato la configurazione generale dell’app WhatsApp di Meta.

Message Template

A questo punto penserai di sapere tutto ciò che ti serve per inviare il primo messaggio con le Cloud API ma, in realtà, occorre prima conoscere un altro importante concetto: i message Templates (modelli di messaggio).

Come puoi leggere nella documentazione ufficiale, i modelli di messaggi di WhatsApp sono messaggi predefiniti utilizzati dalle aziende per inviare notifiche o rispondere alle richieste dei clienti. Possono includere promemoria per appuntamenti, informazioni sulla spedizione, risoluzione dei problemi ecc.

Ma a cosa servono nel nostro caso? Servono a iniziare una conversazione. Infatti per i modelli di messaggi sono utilizzati per avviare una conversazione con i clienti, rappresentano l’unico tipo di messaggio che può essere inviato ai clienti che non hanno ancora iniziato una conversazione con te o che non ti hanno inviato un messaggio negli ultimi 24 ore in una conversazione esistente.

A prima occhiata potrebbe sembrare una politica un po’ restrittiva, perchè non è concesso inviare messaggi di testo in modo diretto a utenti che non ci hanno mai scritto prima. Tuttavia in seconda analisi è bene tenere presente che questo tipo di comportamento è necessario per garantire agli utenti un sistema sicuro per essere contattati dall’azienda. Basti pensare che l’algoritmo di Meta controlla i modelli di messaggio prima di approvarli e assegna una valutazione sulla qualità delle conversazioni che ne scaturiscono. Se per esempio creiamo un modello di messaggio e lo spammiamo in continuazione alla nostra lista utenti, la qualità della conversazione media andrà a diminuire, con tutte le conseguenze che ne deriveranno per il nostro account.

Detto questo, creiamo il nostro primo message template nella sezione Meta WhatsApp Manager del nostro business manager di Meta. L’operazione è molto semplice ma se non sai come fare ti consiglio di leggere queste due guide:

• Modelli di messaggi
• Creazione di modelli di messaggi per l’account WhatsApp Business

Non ci resta  che avviare la nostra prima conversazione inviando il template che abbiamo appena creato!

Invio del Template

Per inviare un Template dobbiamo eseguire una chiamata in POST al seguente end point:

In primo luogo andiamo a recuperare alcuni dati che ci servono per autenticare la chiamata:

• ID_NUMERO_TELEFONO: Lo troviamo nell’app di Meta che abbiamo creato precedentemente, precisamente nello Step 1 della procedura “Getting started”
• TOKEN_ACCESSO: Troviamo questo Token di accesso all’inizio della sezione “Getting started”

Utilizzeremo Postman per testare l’invio, in questo modo avremo la possibilità di eseguire le chiamate a prescindere dal linguaggio di programmazione specifico.

Selezioniamo il metodo POST e incolliamo l’url con le dovute modifiche. Impostiamo l’header in questo modo:

Impostiamo il Body su “raw”, formato JSON e incolliamo questo codice:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "NUMERO_DI_TELEFONO_A_CUI_INVIARE",
  "type": "template",
  "template": {
    "name": "NOME_DEL_TEMPLATE",
    "language": {
    "code": "CODICE_LINGUA"
    },
  }
}

• NUMERO_DI_TELEFONO_A_CUI_INVIARE rappresenta il numero che riceverà il modello di messaggio
• NOME_DEL_TEMPLATE rappresenta il nome del modello di messaggio
• CODICE_LINGUA rappresenta la lingua del modello di messaggio. Se abbiamo creato un template per la lingua italiana sarà semplicemente “it“

{
  "messaging_product": "whatsapp",
  "contacts": [{
    "input": "PHONE_NUMBER",
    "wa_id": "WHATSAPP_ID",
  }]
  "messages": [{
    "id": "wamid.ID",
  }]
}

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "NUMERO_DI_TELEFONO_A_CUI_INVIARE",
  "type": "template",
  "template": {
  "name": "NOME_DEL_TEMPLATE",
  "language": {
    "code": "CODICE_LINGUA"
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "TESTO_VARIABILE"
        },
      ]
    }
  ]
}

• components rappresenta la lista delle componenti del modello di messaggio, per esempio header o body
• parameters rappresenta la lista dei parametri, per esempio text, currency o date_time
• TESTO_VARIABILE rappresenta la stringa di testo che assumerà la nostra variabile {{1}}

Invio del messaggio

Bene, fin’ora abbiamo visto come inviare un Template o modello di messaggio, ma come si invia un normale messaggio di testo tramite WhatsApp Cloud API?

Innanzitutto è bene ricordare che per far sì che l’utente veda il messaggio di testo deve prima rispondere al Template che gli abbiamo inviato, in questo modo la conversazione è consderata aperta e possiamo scrivere tranquillamente.

L’invio del messaggio è molto semplice, possiamo utilizzare lo stesso end-point che abbiamo utilizzato per inviare i Templates (metodo POST):

Configuriamo header con il nostro Token di accesso come abbiamo visto precedentemente e inseriamo nel body questo Json:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "NUMERO_DI_TELEFONO_A_CUI_INVIARE",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "STRINGA_MESSAGGIO"
  }
}

Come si può notare in questo caso andiamo a specificare il recipient_type come messaggio individuale e il tipo testo. Questo è sufficiente a dare l’indicazione alle Cloud API che vogliamo inviare un messaggio testuale.
Se sono stati inseriti i dati corretti, cliccando Send,  vedrai il tuo messaggio (STRINGA_MESSAGGIO) recapitato correttamente al numero WhatsApp NUMERO_DI_TELEFONO_A_CUI_INVIARE.

Ti consiglio anche di dare un’occhiata alla documentazione ufficiale per l’invio dei messaggi (Invio di messaggi) perchè ci sono molti altri tipi di messaggi che possono essere inviati con le WhatsApp Business Cloud API.

Approfondimenti

WhatsApp Business Platform Cloud API
FAQs
Cloud API Error Codes