Trasferimento agente in tempo reale

1. Introduzione

Ultimo aggiornamento: 23/08/2021

Trasferimento a un operatore con Business Messages

La funzionalità di trasferimento a un operatore di Business Messages consente al tuo agente di avviare una conversazione come bot e passare a un operatore (rappresentante umano) a metà conversazione. Il bot può gestire domande comuni, come gli orari di apertura, mentre l'agente live può fornire un'esperienza personalizzata con maggiore accesso al contesto dell'utente. Quando la transizione tra queste due esperienze è fluida, gli utenti ricevono risposte rapide e accurate alle loro domande, il che si traduce in un tasso di coinvolgimento di ritorno più elevato e in una maggiore soddisfazione dei clienti.

Questo codelab ti insegna a sfruttare al meglio la funzionalità di trasferimento all'operatore in tempo reale.

Cosa creerai

In questo codelab creerai un webhook per il tuo agente in grado di inviare e ricevere eventi di trasferimento dell'agente live. Utilizzerai una UI di base fornita dal codice iniziale per testare ciò che hai creato.

Nota:questo codelab presuppone che tu abbia già effettuato la registrazione come partner e che tu abbia ricevuto l'approvazione dal nostro team di assistenza. Se non l'hai ancora fatto, registrati a Business Messages e attendi l'approvazione prima di iniziare questo codelab.

Cosa imparerai a fare

• Come memorizzare e gestire lo stato della conversazione.
• Come utilizzare Business Messages per inviare eventi di trasferimento dell'agente live.
• 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 si concentra sull'utilizzo dell'API Business Messages per implementare il trasferimento all'agente live. Puoi leggere il codice iniziale per ogni fase, ma devi implementare solo il codice relativo a Business Messages.

Che cosa ti serve

• Un agente Business Messages, inclusa la chiave del service account. Puoi creare un agente seguendo la guida alla creazione di un agente.
• Una configurazione di Cloud Datastore funzionante collegata al progetto GCP dell'agente. Per configurarlo, puoi utilizzare la guida rapida di Cloud Datastore. Non devi sapere come 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 di programmazione di applicazioni web. Dovrai scrivere una piccola quantità di codice JavaScript e potresti dover eseguire il debug di ciò che scrivi.

2. Creare un bot echo

In questo passaggio, eseguirai il deployment di un rappresentante bot di base chiamato "Echo bot". Questo bot prende i messaggi degli utenti, li registra in un thread di conversazione in Cloud Datastore e poi "ripete" il messaggio dell'utente rispondendo con gli stessi contenuti. Una volta che hai un bot di base e un'infrastruttura di logging, puoi aggiungerne altri per creare un'implementazione completa del trasferimento all'agente live nei passaggi successivi.

Ottenere il codice di avvio

In un terminale, clona il codice iniziale per il trasferimento all'agente live nella directory di lavoro del tuo 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 iniziale che utilizzerai durante il codelab.

Vai alla directory step-1 e visualizzane i contenuti. Contiene i seguenti elementi:

• bin: questa directory contiene lo script di avvio www che configura il server.
• libs: questa directory contiene datastore_util.js, che contiene metodi pratici per leggere e scrivere da Cloud Datastore. Non è necessario capire come funziona questo file. Prendi nota dei metodi disponibili e di cosa fanno.
• resources: contiene la chiave del service account come file denominato credentials.json.
• routes: il file index.js contiene il webhook e tutti i relativi metodi helper. Questo è il file principale con cui lavorerai e a cui aggiungerai contenuti.
• views: questa directory contiene i file di modello EJS per gli elementi UI. Nei passaggi successivi conterrà più file.
• app.js, app.yaml, package.json: questi file configurano l'applicazione e le relative dipendenze.

Prima del deployment, scarica la chiave del service account GCP 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

Suggerimento: se hai bisogno di aiuto per configurare o scaricare la chiave di servizio, consulta la guida di Google Cloud per la gestione degli account di servizio.

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 questo 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 iniziale che hai appena implementato contiene un'applicazione web con un webhook per ricevere messaggi da Business Messages. L'applicazione ripete i messaggi all'utente e registra i thread di messaggi in Cloud Datastore.

Configura il tuo agente

Vai alla pagina delle impostazioni dell'account nella Console per gli sviluppatori di comunicazione aziendale e imposta il webhook sull'URL dell'applicazione di cui è stato eseguito il deployment. Ad esempio, https://PROJECT_ID.appspot.com/callback/.

Suggerimento: se hai bisogno di un ripasso su come impostare il webhook. Consulta la sezione Impostare il webhook nella guida alla configurazione di Business Messages.

Quindi, nella pagina delle informazioni sull'agente, configura i tipi di interazione principale e secondario rispettivamente come Bot e Operatore.

Avere una conversazione con il bot echo

Apri il tuo agente in Developer Console. Vedrai la pagina Panoramica, che ti consente di esaminare i dettagli del tuo agente. Copia l'URL di test dell'agente corrispondente al tuo dispositivo mobile di test. Utilizza questo URL sul tuo dispositivo mobile per avviare la superficie conversazionale del tuo agente.

Interagisci con l'agente inviando alcuni messaggi. La superficie conversazionale copia solo ciò che dici, il che 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 live. In qualità di operatore live, prima di partecipare devi conoscere alcuni dettagli della conversazione, ad esempio l'ID conversazione. È anche utile sapere se l'utente ha richiesto di parlare con un operatore. In questo passaggio, utilizzerai una pagina CRM (Customer Relationship Management) di base per visualizzare queste informazioni e partecipare alla conversazione come agente live.

Il codice iniziale 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 operatore in carne e ossa.

Vai alla directory step-2 e 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 un elenco con il thread conversazionale che hai iniziato nel passaggio precedente. Lo stato della conversazione è attualmente "Gestita dal bot" perché il bot di test funge da rappresentante del nostro agente in questa conversazione.

Il pulsante Partecipa alla chat viene visualizzato, ma non fa ancora nulla. Inoltre, da questa interfaccia non puoi sapere se l'utente vuole parlare con un operatore.

Business Messages fornisce un evento di richiesta di un agente che indica quando l'utente vuole parlare con un agente. 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 intercettare la richiesta dell'utente di un operatore in carne e ossa 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 a QUEUED_THREAD_STATE.

Se non sai cosa fare, dai un'occhiata alle soluzioni. Il codice iniziale 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 specificato.

Una volta completata l'implementazione e ridistribuita l'app, utilizza il menu overflow nella conversazione sul tuo dispositivo mobile per richiedere l'intervento di un operatore.

Suggerimento: se non vedi "Invia un messaggio a un operatore in carne e ossa " come opzione nel menu overflow, assicurati che l'operatore abbia configurato un tipo di interazione umana nella console Business Messages.

Ora, se torni al CRM, dovresti vedere una nota nel thread della conversazione che indica "Richiesta di un operatore live". Questo utente ha bisogno dell'aiuto di una persona. Per far funzionare il pulsante, devi implementare l'endpoint joinConversation.

Trova l'altro commento TODO nel metodo stub 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 a 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
parent	Imposta questo valore su "conversations/{conversationId}".
eventId	Genera un ID casuale per l'evento.
auth	Utilizza il metodo initCredentials fornito.
resource	Questo è il corpo dell'evento. Devi impostare eventType e representative.

Per assistenza, consulta la pagina di riferimento per il metodo create o la pagina di riferimento per gli 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 Conversazione a cui hai partecipato e lo stato della chat diventa "Chat live". Se guardi la conversazione sul tuo dispositivo mobile, vedrai una nota nella chat che indica che l'agente live ha partecipato.

Complimenti! Nel passaggio successivo, vedremo come far parlare l'agente live con l'utente.

4. Messaggistica come operatore

Ora che hai partecipato alla conversazione, è il momento di inviare alcuni messaggi come agente live.

Vai alla directory step-3 ed esegui nuovamente il deployment dell'app. Nel CRM, fai clic sul thread di conversazione del passaggio precedente. Ora 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 in qualità di agente non è ancora implementato. Devi completarlo in questo passaggio.

Apri il file routes/index.js ed esamina i tre endpoint appena aggiunti:

• /messages: recupera il file di visualizzazione messages.ejs e lo visualizza nel browser. Quando fai clic su un thread di conversazione dall'indice, viene visualizzata una di queste pagine.
• /retrieveMessages: Recupera i contenuti di un thread e restituisce un elenco formattato di tutti i messaggi nella conversazione. La pagina dei messaggi chiama periodicamente questo endpoint per visualizzare i messaggi più recenti.
• /sendMessage: invia un messaggio dall'operatore all'utente. La pagina dei messaggi chiama questa funzione 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) {
...
}

Il webhook utilizza già questo metodo per inviare le risposte del bot echo. Il metodo archivia innanzitutto i dati dei messaggi in arrivo nell'oggetto Cloud Datastore per la conversazione. Poi, invia il messaggio di risposta. Esamina attentamente l'oggetto del messaggio che crea, in particolare il tipo di rappresentante.

Ora implementa autonomamente l'endpoint /sendMessage. Puoi utilizzare il metodo storeAndSendResponse esistente per svolgere la maggior parte del lavoro. La cosa importante è ricordare di impostare il rappresentante corretto.

Una volta risolto il problema, esegui di nuovo il deployment dell'app e torna alla conversazione nel CRM. Ora puoi vedere i tuoi messaggi nella cronologia della chat. Puoi anche visualizzare i messaggi dell'agente sul tuo dispositivo mobile di test.

Prima di procedere, assicurati di aver compreso il funzionamento dei nuovi endpoint. Nel passaggio successivo, aggiungerai il tuo endpoint per uscire dalla conversazione.

5. Uscita dalla conversazione

Dopo aver aiutato l'utente con le sue domande, potresti voler abbandonare la conversazione e lasciare che l'utente parli di nuovo con il bot. In Business Messages, questa modifica è segnalata da un evento REPRESENTATIVE_LEFT.

Vai alla directory step-4, esegui nuovamente il deployment dell'app e torna al thread della conversazione. Ora nella parte inferiore del thread è presente un link Chiudi e abbandona la conversazione. Questo link non funziona ancora perché l'endpoint leaveConversation non è implementato.

Guarda 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 imparato finora dal codelab. Questo endpoint deve:

• Aggiorna il thread a 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 a BOT.

L'ultimo passaggio chiarisce lo stato della conversazione per l'utente. L'utente vede un evento quando un rappresentante esce dalla chat, ma non sa necessariamente di parlare di nuovo con il bot echo. Se invii un messaggio direttamente dal bot, riduci la confusione degli utenti e migliori l'esperienza.

Ora che il bot si occupa di tutto, l'operatore può partecipare a un'altra conversazione. Prova a utilizzare il codice campione e il CRM quanto vuoi. Prova diverse idee per l'esperienza di trasferimento all'agente live della tua attività e vedi cosa ti viene in mente.

6. In sintesi

Congratulazioni per aver completato il codelab sul trasferimento all'agente live.

Hai creato un agente in grado di gestire i trasferimenti di agenti live dall'inizio alla fine. Hai anche imparato un modo per monitorare lo stato della conversazione con Cloud Datastore.

Con il trasferimento all'operatore, potrai lasciare le richieste comuni al bot, mentre gli operatori gestiranno le domande più complesse. I tuoi utenti saranno più soddisfatti della nuova esperienza personalizzata e utile, il che aumenterà la probabilità che tornino e consiglino la tua attività agli amici.

Passaggi successivi

Dai un'occhiata ad alcuni di questi codelab:

• Acquista online, ritira in negozio parte 1
• Acquista online, ritira in negozio parte 2

Further reading

• Rivedi i concetti di base del trasferimento a un operatore con la guida al trasferimento dal bot all'operatore.
• Esegui l'upgrade del bot echo a un bot per le domande frequenti con la guida di Dialogflow.

Documentazione di riferimento

• Metodo: conversations.events.create
• Metodo: conversations.messages.create
• Risorsa: Event
• Rappresentante