Informazioni su questo codelab
1. Introduzione
Ultimo aggiornamento: 11/05/2022
Ti diamo il benvenuto in Business Messages.
Questo codelab è un'introduzione all'integrazione con Business Messages, che consente ai clienti di contattare le attività che gestisci tramite la Ricerca Google e Maps. Potresti essere un'attività che vuole eseguire l'integrazione direttamente con Business Messages oppure potresti lavorare per un fornitore di software indipendente che crea soluzioni di messaggistica per le attività con cui collabori oppure potresti aver appena scoperto Business Messages e voler fare esperimenti sulla piattaforma.
Indipendentemente dal motivo per cui ti trovi qui, questo codelab è un ottimo modo per iniziare. Al termine, avrai il tuo primo agente digitale con cui gli utenti possono interagire. Quando sarà tutto pronto per il lancio su Business Messages, avrai la possibilità di raggiungere milioni di clienti.
Cosa rende un agente digitale efficace?
Business Messages è una piattaforma di conversazione che offre un'esperienza simile a un'app sui dispositivi mobili e consente ai consumatori di contattare le attività senza installare un'app aggiuntiva. Un agente digitale è la parte di logica con cui interagiscono i clienti. La logica è gestita da un'applicazione web di cui è stato eseguito il deployment nel cloud o nella tua infrastruttura. Sta a te decidere come rispondere all'utente. I migliori agenti forniscono il contesto per creare aspettative, mantenere i clienti coinvolti e offrire funzionalità per soddisfare le esigenze degli utenti.
Cosa creerai
In questo codelab, creerai un agente digitale su Business Messages per un'azienda fittizia chiamata Bonjour Meal. Questo agente digitale risponderà ad alcune semplici domande, ad esempio "A che ora chiudete?" o "Posso acquistare online?".
In questo codelab, gli utenti potranno acquistare articoli tramite l'agente digitale, indirizzare l'utente a un elaboratore dei pagamenti per incassare il denaro e poi pianificare il ritiro dei loro articoli fittizi in negozio.
In questo codelab, la tua app:
- Rispondere alle domande tramite un chip di suggerimento
- Invita l'utente a porre domande a cui il tuo agente digitale può rispondere
- Fornire funzionalità di conversazione avanzate per mantenere l'utente coinvolto nella conversazione
Cosa imparerai a fare
- Come eseguire il deployment di un'applicazione web su App Engine nella piattaforma Google Cloud. In alternativa, puoi utilizzare ngrok per testare pubblicamente la tua applicazione locale.
- Come configurare l'account Business Messages con un webhook di applicazione web per ricevere messaggi dagli utenti
- Come inviare funzionalità avanzate come schede, caroselli e suggerimenti di conversazione con l'API Business Messages
- In che modo Business Messages invia i messaggi
Questo codelab è incentrato sulla creazione del tuo primo agente digitale.
Che cosa ti serve
- Registrati per un account sviluppatore Business Communications senza costi
- Visita il nostro sito per sviluppatori per istruzioni su come
- Un dispositivo Android con versione 5 o successive OPPURE un dispositivo iOS con l'app Google Maps
- Esperienza nella programmazione di applicazioni web
- Una connessione a internet.
2. Preparazione
Abilita le API
Per questo codelab, poiché lavoreremo con un'applicazione Django, ci affideremo all'API Cloud Build per eseguire il deployment dell'applicazione in App Engine. In alternativa, se utilizzi ngrok, non è necessario abilitare l'API Cloud Build.
Per abilitare l'API Cloud Build:
- Apri l'API Cloud Build nella console Google Cloud.
- Fai clic su Abilita.
Creare un account di servizio
Devi creare un account di servizio per accedere alle API Business Communications e Business Messages. Segui i passaggi descritti nella documentazione per creare un account di servizio nella Business Communications Developer Console.
Esegui il deployment del codice di avvio di Django Python EchoBot
In un terminale, clona l'esempio di bot Django Echo nella directory di lavoro del progetto con il seguente comando:
$ git clone https://github.com/google-business-communications/bm-bonjour-meal-django-starter-code
Copia il file delle credenziali JSON creato per l'account di servizio nella cartella delle risorse del Sample e rinomina le credenziali in "bm-agent-service-account-credentials.json".
bm-bonjour-meal-django-starter-code/bonjourmeal-codelab/step-1/resources/bm-agent-service-account-credentials.json
In un terminale, vai alla directory step-1 dell'esempio.
Esegui i seguenti comandi in un terminale per eseguire il deployment dell'esempio:
$ gcloud config set project PROJECT_ID*
$ gcloud app create
$ gcloud app deploy
- PROJECT_ID è l'ID progetto che hai utilizzato per registrarti alle API.
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 può mostrare alcune delle funzionalità avanzate disponibili nella piattaforma di conversazione.
Configurare il tuo webook
Ora che il servizio è stato disegnato, utilizza l'URL dell'applicazione per impostare l'URL webhook nella pagina Impostazioni account della Developer Console di Business Communications.
L'URL del webhook sarà l'URL dell'applicazione + "/callback/". Ad esempio, potrebbe essere qualcosa di simile: https://PROJECT_ID.appspot.com/callback/
Vai alla pagina Impostazioni account della Business Communications Console. Nell'angolo in alto a destra, sotto la barra di navigazione, dovresti vedere il nome del progetto Google Cloud. Se viene visualizzato un elenco a discesa, assicurati di selezionare il tuo progetto Google Cloud.
Compila i dettagli del Punto di contatto tecnico, quindi aggiorna Webhook con l'URL webhook per l'applicazione di cui è stato eseguito il deployment.
Fai clic su Salva accanto al riferimento del tuo progetto Google Cloud.
3. Creare il primo agente
Utilizzare la Business Communications Developer Console
Nella Business Communications Console, fai clic sul logo in alto a sinistra per tornare alla dashboard della console, quindi fai clic su Crea agente. Puoi creare un brand contemporaneamente all'agente. Seleziona Messaggi per le attività per Tipo di agente e assicurati che le Informazioni sul partner siano corrette.
In Brand, digita il nome del brand che stai creando.Il brand è l'attività con cui collabori e i consumatori possono interagire con l'agente in modo conversazionale. In Nome agente, specifica cosa vuoi che gli utenti vedano nella conversazione di Business Messages. Nel caso del pasto fittizio Bonjour, Bonjour Rail è la compagnia ferroviaria che gestisce i ristoranti Bonjour Meal. Specificherò quindi Bonjour Rail come brand e Bonjour Meal come agente.
L'agente è l'entità di conversazione che rappresenta il brand.
Fai clic su Crea agente e lascia che la console faccia il resto. Questa richiesta richiede alcuni secondi per inviare diverse richieste all'API Business Communications per creare il brand e l'agente. Puoi utilizzare direttamente l'API Business Communications per creare un agente e un brand. Consulta la documentazione per vedere come sarebbe una richiesta curl per eseguire le stesse operazioni della console.
Condurre la prima conversazione
Apri l'agente appena creato. Viene visualizzata la pagina Panoramica, che ti consente di iniziare a esaminare i dettagli dell'agente. Dai un'occhiata agli URL di test dell'agente. Questi URL vengono utilizzati per richiamare la piattaforma di conversazione sul tuo dispositivo.
Puoi copiare l'URL di test facendo clic su uno dei chip. Ovviamente, copia l'URL di test per il dispositivo di cui disponi per eseguire il test. Invia il messaggio copiato al tuo dispositivo come preferisci.
Una volta sul dispositivo mobile, toccando il link viene richiamato il programma di avvio dell'agente di Business Messages con l'URL di test dell'agente precompilato.
Tocca Avvia per richiamare la superficie di conversazione dell'agente.
Interagisci con l'agente e scopri di cosa è capace. Nella maggior parte dei casi, la piattaforma di conversazione ripeterà solo i tuoi messaggi. Invia un messaggio del tipo "Ciao" e vedrai che l'agente ti invierà lo stesso messaggio.
L'applicazione di cui è stato eseguito il deployment contiene anche una logica per mostrare le funzionalità avanzate disponibili in Business Messages.
- Se invii "card", verrà invocata una scheda informativa
- Se invii "chip", verranno richiamati i chip di suggerimento
- Se invii "carousel", verrà visualizzato un carosello di schede interattive
Complimenti! Questa è la prima conversazione del tuo agente con te.
Ognuna delle funzionalità avanzate può essere utilizzata per fornire un contesto migliore alla persona che comunica con il tuo agente. Invia asset grafici nelle schede avanzate per comunicare meglio le idee o utilizza i chip di suggerimento per guidare la conversazione.
Aggiornare il messaggio di benvenuto e utilizzare i chip di conversazione
Fai pratica con la Developer Console e scopri come modificare il messaggio di benvenuto dell'agente e utilizzare i chip di suggerimento per aiutare l'utente a comunicare.
Vai alla pagina Panoramica dell'agente e seleziona Informazioni sull'agente. Scorri verso il basso fino alla sezione relativa al messaggio di benvenuto e ai temi di conversazione.
Aggiorna il messaggio di benvenuto (il campo di immissione giallo) in modo che riporti quanto segue:
Ti diamo il benvenuto nell'agente di avvio del pasto Bonjour. Posso ripetere i tuoi messaggi e mostrarti alcune delle funzionalità avanzate supportate sulla piattaforma. Prova questi suggerimenti.
Fai clic su + Aggiungi spunto di conversazione come indicato nella casella viola nell'immagine sopra per aggiungere spunti di conversazione per richiamare chip di suggerimento, carosello e scheda. Gli spunti di conversazione che aggiungi richiedono un componente di testo e un componente postbackData. Il testo viene mostrato all'utente, mentre i dati postback vengono inviati all'webhook dell'agente. Il webhook analizza i dati di postback e invia la risposta appropriata all'utente. 
Le Informazioni sull'agente nella console hanno il seguente aspetto dopo la modifica:
Sul lato destro della console, viene visualizzata un'anteprima dell'aspetto dell'agente. Hai notato che il messaggio di benvenuto riflette i dati che hai appena modificato e i chip di suggerimento sottostanti?
Si tratta di un ottimo strumento per farsi un'idea di come sarà l'esperienza utente. Puoi utilizzarlo durante la creazione dell'agente e la pianificazione dei percorsi dell'utente che vuoi supportare.
Purtroppo, non potremo vedere immediatamente queste modifiche nella conversazione, poiché i dati precedenti vengono memorizzati nella cache all'interno dell'infrastruttura di Business Messages. La cache viene cancellata ogni 2 ore circa, quindi dovresti riuscire a provare questa funzionalità domani.
Nel frattempo, diamo un'occhiata a come funziona tutto.
4. Analisi del codice di avvio
Una vista d'insieme del codice sorgente
Il codice di avvio di cui hai eseguito il deployment restituisce i messaggi agli utenti e può presentare una scheda avanzata, un carosello o chip di suggerimento. Esaminiamo più da vicino il codice sorgente per capire come funziona. Poi capiremo cosa dovremo cambiare.
Il codice di avvio è un progetto Django. In un secondo momento di questa serie di codelab, utilizzeremo Google Datastore per mantenere i dati come i carrelli degli acquisti e le conversazioni associate. Non preoccuparti se non hai mai utilizzato Django prima d'ora: è abbastanza semplice e alla fine di questo codelab avrai imparato come funziona.
A livello generale, Django indirizzerà gli URL alle visualizzazioni e la logica di visualizzazione produrrà un modello che verrà visualizzato nel browser. Diamo un'occhiata a urls.py del progetto.
bm-django-echo-bot/bmcodelab/urls.py [Righe 31-37]
from django.urls import include, path
import bopis.views as bopis_views
urlpatterns = [
path('', bopis_views.landing_placeholder),
path('callback/', bopis_views.callback),
]
Qui sono definiti due percorsi, quindi Django può eseguire la logica se questi due URL vengono riconosciuti. Dato che l'URL del progetto è https://PROJECT_ID.appspot.com/, i percorsi noti del progetto sono:
- https://PROJECT_ID.appspot.com/
- https://PROJECT_ID.appspot.com/callback/
Entrambi i percorsi dell'URL fanno riferimento a bopis_views, che si trova in bopis/views.py. Diamo un'occhiata a cosa succede in questo file. Per iniziare, cerchiamo di capire cosa sia bopis_views.landing_placeholder.
bm-django-echo-bot/bonjourmeal-codelab/step-1/bopis/views.py [Righe 302-309]
...
def landing_placeholder(request):
return HttpResponse("<h1>Welcome to the Bonjour Meal Codelab</h1>
<br/><br/>
To message your Bonjour Meal agent, go to the Developer Console and retrieve
the Test URLs for the agent you have created as described in the codelab
<a href='https://codelabs.developers.google.com/codelabs/'>here</a>.")
...
Questo frammento di logica viene eseguito dal server web quando riceve una richiesta web che rimanda alla radice del progetto. Non succede niente di troppo complicato: restituiamo semplicemente una risposta HTTP contenente del codice HTML al browser che ha effettuato la richiesta. Quindi sì, puoi aprire l'URL principale del progetto, ma non c'è molto da fare perché ti reindirizza a questo codelab.
L'altro URL rimanda a una funzione chiamata callback, sempre in bopis/views.py. Diamo un'occhiata a questa funzione.
bm-django-echo-bot/bopis/views.py [Righe 60-101]
...
def callback(request):
"""
Callback URL. Processes messages sent from user.
"""
if request.method == "POST":
request_data = request.body.decode('utf8').replace("'", '"')
request_body = json.loads(request_data)
print('request_body: %s', request_body)
# Extract the conversation id and message text
conversation_id = request_body.get('conversationId')
print('conversation_id: %s', conversation_id)
# Check that the message and text body exist
if 'message' in request_body and 'text' in request_body['message']:
message = request_body['message']['text']
print('message: %s', message)
route_message(message, conversation_id)
elif 'suggestionResponse' in request_body:
message = request_body['suggestionResponse']['postbackData']
print('message: %s', message)
route_message(message, conversation_id)
elif 'userStatus' in request_body:
if 'isTyping' in request_body['userStatus']:
print('User is typing')
elif 'requestedLiveAgent' in request_body['userStatus']:
print('User requested transfer to live agent')
return HttpResponse("Response.")
elif request.method == "GET":
return HttpResponse("This webhook expects a POST request.")
...
La logica qui analizza il corpo della richiesta per un message o un suggestionResponse e passa queste informazioni a una funzione chiamata route_message, quindi restituisce un'HttpResponse all'infrastruttura di Business Messages per confermare la ricezione del messaggio.
Questa è una funzione importante. Questo frammento di logica è il webhook della tua applicazione web, che riceve i messaggi dagli utenti che interagiscono con il tuo agente. Puoi estendere l'webhook per inviare messaggi a uno strumento di automazione come Dialogflow per capire cosa potrebbe dire un utente e produrre una risposta da questa deduzione. Puoi anche inoltrare il messaggio in modo che l'utente possa contattare un operatore in tempo reale. Vedi il seguente diagramma:
Business Messages invia i contenuti del messaggio come payload JSON al tuo webhook, dove vengono inoltrati a un agente in tempo reale o a una logica per rispondere come bot. Questo meccanismo di instradamento, nel nostro caso, è route_message. Diamo un'occhiata.
bm-django-echo-bot/bopis/views.py [Lines 105-122]
...
def route_message(message, conversation_id):
'''
Routes the message received from the user to create a response.
Args:
message (str): The message text received from the user.
conversation_id (str): The unique id for this user and agent.
'''
normalized_message = message.lower()
if normalized_message == CMD_RICH_CARD:
send_rich_card(conversation_id)
elif normalized_message == CMD_CAROUSEL_CARD:
send_carousel(conversation_id)
elif normalized_message == CMD_SUGGESTIONS:
send_message_with_suggestions(conversation_id)
else:
echo_message(message, conversation_id)
...
Questo breve frammento di logica inizia a esaminare il messaggio ricevuto dall'utente. Innanzitutto, il messaggio viene normalizzato abbassando tutti i caratteri. Una volta normalizzato, viene controllato se il messaggio corrisponde a una delle costanti definite nella parte superiore del file.
bm-django-echo-bot/bopis/views.py [Linee 40-42]
...
# Set of commands the bot understands
CMD_RICH_CARD = 'card'
CMD_CAROUSEL_CARD = 'carousel'
CMD_SUGGESTIONS = 'chips'
...
In altre parole, il bot analizza i messaggi che contengono specificamente una delle stringhe che abbiamo inserito in postback_data degli approcci di conversazione del passaggio precedente di questo codelab. Se non viene visualizzata nessuna di queste stringhe, il messaggio viene semplicemente passato a una funzione chiamata echo_message, che, come puoi immaginare, ripete i messaggi.
Invio di messaggi
A questo punto dovresti avere un'idea di come i messaggi vengono ricevuti dall'applicazione web. Tutto viene gestito dal webhook.
Ma in che modo l'applicazione invia un messaggio in uscita a un utente che utilizza Business Messages?
Quando la tua infrastruttura risponde all'utente, invii la risposta all'API Business Messages, che consegna il messaggio all'utente.
L'API Business Messages dispone di librerie in Python, Node.js e Java. Abbiamo anche un'API REST a cui puoi inviare richieste direttamente se la tua infrastruttura non è in un linguaggio per cui abbiamo una libreria. Consulta Invio di messaggi per scoprire come viene utilizzato cURL per inviare un messaggio a un ID conversazione specifico.
Ai fini di questo codelab, ci concentreremo sull'utilizzo della libreria client Python già integrata nel codice di avvio di Bonjour Meal che è stato disegnato in App Engine nel tuo progetto Google Cloud o in esecuzione localmente tramite ngrok.
Esamina la funzione echo_message e scopri come interagiamo con l'API per inviare il messaggio a Business Messages.
bm-django-echo-bot/bopis/views.py [Linee 199-212]
...
def echo_message(message, conversation_id):
'''
Sends the message received from the user back to the user.
Args:
message (str): The message text received from the user.
conversation_id (str): The unique id for this user and agent.
'''
message_obj = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BOT_REPRESENTATIVE,
text=message)
send_message(message_obj, conversation_id)
...
In questa funzione, viene creato un oggetto BusinessMessagesMessage con la variabile messaggio passata alla funzione echo_message. Una volta creato, l'oggetto viene passato a send_message insieme all'ID conversazione.
bm-django-echo-bot/bopis/views.py [Linee 214-236]
...
def send_message(message, conversation_id):
'''
Posts a message to the Business Messages API, first sending
a typing indicator event and sending a stop typing event after
the message has been sent.
Args:
message (obj): The message object payload to send to the user.
conversation_id (str): The unique id for this user and agent.
'''
credentials = ServiceAccountCredentials.from_json_keyfile_name(
SERVICE_ACCOUNT_LOCATION,
scopes=['https://www.googleapis.com/auth/businessmessages'])
client = bm_client.BusinessmessagesV1(credentials=credentials)
# Create the message request
create_request = BusinessmessagesConversationsMessagesCreateRequest(
businessMessagesMessage=message,
parent='conversations/' + conversation_id)
bm_client.BusinessmessagesV1.ConversationsMessagesService(
client=client).Create(request=create_request)
...
La funzione send_message si limita a utilizzare le credenziali del tuo account di servizio per verificare che tu possa inviare messaggi a questa conversazione, a creare un'istanza di un client Business Messages e a creare una richiesta per inviare il messaggio al conversation ID specificato.
Anche le funzionalità avanzate utilizzano questa funzione send_message, ma i messaggi che creano sono specifici per schede avanzate, caroselli e chip di suggerimento. Le schede avanzate e i caroselli possono includere risorse grafiche, mentre i chip di suggerimento hanno postback_data in modo che la logica di callback possa analizzarli in modo appropriato.
Ora che abbiamo visto come inviare un messaggio, scopri come il sample invia schede interattive, caroselli e chip di suggerimento. Nella sezione seguente modificheremo il codice sorgente per inviare messaggi con alcune di queste funzionalità avanzate.
Quando è tutto pronto, personalizziamo l'agente Bonjour Meal.
5. Personalizzare l'agente
Se hai seguito il codelab fino a questo momento, dovresti vedere il nostro bellissimo agente.
Ok, non è così bello, sembra un po' spoglio e non rappresenta molto bene la nostra attività. Fortunatamente, abbiamo una conoscenza di base del codice che supporta l'agente e gli strumenti necessari per personalizzarlo in qualsiasi modo.
Nella parte rimanente di questo codelab, estenderemo l'agente con quanto segue:
- Includi un logo reale
- Messaggio di benvenuto migliorato
- Fornire informazioni sull'orario di apertura
- Comunicare all'utente che l'acquisto di articoli online sarà disponibile a breve
- Utilizzo di chip di suggerimenti conversazionali per facilitare la conversazione
Utilizzeremo la console Business Communications per aggiornare il logo e il messaggio di benvenuto, ma puoi sempre utilizzare direttamente le API Business Communications per eseguire la stessa operazione. Dovremo quindi aggiornare il codice sorgente per inviare messaggi appropriati per fornire informazioni sugli orari di apertura e che a breve Bonjour Meal offrirà una funzionalità di acquisto online. Al termine, torneremo a Business Communications Console e creeremo chip di suggerimenti di conversazione per aiutare a indirizzare la conversazione alle esperienze di percorso ottimale supportate dall'agente digitale.
Includi un logo
Nella Business Communications Console, seleziona il tuo agente e vai a Informazioni sull'agente. Dovremo aggiornare il logo dell'attività, come indicato in giallo di seguito.
Fai clic su Carica per selezionare un'immagine da caricare o da importare da un URL.
Consulta le linee guida per la progettazione del logo nella documentazione per scoprire le best practice consigliate per l'utilizzo dei tuoi loghi.
Carica il logo che si trova nel codice sorgente che hai clonato all'inizio di questo codelab. Puoi trovarlo nella directory ./assets/ del repository e il file si chiama "bonjour_meal-logo.png". Puoi trascinare il file nella finestra modale del browser web, dove verrà visualizzato uno strumento di modifica leggero per manipolare la qualità e il ritaglio dell'immagine. Modifica la risoluzione e il ritaglio dell'immagine in modo che non superi il limite di 50 KB. Quando l'immagine ti soddisfa, fai clic sul segno di spunta nel cerchio blu per confermare e poi su Seleziona nella parte inferiore della finestra modale.
Infine, fai clic su Salva in alto a destra nella pagina Informazioni sull'agente. Poiché le informazioni sull'agente vengono memorizzate nella cache dei nostri server, questa modifica potrebbe richiedere del tempo prima di essere applicata al tuo dispositivo, ma dovrebbe essere visibile entro due ore dalla modifica.
Aggiornare il messaggio di benvenuto
Abbiamo già aggiornato il messaggio di benvenuto in precedenza in questo codelab. Ripetiamo l'operazione, ma questa volta configura un messaggio di benvenuto più adatto al percorso dell'utente di Bonjour Meal.
Nella Business Communications Console, seleziona il tuo agente e vai a Informazioni sull'agente. Scorri verso il basso fino a visualizzare il campo di immissione Messaggio di benvenuto, in cui puoi aggiornare il messaggio.
Dato che aggiungeremo dei modi per iniziare una conversazione, possiamo farvi riferimento nel messaggio di benvenuto. Nel campo di immissione, sostituiamolo con il seguente testo:
"Ti diamo il benvenuto in Bonjour Meal. Sono un assistente che può aiutarti a rispondere alle tue domande su Bonjour Meal. Prova alcune delle seguenti opzioni."
Infine, fai clic su Salva in alto a destra nella pagina Informazioni sull'agente. Anche in questo caso, l'applicazione di questa modifica richiederà un po' di tempo a causa del nostro meccanismo di memorizzazione nella cache, che garantisce velocità.
Fornire informazioni sull'orario di apertura
Per fornire queste informazioni agli utenti, invieremo un messaggio personalizzato utilizzando l'API Business Messages.
Potresti ricordare che i messaggi vengono analizzati nella funzione route_message di views.py. La funzione normalizza prima la stringa e poi inizia a verificare se il messaggio normalizzato corrisponde a uno dei parametri hardcoded. Per semplicità, aggiungiamo un'altra condizione in cui controlliamo se il messaggio normalizzato è uguale a una nuova costante che chiameremo CMD_BUSINESS_HOURS_INQUIRY e conterrà il valore "business-hours-inquiry". Se la condizione restituisce true, chiameremo una funzione chiamata send_message_with_business_hours.
La funzione route_message avrà il seguente aspetto:
bm-django-echo-bot/bopis/views.py
...
def route_message(message, conversation_id):
'''
Routes the message received from the user to create a response.
Args:
message (str): The message text received from the user.
conversation_id (str): The unique id for this user and agent.
'''
normalized_message = message.lower()
if normalized_message == CMD_RICH_CARD:
send_rich_card(conversation_id)
elif normalized_message == CMD_CAROUSEL_CARD:
send_carousel(conversation_id)
elif normalized_message == CMD_SUGGESTIONS:
send_message_with_suggestions(conversation_id)
elif normalized_message == CMD_BUSINESS_HOURS_INQUIRY:
send_message_with_business_hours(conversation_id)
else:
echo_message(message, conversation_id)
...
Affinché il codice funzioni, dovremo apportare altre due modifiche: la prima è definire CMD_BUSINESS_HOURS_INQUIRY insieme alle altre costanti, la seconda è definire effettivamente la funzione send_message_with_business_hours e inviare un messaggio utilizzando l'API Business Messages.
Definiamo innanzitutto la costante nella parte superiore del file con le altre dichiarazioni di costanti:
bm-django-echo-bot/bopis/views.py
...
# Set of commands the bot understands
CMD_RICH_CARD = 'card'
CMD_CAROUSEL_CARD = 'carousel'
CMD_SUGGESTIONS = 'chips'
CMD_BUSINESS_HOURS_INQUIRY = 'business-hours-inquiry'
...
Ora, per definire send_message_with_business_hours. Puoi definire questa funzione in qualsiasi punto del file, seguendo la sintassi Python appropriata. Poiché questa funzione invia semplicemente un messaggio, come echo_message, puoi utilizzarla come modello per definirla.
bm-django-echo-bot/bopis/views.py
...
def send_message_with_business_hours(conversation_id):
message = '''Thanks for contacting us! The hours for the store are:\n
MON 8am - 8pm\n
TUE 8am - 8pm\n
WED 8am - 8pm\n
THU 8am - 8pm\n
FRI 8am - 8pm\n
SAT 8am - 8pm\n
SUN 8am - 8pm
'''
message_obj = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BOT_REPRESENTATIVE,
text=message)
send_message(message_obj, conversation_id)
...
In questo modo, il nostro bot dovrebbe essere in grado di rispondere all'utente con questi orari di apertura quando invia il seguente messaggio: "business-hours-inquiry". Dovresti visualizzare qualcosa di simile al seguente:
Una volta eseguito il deployment del codice sorgente su Google Cloud, le modifiche saranno visibili immediatamente. Non memorizziamo nella cache l'applicazione web nella piattaforma Google Cloud nello stesso modo in cui vengono memorizzate nella cache le informazioni sugli agenti, quindi potrai testare subito questa esperienza.
Dato che abbiamo un po' di slancio con le modifiche all'origine, apportiamo un'altra modifica che consentirà a un utente di chiedere informazioni sugli acquisti online. L'agente digitale risponderà dicendo che la funzionalità non è ancora disponibile, ma che puoi tornare a controllare più tardi.
Comunicare all'utente che la funzionalità di acquisto online sarà presto disponibile
Applicheremo una modifica simile a quella che abbiamo fatto per informare l'utente sugli orari di apertura. Questa volta, inseriamo le informazioni in una scheda avanzata insieme a un'immagine accattivante.
Analizza il messaggio normalizzato e controlla una condizione per una costante denominata CMD_ONLINE_SHOPPING_INQUIRY con il valore impostato su "online-shopping-inquiry" che richiama send_online_shopping_info_message se la condizione è vera.
bm-django-echo-bot/bopis/views.py
...
# Set of commands the bot understands
CMD_RICH_CARD = 'card'
CMD_CAROUSEL_CARD = 'carousel'
CMD_SUGGESTIONS = 'chips'
CMD_BUSINESS_HOURS_INQUIRY = 'business-hours-inquiry'
CMD_ONLINE_SHOPPING_INQUIRY = 'online-shopping-inquiry'
...
...
...
def route_message(message, conversation_id):
'''
Routes the message received from the user to create a response.
Args:
message (str): The message text received from the user.
conversation_id (str): The unique id for this user and agent.
'''
normalized_message = message.lower()
if normalized_message == CMD_RICH_CARD:
send_rich_card(conversation_id)
elif normalized_message == CMD_CAROUSEL_CARD:
send_carousel(conversation_id)
elif normalized_message == CMD_SUGGESTIONS:
send_message_with_suggestions(conversation_id)
elif normalized_message == CMD_BUSINESS_HOURS_INQUIRY:
send_message_with_business_hours(conversation_id)
elif normalized_message == CMD_ONLINE_SHOPPING_INQUIRY:
send_online_shopping_info_message(conversation_id)
else:
echo_message(message, conversation_id)
...
Ora definiamo send_online_shopping_info_message. Vogliamo che questo messaggio venga inviato in una scheda avanzata con un'immagine, quindi copiamo la funzione send_rich_card da utilizzare come modello per definire send_online_shopping_info_message.
Per prima cosa dobbiamo aggiornare il testo alternativo per avere un messaggio appropriato. Il testo di riserva viene utilizzato se il dispositivo non può ricevere una scheda avanzata per qualche motivo. A questo punto, dobbiamo aggiornare BusinessMessagesRichCard in modo da includere un titolo, una descrizione, suggerimenti e un campo multimediale pertinenti. La nostra funzione dovrebbe avere il seguente aspetto:
bm-django-echo-bot/bopis/views.py
...
def send_online_shopping_info_message(conversation_id):
fallback_text = ('Online shopping will be available soon!')
rich_card = BusinessMessagesRichCard(
standaloneCard=BusinessMessagesStandaloneCard(
cardContent=BusinessMessagesCardContent(
title='Online shopping info!',
description='Thanks for your business, we are located in SF near the Golden Gate Bridge. Online shopping is not yet available, please check back with us in a few days.',
suggestions=[],
media=BusinessMessagesMedia(
height=BusinessMessagesMedia.HeightValueValuesEnum.MEDIUM,
contentInfo=BusinessMessagesContentInfo(
fileUrl=SAMPLE_IMAGES[4],
forceRefresh=False
))
)))
message_obj = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BOT_REPRESENTATIVE,
richCard=rich_card,
fallback=fallback_text)
send_message(message_obj, conversation_id)
...
Bene! Il nostro agente digitale ora può rispondere alle domande degli utenti sullo shopping online. Per il momento, il nostro agente digitale non supporta ancora gli acquisti online, pertanto forniamo all'utente un messaggio che lo informa che la funzionalità sarà disponibile a breve. Ecco l'aspetto del nostro agente digitale quando l'utente chiede informazioni sugli acquisti online.
Come la modifica precedente che abbiamo apportato per consentire a un utente di chiedere informazioni sugli orari di apertura, questa modifica può essere visualizzata immediatamente se utilizzi ngrok o non appena esegui il deployment del codice in App Engine di Google Cloud.
Nella parte successiva, utilizzeremo gli spunti di conversazione e i chip di suggerimento per indirizzare la conversazione verso il percorso ottimale.
Utilizzare i chip per guidare la conversazione
Abbiamo apportato alcune modifiche al codice sorgente e abbiamo implementato l'agente digitale aggiornato, ma non ci aspettiamo mai che gli utenti digitino "business-hours-inquiry" o "online-shopping-info" per chiedere informazioni sull'attività. Aggiorniamo gli approcci alla conversazione in modo che, quando la conversazione viene aperta, l'utente non riceva solo un bel messaggio di benvenuto, ma anche degli approcci alla conversazione.
Vai alla console Business Communications e accedi alla pagina Informazioni agente del tuo agente. In precedenza avevamo definito comandi iniziali per "chip", "scheda" e "carosello". Sebbene continuino a funzionare, non sono più pertinenti per la nostra attività. Puoi lasciarli per continuare a mostrare queste funzionalità avanzate o rimuoverli in modo che l'agente digitale mostri i comandi iniziali della conversazione specifici per l'attività Bonjour Meal.
Creeremo due nuovi spunti di conversazione. Per il primo, imposta il testo su "Qual è il tuo orario di apertura?" e imposta i Dati postback su "business-hours-inquiry". Per il secondo argomento di conversazione, imposta il testo su "Posso effettuare acquisti qui?" e imposta i Dati postback su "online-shopping-info".
Il risultato dovrebbe essere la configurazione mostrata nello screenshot seguente:
Come per le altre modifiche apportate in Business Communications Console, la propagazione richiederà del tempo prima che tu possa vedere le modifiche apportate sul tuo dispositivo mobile.
Ora che abbiamo terminato con gli spunti di conversazione, ci serve anche un modo per guidare l'utente verso un percorso ottimale una volta iniziata la conversazione. È possibile utilizzare i chip in modo contestuale dopo l'invio di un messaggio per indirizzare l'utente ad altre funzionalità dell'agente digitale. Pertanto, invieremo un messaggio con un suggerimento per fare qualcos'altro con l'agente ogni volta che l'utente chiede informazioni sugli orari di apertura o sugli acquisti online.
Alla fine della funzione, aggiungi quanto segue:
bm-django-echo-bot/bopis/views.py
...
def send_online_shopping_info_message(conversation_id):
...
# at the end of the function, send a message with suggestions
message_obj = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BOT_REPRESENTATIVE,
text='Let us know how else we can help you:',
fallback='Please let us know how else we can help you.',
suggestions=[
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Business hours',
postbackData='business-hours-inquiry')
),
])
send_message(message_obj, conversation_id)
...
# Let's do the same with the business hours
def send_message_with_business_hours(conversation_id):
...
# at the end of the function, send a message with suggestions
message_obj = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BOT_REPRESENTATIVE,
text='Let us know how else we can help you:',
fallback='Please let us know how else we can help you.',
suggestions=[
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Can I purchase online?',
postbackData='online-shopping-inquiry')
),
])
send_message(message_obj, conversation_id)
...
Tieni presente che il campo di testo all'interno di un BusinessMessagesSuggestion è limitato a 25 caratteri, come descritto nella documentazione.
Con gli spunti di conversazione aggiornati e l'uso strategico dei chip di suggerimento, ecco alcuni screenshot dell'esperienza utente prevista.
6. Complimenti
Congratulazioni, hai creato il tuo primo agente digitale Business Messages.
Hai eseguito il deployment di un'applicazione web per supportare il tuo agente digitale su Business Messages, hai utilizzato la Business Communications Console per modificarlo e hai definito l'esperienza utente con un agente digitale apportando modifiche al codice sorgente.
Ora conosci i passaggi chiave necessari per creare un'esperienza di Business Messages interattiva e le possibilità da qui in poi sono entusiasmanti. L'agente può essere esteso per supportare la ricerca dell'inventario o introdurre un carrello degli acquisti per monitorare gli interessi dell'utente. Puoi utilizzare un carosello per mostrare gli articoli del menu e, utilizzando i suggerimenti, consentire all'utente di selezionare gli articoli che lo interessano.
Ecco un'anteprima di come potrebbe essere.
Come faccio a creare un'esperienza di conversazione ottimale?
I migliori agenti forniscono all'utente informazioni contestuali e allo stesso tempo funzionalità durante la conversazione, in modo che possa interagire con l'attività come farebbe normalmente per telefono o di persona. Pensa a come i seguenti argomenti potrebbero essere utili per una conversazione con un'azienda con cui collabori.
Fornire il contesto e definire le aspettative
Fornire il contesto può includere qualsiasi cosa, dall'indicare esplicitamente in che modo puoi aiutare l'utente all'introduzione dell'agente digitale con una persona con cui l'utente può relazionarsi. Gli agenti di successo di Business Messages utilizzano l'avatar rappresentativo per mostrare all'utente con chi sta parlando.
L'impostazione delle aspettative dipende dall'esperienza utente che stai creando. Ad esempio, se il tuo agente supporta la ricerca dell'inventario, prima di fornire la risposta comunica all'utente che la disponibilità potrebbe essere ridotta.
Fornire funzionalità all'utente
I consumatori interagiscono con le attività in ogni momento. Da richieste come il controllo dello stato di un ordine al controllo della disponibilità di un articolo, Business Messages può supportare interazioni complesse con gli utenti. Molti utenti continuano a chiamare le attività per telefono per ricevere risposte alle loro domande, anche se le risposte sono disponibili sul sito web delle attività. Di conseguenza, le attività devono investire più risorse per gestire il volume di chiamate, soprattutto durante le festività.
Mantenere l'utente coinvolto
Fornisci punti di contatto di conversazione per mantenere l'utente coinvolto nella conversazione. Tra un messaggio e l'altro, puoi richiamare gli indicatori di digitazione per far sapere all'utente che stai elaborando una risposta.
Con funzionalità avanzate come indicatori di digitazione, chip di suggerimento, schede avanzate e caroselli, puoi guidare l'utente attraverso esperienze utente ottimali per aiutarlo a completare determinate attività, ad esempio ordinare da un menu di articoli. L'obiettivo è ridurre il traffico di chiamate sulla linea telefonica di un'attività.
È fondamentale che una conversazione fornisca funzionalità all'utente. Gli utenti che contattano un'attività tramite messaggistica si aspettano di ricevere risposte rapide alle loro domande. In una situazione non ideale, l'agente digitale non può facilitare la conversazione, il che potrebbe portare a un'esperienza utente negativa. Fortunatamente, esistono dei modi per aggirare il problema, ad esempio trasferendo la conversazione a un agente in tempo reale, come vedremo in un prossimo codelab.
Passaggi successivi
Quando è tutto pronto, consulta alcuni dei seguenti argomenti per scoprire le interazioni più complesse che puoi realizzare in Business Messages
- Vita di un agente: dalla creazione al lancio
- Requisiti e linee guida
- Linee guida per i loghi
- Tutte le guide
Documentazione di riferimento
- SuggestedReply
- Documento di riferimento per i messaggi di Business Messages
- Definizione JSON per RichCard