Utilizzo di codici QR e link diretti in WhatsApp
Con i codici QR puoi incorporare con facilità elementi ricchi di informazioni in un'immagine di piccole dimensioni. Li vediamo spesso utilizzati per scopi diversi, ad esempio per fornire maggiori informazioni a chi consulta un volantino o per mettere a disposizione dei commensali il menù di un ristorante.
Fondamentalmente, i codici QR e i link diretti (una versione abbreviata e più leggibile di un link complesso) sono un modo semplice e accessibile per connettersi con il cliente. WhatsApp utilizza codici QR e link diretti per aiutarti a connetterti meglio con i tuoi clienti. Insieme, queste due opzioni consentono ai tuoi clienti di avviare una conversazione con te senza dover inserire un numero di telefono o di accedere rapidamente a informazioni su prodotti, promozioni e altro ancora.
In questo articolo verrà mostrato come generare e utilizzare codici QR e link diretti dalla piattaforma WhatsApp Business utilizzando l'API Cloud, ospitata da Meta. Esamineremo come creare, aggiornare, ottenere ed eliminare un nuovo codice QR o link diretto e mostreremo come inviarli in un messaggio WhatsApp. Puoi consultare in qualsiasi momento il codice completo qui.
Prerequisiti
Per seguire questo tutorial, avrai bisogno di:
un'app WhatsApp nel tuo account sviluppatore di Meta come indicato nella guida Primi passi e dovrai poter inviare un messaggio di testo (configurazione webhook non necessaria);
un token d'accesso utente di sistema con le autorizzazioni necessarie (
whatsapp_business_management, whatsapp_business_messaging e business_management);una conoscenza di base di Node.js ed Express.js.
Inoltre, in questo tutorial saranno utilizzate diverse librerie Node.js (compresa dotenv) per memorizzare la configurazione necessaria per effettuare richieste HTTP con l'API Cloud. Per testare gli endpoint di questa app, userai inoltre Postman. Infine, come base per questo articolo avrai bisogno di questo codice boilerplate.
Configurazione dell'ambiente
Crea e apri un file .env alla radice del progetto e inserisci tutte le variabili mancanti con i valori dei passaggi 1 e 2 dei prerequisiti.
# Your WhatsApp Business app Id APP_ID= # Your WhatsApp Business app secret APP_SECRET= # Recipient phone number without "+" symbol RECIPIENT_PHONE_NUMBER= # Your WhatsApp phone number Id PHONE_NUMBER_ID= # Business Account Id BUSINESS_ACCOUNT_ID= # System User Access Token. Not temporary access token ACCESS_TOKEN= # Cloud API version number VERSION=v15.0 # Override the default app listener port. LISTENER_PORT=3000
Ora che hai aggiunto le variabili di ambiente, avvia l'app utilizzando lo script di scelta rapida npm init, che creerà un'app scheletro.
Creazione di un codice QR e di un link diretto nuovi
Inizi la procedura creando un codice QR e un link diretto nuovi usando l'API Business Management, parte della piattaforma WhatsApp Business.
Come indicato nella documentazione, inizia inviando una richiesta POST all'endpoint /{phone-number-ID}/message_qrdls con tre parametri della query: prefilled_message, generate_qr_image e il tuo access_token.
In questo caso desideri che il codice QR scansionato e il link diretto siano memorizzati nel prefilled_message. Questo consentirà a un utente di inviarti un messaggio precompilato, che può rivelarsi utile per l'assistenza clienti, l'e-commerce, per ottenere un consenso esplicito alla ricezione di messaggi di marketing e altro ancora.
Successivamente, generate_qr_image ti consente di supportare due formati per l'immagine del codice QR generato: .svg o .png. Puoi selezionare il formato che preferisci con il metodo seguente. In questo esempio viene utilizzato .png.
Usando il boilerplate, vai a controllers/qrCode.js e aggiorna il metodo createQRCode con il codice seguente:
const qrdlObject =
{
"prefilled_message" : message,
"generate_qr_image" : type
}
const config =
{
"method" : "post",
"url" : `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/message_qrdls`,
"headers" : {
Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
'Content-Type': 'application/json'
},
"data" : qrdlObject,
};
try
{
await axios( config );
}
catch( error )
{
console.log( "")
}
},
function (err, resp, body) {
if (err) {
console.log("Error!");
} else {
res.json(JSON.parse(body));
}
}
);
};Quindi, devi passare due variabili dal corpo della richiesta: un messaggio (che in seguito verrà utilizzato come prefilled_message) e il formato dell'immagine. Quindi, esegui un test con Postman.
Il corpo della richiesta avrà questo aspetto:
{
"message":"Creating the example QR Code and Short Link",
"type":"png"
}
Premendo il pulsante Send (Invia) nell'angolo in alto a destra, l'API restituirà la risposta mostrata nello screenshot qui sotto. La risposta include deep_link_url, che funge da link diretto, e qr_image_url, che funge da immagine del codice QR. Contiene inoltre id e prefilled_message.
Invio di un messaggio WhatsApp con codice QR e link diretto
Ora potrai inviare ai clienti il codice QR e il link diretto appena generati. Per tale scopo, devi usare l'API Cloud. Come riferimento, puoi seguire gli esempi riportati nell'apposita documentazione. Con l'API, potrai inviare un link diretto come messaggio di testo e un URL immagine come messaggio multimediale.
Messaggi di testo
curl -X POST \
'https://graph.facebook.com/v15.0/BUSINESS_ACCOUNT_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "RECIPIENT_PHONE_NUMBER",
"type": "text",
"text": { // the text object
"preview_url": false,
"body": "MESSAGE_CONTENT"
}
}'Messaggi multimediali
curl -X POST \
'https://graph.facebook.com/v15.0/BUSINESS_ACCOUNT_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "RECIPIENT_PHONE_NUMBER",
"type": "image",
"image": {
"id" : "MEDIA_OBJECT_ID"
}
}'Creerai un metodo che accetta un oggetto request simile ed esegue la richiesta HTTP, che chiamerà l'endpoint /phone_number_id/messages e invierà un messaggio. In controllers/qrCode.js, crea un metodo sendMessage con il codice seguente. Il metodo shell sarà già nel boilerplate.
exports.sendMessage = async (req, res) => {
const { to, type } = req.body;
if (!to || !type) {
return res.status(400).json({
error: "Required Fields: to and type",
});
}
request.post(
{
url: `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/messages`,
headers: {
Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
"content-type": "application/json",
},
body: JSON.stringify(req.body),
},
function (err, resp, body) {
if (err) {
console.log("Error!");
} else {
res.json(JSON.parse(body));
}
}
);
};Quindi, invierai un messaggio con il codice QR appena generato. Copia il qr_image_url e aggiungilo come link di immagine al corpo della richiesta.
Di seguito puoi vedere come appare l'oggetto request in Postman. PHONE_NUMBER_TO_SEND può essere qualsiasi formato componibile.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "RECIPIENT_PHONE_NUMBER",
"type": "image",
"image": {
"link": "https://scontent.fybz2-1.fna.fbcdn.net/m1/v/t6/An95lHumHOGcQ_Fl8cDwVrARmc9T9tmtMLyeTOeSFny-OoLLAqSFHEd8gQzAYVsVS6jNm9IBVU27fcb1H05ERwyb5i87Jtp4fjsNppvFnTu26k7ss_dN8S1ZtkSl6XRZtwB68GUabG8?ccb=10-5&oh=00_AT-LCjyu6J8kkeoW1Qj2rxMZikjrHw0fvwA2C6cn9DYkEA&oe=62C8EC07&_nc_sid=f36290"
}
}
Se ottieni una risposta simile all'immagine qui sotto, il messaggio è stato inviato correttamente.
L'immagine seguente mostra la visualizzazione del messaggio da parte del destinatario:
Quando qualcuno eseguirà la scansione di questo codice QR utilizzando uno smartphone o qualsiasi altro dispositivo, il messaggio verrà precompilato senza l'input dell'utente e sarà avviata una nuova conversazione.
Recupero della lista di codici QR e link diretti esistenti
Ottenere la lista dei codici QR e dei link diretti esistenti è semplice, poiché è sufficiente effettuare una richiesta GET all'endpoint /{phone-number-ID}/message_qrdls . Viene restituito un array di oggetti, in cui i singoli oggetti comprendono code(id), prefilled_message, e deep_link_url.
Nel file controllers/qrCode.js aggiorna il metodo con il codice seguente:
exports.fetchQRCodes = async (req, res) => {
request.get(
{
url: `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/message_qrdls`,
headers: {
Authorization: `Bearer ${process.env.ACCESS_TOKEN}`
}
},
function (err, resp, body) {
if (err) {
console.log("Error!");
} else {
res.json(JSON.parse(body));
}
}
);
};Dopo aver aggiunto il codice, testa l'API con Postman. L'immagine seguente mostra come viene visualizzata la richiesta in Postman:
Una risposta corretta restituisce un array di codici QR e link diretti.
Aggiornamento dei messaggi dei codici QR
Aggiornare un codice QR è molto utile, perché viene aggiornato il messaggio senza modificare l'immagine del codice QR, quindi non dovrai ristampare o ricondividere nuovi codici QR. Questa funzione si rivela particolarmente utile quando nei codici QR vengono memorizzate informazioni come dati di contatto e dettagli promozionali.
Per aggiornare il messaggio del codice QR, devi conoscere il code(id) del codice QR creato, che puoi passare come parametro di query all'endpoint /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .
Nel file controllers/qrCode.js aggiorna il metodo updateQRCode con il codice seguente:
exports.updateQRCode = async (req, res) => {
const { message, qr-code-id } = req.body;
if (!message || !qr-code-id) {
return res.status(400).json({
error: "Required Fields: message and id",
});
}
request.post(
{
url: `https://graph.facebook.com/v14.0/${process.env.META_PHONE_ID}/message_qrdls/${qr-code-id}?prefilled_message=${message}`,
headers: {
Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
"content-type": "application/json",
}
},
function (err, resp, body) {
if (err) {
console.log("Error!");
} else {
res.json(JSON.parse(body));
}
}
);
};Eseguendo il test in Postman, vedrai questo oggetto request:
{
"message":"This is my first Updated QR code",
"id":"4WW67TGNCGPXB1"
}
Una richiesta eseguita correttamente restituisce il codice aggiornato.
Eliminazione di codici QR
Poiché i codici QR non scadono, puoi eliminarli quando le informazioni contenute al loro interno sono obsolete o non più valide.
In primo luogo, devi inviare una richiesta DELETE all'endpoint /{BUSINESS_ACCOUNT_ID}/message_qrdls/{qr-code-id} .
Vai fino a controllers/qrCode.js e aggiorna il metodo deleteQRCode dal metodo shell usando il codice seguente:
exports.deleteQRCode = async (req, res) => {
const { qr_code_id } = req.query;
request.delete(
{
url: `https://graph.facebook.com/${process.env.VERSION}/${process.env.BUSINESS_ACCOUNT_ID}/message_qrdls/${qr_code_id}`,
headers: {
Authorization: `Bearer ${process.env.ACCESS_TOKEN}`
}
},
function (err, resp, body) {
if (err) {
console.log("Error!");
} else {
res.json(JSON.parse(body));
}
}
);
};Qui passi come parametri della query il code id del codice QR che desideri eliminare. Una risposta corretta restituisce un oggetto JSON con success impostato su true.
Vale la pena notare che, una volta eliminato il codice QR, non è più possibile utilizzarlo per avviare una conversazione e digitare un messaggio senza l'input dell'utente.
Conclusioni
In questo tutorial pratico, hai imparato come creare, aggiornare, recuperare ed eliminare codici QR e link diretti con la piattaforma WhatsApp Business utilizzando l'API Cloud, ospitata da Meta. Sono stati inoltre analizzati rapidamente alcuni casi d'uso.
I codici QR di WhatsApp sono facili da gestire e possono consentire di aumentare in modo significativo le interazioni con i clienti. Con le funzionalità dei codici QR e dei link diretti di WhatsApp, è più facile che mai rimanere in contatto con i tuoi utenti.
Send Interactive Messages on the WhatsApp Business Platform
