Informazioni su questo codelab
1. Introduzione
Ultimo aggiornamento: 23/08/2021
Trasferimento a un operatore in tempo reale con Business Messages
La funzionalità di trasferimento all'agente dal vivo di Business Messages consente al tuo agente di avviare una conversazione come bot e passare a un agente dal vivo (rappresentante umano) durante la conversazione. Il bot può gestire le domande più comuni, come gli orari di apertura, mentre l'agente in tempo reale può offrire un'esperienza personalizzata con un maggiore accesso al contesto dell'utente. Quando la transizione tra queste due esperienze è fluida, gli utenti ricevono risposte alle loro domande in modo rapido e preciso, con un conseguente aumento del tasso di coinvolgimento dei clienti e della loro soddisfazione.
Questo codelab ti insegna a sfruttare al meglio la funzionalità di trasferimento all'agente in tempo reale.
Cosa creerai
In questo codelab, creerai un webhook per il tuo agente che possa inviare e ricevere eventi di trasferimento dell'agente in tempo reale. Utilizzerai un'interfaccia utente di base fornita dal codice di avvio per testare ciò che hai creato.
Cosa imparerai a fare
- Come memorizzare e gestire lo stato della conversazione.
- Come utilizzare Business Messages per inviare eventi di trasferimento all'agente in tempo reale.
- Come configurare un webhook e un'interfaccia utente di base per partecipare alle conversazioni come agente.
- Best practice per l'utilizzo dell'API Business Messages.
Questo codelab è incentrato sull'utilizzo dell'API Business Message per implementare il trasferimento all'agente in tempo reale. Puoi leggere il codice di avvio per ogni fase, ma devi implementare solo il codice relativo a Business Messages.
Che cosa ti serve
- Un agente Business Messages, inclusa la chiave dell'account di servizio. Per creare un agente, segui la guida alla creazione di un agente.
- Una configurazione Cloud Datastore funzionante collegata al progetto Google Cloud dell'agente. Per configurare questa operazione, puoi utilizzare la guida rapida di Cloud Datastore. Non devi necessariamente saper utilizzare Cloud Datastore.
- Un computer su cui sono installati Google Cloud SDK e Node.js (versione 10 o successive).
- Un dispositivo Android (con versione 5 o successive) o un dispositivo iOS per testare l'esperienza utente.
- Esperienza nella programmazione di applicazioni web. Dovrai scrivere una piccola quantità di codice JavaScript e potrebbe essere necessario eseguire il debug del codice scritto.
2. Creare un bot di ripetizione
In questo passaggio, eseguirai il deployment di un bot di base chiamato "bot Echo". Questo bot prende i messaggi degli utenti, li registra in un thread di conversazione in Cloud Datastore e poi "riproduce" il messaggio dell'utente rispondendo con gli stessi contenuti. Una volta creata un'infrastruttura di bot e di registrazione di base, puoi aggiungerne altre per creare un'implementazione completa del trasferimento all'agente in tempo reale nei passaggi successivi.
Ottieni il codice di avvio
In un terminale, clona il codice di avvio del trasferimento all'agente in tempo reale nella directory di lavoro del progetto con il seguente comando:
git clone https://github.com/google-business-communications/bm-nodejs-live-agent-transfer
Informazioni sul codice di avvio
Diamo un'occhiata alla struttura del codice di avvio con cui lavorerai durante il codelab.
Vai alla directory step-1 e visualizza i relativi contenuti. Contiene i seguenti elementi:
- bin: questa directory contiene lo script di avvio www che imposta e configura il server.
- libs: questa directory contiene
datastore_util.js, che contiene metodi di utilità per la lettura e la scrittura in Cloud Datastore. Non è necessario comprendere il funzionamento di questo file. Prendi nota dei metodi disponibili e della loro funzione. - resources: contiene la chiave dell'account di servizio come file denominato
credentials.json. - routes: il file
index.jscontiene l'webhook e tutti i relativi metodi di assistenza. Si tratta del file principale con cui lavorerai e a cui aggiungerai elementi. - views: questa directory contiene i file di modelli EJS per gli elementi dell'interfaccia utente. Nei passaggi successivi conterrà altri file.
- app.js, app.yaml, package.json: questi file configurano l'applicazione e le relative dipendenze.
Prima di eseguire il deployment, scarica la chiave dell'account di servizio Google Cloud e copia il file delle credenziali JSON in ogni directory delle risorse nel codice di esempio. Ripeti l'operazione per ogni passaggio del codelab.
cp credentials.json bm-nodejs-live-agent-transfer/step-<step number>/resources/credentials.json
Eseguire il deployment del codice di avvio
In un terminale, vai alla directory step-1 dell'esempio. Poi, imposta lo strumento gcloud in modo che utilizzi il tuo progetto Google Cloud impostando l'ID progetto che hai utilizzato per registrarti alle API.
gcloud config set project <PROJECT_ID>
Per eseguire il deployment dell'applicazione, esegui il seguente comando:
gcloud app deploy
Prendi nota dell'URL dell'applicazione di cui è stato eseguito il deployment nell'output dell'ultimo comando:
Deployed service [default] to [https://PROJECT_ID.appspot.com]
Il codice di avvio che hai appena di cui hai eseguito il deployment contiene un'applicazione web con un webhook per ricevere messaggi da Business Messages. L'applicazione restituisce i messaggi all'utente e registra i thread dei messaggi in Cloud Datastore.
Configura il tuo agente
Vai alla pagina Impostazioni account nella Console per gli sviluppatori di comunicazione aziendale e imposta l'webhook sull'URL dell'applicazione di cui è stato eseguito il deployment. Ad esempio, https://PROJECT_ID.appspot.com/callback/.
Nella pagina Informazioni sull'agente, configura i tipi di interazione principale e secondario come Bot e Operatore umano.
Conversazione con il bot Echo
Apri l'agente nella Console per gli sviluppatori. Viene visualizzata la pagina Panoramica, che ti consente di esaminare i dettagli dell'agente. Copia l'URL di test dell'agente corrispondente al tuo dispositivo di test mobile. Utilizza questo URL sul tuo dispositivo mobile per avviare la piattaforma di conversazione dell'agente.
Interagisci con l'agente inviando alcuni messaggi. La piattaforma di conversazione copia solo ciò che dici, non è un'esperienza utente molto utile. Se solo ci fosse un modo per parlare con una persona reale.
3. Partecipare alla conversazione
Ora esaminiamo la conversazione dal punto di vista dell'agente in tempo reale. In qualità di agente in tempo reale, devi conoscere alcuni aspetti della conversazione prima di partecipare, ad esempio l'ID conversazione. È utile anche sapere se l'utente ha richiesto di parlare con un operatore in tempo reale. In questo passaggio, utilizzerai una pagina di CRM (Customer Relationship Management) di base per visualizzare queste informazioni e partecipare alla conversazione come agente in tempo reale.
Il codice di avvio per questo passaggio aggiunge un CRM di base che elenca tutti i thread di conversazione in corso per l'agente. Diamo un'occhiata al CRM per vedere quali conversazioni potrebbero richiedere l'attenzione di un agente in tempo reale.
Vai alla directory step-2 ed esegui di nuovo il deployment dell'app come nel passaggio precedente.
Quando esegui il deployment dell'app, viene visualizzato un URL di destinazione. Vai a questo URL in un browser per visualizzare una scheda con il thread di conversazione che hai iniziato nel passaggio precedente. Lo stato della conversazione è attualmente "Gestito dal bot" perché il bot Echo agisce come rappresentante del nostro agente in questa conversazione.
Viene visualizzato il pulsante Partecipa alla chat, ma non fa ancora nulla. Inoltre, da questa interfaccia non puoi capire se l'utente vuole parlare con un operatore in tempo reale.
Business Messages fornisce un evento di richiesta di agente in tempo reale che indica quando l'utente vuole parlare con un agente in tempo reale. Devi tenere traccia di questo stato per elencarlo nell'interfaccia utente.
Dai un'occhiata al metodo di callback in index.js. Un commento TODO indica dove devi acquisire la richiesta dell'utente di un agente in tempo reale e aggiornare lo stato del thread.
step-2/routes/index.js
/**
* The webhook callback method.
*/
router.post('/callback', async function(req, res, next) {
...
} else if (requestBody.userStatus !== undefined) {
if (requestBody.userStatus.requestedLiveAgent !== undefined) {
...
// TODO: Update the thread state to QUEUED_THREAD_STATE.
}
}
});
...
});
Devi utilizzare i metodi in libs/datastore_utils.js per caricare il thread di conversazione corrente e aggiornarne lo stato su QUEUED_THREAD_STATE.
Se non sai cosa fare, dai un'occhiata alle soluzioni. Il codice di avvio include una directory solutions in ogni passaggio in cui devi completare del codice. Queste directory contengono una copia dell'intera app con l'implementazione completa per il passaggio in questione.
Una volta completata l'implementazione e riapplicata l'app, utilizza il menu extra nella conversazione sul tuo dispositivo mobile per richiedere un agente in tempo reale.
Ora, se torni al CRM, dovresti vedere una nota nel thread della conversazione che dice "Agente dal vivo richiesto". Questo utente ha bisogno di aiuto da parte di una persona. Per far funzionare il pulsante, devi implementare l'endpoint joinConversation.
Trova l'altro commento TODO nel metodo simulato per /joinConversation.
step-2/routes/index.js
/**
* Updates the thread state and sends a representative join signal to the user.
*/
router.post('/joinConversation', async function(req, res, next) {
let conversationId = req.body.conversationId;
// TODO: Update the thread state to LIVE_AGENT_THREAD_STATE and post a REPRESENTATIVE_JOINED event.
res.json({
'result': 'ok',
});
});
Devi aggiornare di nuovo lo stato del thread, questa volta impostandolo su LIVE_AGENT_THREAD_STATE. Inoltre, devi utilizzare il metodo conversations.events.create dell'API Business Messages per pubblicare un evento REPRESENTATIVE_JOINED.
Per creare il payload della richiesta, devi impostare i campi descritti nella tabella seguente:
Nome campo | Suggerimento |
| Imposta questo valore su "conversations/{conversationId}". |
| Genera il tuo ID casuale per l'evento. |
| Utilizza il metodo |
| Si tratta del corpo dell'evento stesso. Devi impostare eventType e representative. |
Per assistenza, consulta la pagina di riferimento del metodo create o la pagina di riferimento degli eventi.
Al termine dell'implementazione, esegui nuovamente il deployment dell'app e fai clic sul pulsante Partecipa alla chat. Viene visualizzata la finestra di dialogo Hai partecipato alla conversazione e lo stato della chat diventa "Chat live". Se esamini la conversazione sul tuo dispositivo mobile, vedrai una nota nella chat che ti informa che l'agente dal vivo si è unito alla chat.
Complimenti! Nel passaggio successivo, vedremo come fare in modo che l'agente dal vivo parli con l'utente.
4. Inviare messaggi come operatore in tempo reale
Ora che hai partecipato alla conversazione, è il momento di inviare alcuni messaggi come agente in tempo reale.
Vai alla directory step-3 e esegui nuovamente il deployment dell'app. Nel CRM, fai clic sul thread di conversazione del passaggio precedente. A questo punto dovresti vedere un'interfaccia di chat di base. Da qui puoi vedere i messaggi dell'utente in tempo reale.
Tuttavia, l'invio di un messaggio come agente non è ancora implementato. Devi completare questa operazione in questo passaggio.
Apri il file routes/index.js e controlla i tre endpoint appena aggiunti:
/messages: recupera il file di visualizzazionemessages.ejse lo esegue nel browser. Quando fai clic su un thread di conversazione dall'indice, accedi a una di queste pagine./retrieveMessages: recupera i contenuti del messaggio di un thread e restituisce un elenco formattato di tutti i messaggi della conversazione. La pagina dei messaggi chiama periodicamente questo endpoint per visualizzare i messaggi più recenti./sendMessage: invia un messaggio dall'agente all'utente. La pagina dei messaggi lo chiama quando fai clic su Invia. Al momento non è implementata.
Ora dai un'occhiata al metodo storeAndSendResponse esistente:
step-3/routes/index.js
/**
* Updates the thread, adds a new message and sends a response to the user.
*
* @param {string} message The message content that was received.
* @param {string} conversationId The unique id for this user and agent.
* @param {string} threadState Represents who is managing the conversation for the CRM.
* @param {string} representativeType The representative sending the message, BOT or HUMAN.
*/
async function storeAndSendResponse(message, conversationId, threadState, representativeType) {
...
}
L'webhook utilizza già questo metodo per inviare le risposte dal bot echo. Il metodo memorizza prima i dati dei messaggi in arrivo nell'oggetto Cloud Datastore per la conversazione. Poi, invia il messaggio di risposta. Esamina attentamente l'oggetto messaggio creato, in particolare il tipo di rappresentante.
Ora implementa l'endpoint /sendMessage. Puoi utilizzare il metodo storeAndSendResponse esistente qui per svolgere la maggior parte del lavoro. L'importante è ricordare di impostare il rappresentante corretto.
Una volta che tutto funziona, esegui nuovamente il deployment dell'app e torna alla conversazione nel CRM. Ora puoi vedere i tuoi messaggi nella cronologia della chat. Puoi anche vedere i messaggi dell'agente sul tuo dispositivo di test mobile.
Prima di continuare, assicurati di aver compreso il funzionamento dei nuovi endpoint. Nel passaggio successivo aggiungerai il tuo endpoint per abbandonare la conversazione.
5. Abbandonare la conversazione
Dopo aver aiutato l'utente a rispondere alle sue domande, ti consigliamo di abbandonare la conversazione e di lasciare che l'utente parli di nuovo con il bot. In Business Messages, questa modifica viene segnalata da un evento REPRESENTATIVE_LEFT.
Vai alla directory step-4, esegui nuovamente il deployment dell'app e torna al thread di conversazione. Ora nella parte inferiore del thread è presente il link Chiudi e esci dalla conversazione. Questo link non funziona ancora perché l'endpoint leaveConversation non è implementato.
Esamina il file index.js. È presente un commento TODO che ti chiede di creare un nuovo endpoint leaveConversation.
step-4/routes/index.js
/*
* TODO: Create a '/leaveConversation' endpoint that does the following:
* - Updates the thread to BOT_THREAD_STATE.
* - Sends a REPRESENTATIVE_LEFT event.
* - Sends a message to the thread informing the user that they are speaking to the echo bot again.
*
* Hint: You can use the same methods that '/joinConversation' uses.
*/
Per implementare questa funzionalità, devi mettere insieme tutto ciò che hai appreso finora nel codelab. Questo endpoint deve:
- Aggiorna il thread su
BOT_THREAD_STATE. - Invia un evento
REPRESENTATIVE_LEFT. - Invia un messaggio nella conversazione per comunicare all'utente che sta parlando con il bot Echo. Utilizza il metodo
storeAndSendResponse. Ricorda che il rappresentante è tornato aBOT.
L'ultimo passaggio chiarisce lo stato della conversazione per l'utente. L'utente vede un evento quando un rappresentante lascia la chat, ma non necessariamente sa che sta parlando di nuovo con il bot echo. Se invii un messaggio direttamente dal bot, riduci la confusione degli utenti e migliori la loro esperienza.
Ora che il bot si sta occupando della richiesta, l'agente dal vivo è libero di partecipare a un'altra conversazione. Prova a utilizzare il codice campione e il CRM quanto vuoi. Prova alcune idee diverse per l'esperienza di trasferimento all'agente in tempo reale della tua attività e scopri cosa riesci a ottenere.
6. In sintesi
Complimenti per aver completato il codelab sul trasferimento all'agente in tempo reale.
Hai creato un agente che può gestire i trasferimenti agli agenti dal vivo dall'inizio alla fine. Hai anche imparato un modo per monitorare lo stato della conversazione con Cloud Datastore.
Con il trasferimento all'agente in tempo reale, puoi lasciare le richieste comuni al tuo bot, mentre gli agenti in tempo reale gestiscono le richieste più complesse. I tuoi utenti saranno più soddisfatti della nuova esperienza personalizzata e utile, aumentando le probabilità che tornino e consiglino la tua attività agli amici.
Passaggi successivi
Dai un'occhiata ad alcuni di questi codelab:
Letture aggiuntive
- Consulta le nozioni di base sul trasferimento all'agente in tempo reale con la guida al trasferimento dal bot all'agente in tempo reale.
- Esegui l'upgrade del tuo bot Echo a un bot FAQ con la guida di Dialogflow.