Crea un componente aggiuntivo di Google Chat con Dialogflow ES

Anteprima per sviluppatori: disponibile nell'ambito del programma di anteprima per sviluppatori di Google Workspace, che concede l'accesso in anteprima a determinate funzionalità.

Questa pagina spiega come creare un'app Google Chat come componente aggiuntivo di Google Workspace che utilizza Dialogflow ES per comprendere e rispondere al linguaggio naturale. Puoi anche utilizzare Dialogflow CX, che ha un'integrazione diretta con Google Chat, per creare un'app Dialogflow CX Google Chat seguendo la guida Dialogflow CX Google Chat.

Obiettivi

• Configurare l'ambiente.
• Crea e implementa un agente Dialogflow ES.
• Crea e implementa un'app di chat basata sull'agente Dialogflow ES.
• Testa l'app Chat.

Prerequisiti

• Un account Google Workspace Business o Enterprise con accesso a Google Chat.
• Un progetto Google Cloud con la fatturazione abilitata. Per verificare che la fatturazione sia attivata per un progetto esistente, consulta Verifica lo stato di fatturazione dei progetti. Per creare un progetto e configurare la fatturazione, consulta Creare un progetto Google Cloud.

Architettura

Il seguente diagramma mostra l'architettura di un'app di chat creata con Dialogflow:

Nel diagramma precedente, un utente che interagisce con un'app di chat Dialogflow ha il seguente flusso di informazioni:

1. Un utente invia un messaggio in Chat a un'app di Chat, in un messaggio diretto o in uno spazio di Chat.
2. Un agente virtuale Dialogflow, che si trova in , riceve ed elabora il messaggio per produrre una risposta.
3. Se vuoi, utilizzando un webhook Dialogflow, l'agente Dialogflow può interagire con servizi esterni di terze parti, ad esempio un sistema di gestione dei progetti o uno strumento di gestione dei ticket.
4. L'agente Dialogflow invia una risposta al servizio dell'app di chat in Chat.
5. La risposta viene inviata allo spazio di Chat.

Configurare l'ambiente

Prima di utilizzare le API di Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

1. Nella console API di Google, abilita l'API Google Chat e l'API Dialogflow.

   Abilita le API

2. Verifica di abilitare le API nel progetto Cloud corretto, poi fai clic su Avanti.

3. Verifica di abilitare le API corrette, poi fai clic su Abilita.

Crea un agente Dialogflow ES

Se non hai un agente Dialogflow ES esistente:

1. Vai alla console di Dialogflow ES.
2. Fai clic su Crea agente.
3. Assegna un nome, seleziona una lingua predefinita e un fuso orario.
4. Associalo al tuo progetto Cloud.
5. Fai clic su Crea.
6. Crea intent ed entità in base alle esigenze del flusso conversazionale della tua app di chat. Puoi iniziare con un intent di saluto.
7. Prendi nota dell'ID progetto.

Per una guida dettagliata, vedi Creare un agente.

Crea un'app di chat e connettila all'agente Dialogflow

Dopo aver creato un agente Dialogflow ES, segui questi passaggi per trasformarlo in un'app di chat:

1. Nella console API di Google, vai all'API Google Chat. Cerca "API Google Chat" e fai clic su API Google Chat, poi su Gestisci.

   Vai all'API Chat

2. Fai clic su Configurazione e configura l'app Chat:

   1. In Nome dell'app, inserisci Dialogflow App.
   2. In URL avatar, inserisci https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
   3. In Descrizione, inserisci Responds to real human conversation.
   4. In Funzionalità, seleziona Partecipa a spazi e conversazioni di gruppo.
   5. Nella sezione Impostazioni di connessione, seleziona Dialogflow.
   6. Nella sezione Impostazioni di Dialogflow, seleziona Dialogflow ES.
   7. Rendi disponibile l'app di chat a utenti e gruppi specifici nel tuo dominio e inserisci il tuo indirizzo email.
   8. In Log, seleziona Errori di log in Logging.

3. Fai clic su Salva.

L'app Chat è pronta a ricevere e rispondere ai messaggi su Chat.

Testare l'app Chat

Testa l'app di chat Dialogflow ES inviando un messaggio in Google Chat.

1. Apri Google Chat utilizzando l'account Google Workspace che hai fornito quando ti sei aggiunto come tester attendibile.

   Vai a Google Chat

2. Fai clic su Nuova chat.
3. Nel campo Aggiungi una o più persone, digita il nome della tua app di Chat.

4. Seleziona l'app di chat dai risultati. Si apre un messaggio diretto.

   Nota:se non vedi la tua app di Chat nell'elenco dei risultati, assicurati di aver incluso il tuo account Google Workspace nelle impostazioni di visibilità della pagina di configurazione dell'API di Chat nella console API di Google.

5. Nel nuovo messaggio diretto con l'app, digita Hello e premi enter.

   L'app Dialogflow Chat risponde con un messaggio di saluto.

Risposte testuali

Le risposte di testo vengono inviate a Google Chat come messaggi. Con questa formattazione puoi mettere il testo in grassetto o in corsivo racchiudendolo tra determinati simboli (markdown light).

La risposta al messaggio di testo ha lo stesso aspetto della risposta di testo predefinita nella console Dialogflow. Tuttavia, la risposta API non elaborata avrà un aspetto leggermente diverso. Imposta anche la configurazione della piattaforma su GOOGLE_HANGOUTS, il che potrebbe essere interessante quando crei agenti per più integrazioni.

"fulfillmentMessages": [
{
   "text": {
   "text": [
        "This is a test."
   ]
},
  "platform": "GOOGLE_HANGOUTS"
},

Carte

Le risposte alle schede vengono inviate a Google Chat come messaggi con schede.

Immagini

Le risposte con immagini vengono inviate a Google Chat come widget immagine di Google Chat.

Payload personalizzato

Per inviare altri tipi di messaggi di Google Chat, puoi utilizzare un payload personalizzato�.

Il payload personalizzato di Google Chat ti consente di creare schede più avanzate. Una scheda può avere una o più sezioni. Ogni sezione può avere un'intestazione. Puoi consultare la Guida di riferimento per l'estensione delle schede di Chat dei componenti aggiuntivi di Google Workspace per vedere alcune delle combinazioni che puoi creare. Tuttavia, l'utilizzo di payload personalizzati significa che dovrai fornire il formato JSON.

Nota :quando copi e incolli gli esempi della guida di riferimento nella casella del payload personalizzato in Dialogflow, assicurati che l'editor non contenga errori di linting. Non puoi testare i risultati nel simulatore di Dialogflow, ma puoi farlo direttamente in Google Chat.

Ecco un esempio di payload personalizzato per la creazione di un messaggio con una scheda:

{ "hangouts": { "hostAppDataAction": { "chatDataAction": {
  "createMessageAction": { "message": { "cardsV2": [{
    "cardId": "pizza",
    "card": {
      "header": {
        "title": "Pizza Delivery Customer Support",
        "subtitle": "[e-mail]",
        "imageUrl": "https://goo.gl/aeDtrS"
      },
      "sections": [{ "widgets": [{ "textParagraph": {
        "text": " Your pizza is here!"
      }}]}]
    }
  }]}}
}}}}

Limiti e considerazioni

• Quando utilizzi i componenti aggiuntivi di Google Workspace con Dialogflow, gli oggetti evento di Chat presentano le seguenti limitazioni e considerazioni:
  • Eventi dell'app Home:il supporto per gli eventi APP_HOME non è ancora disponibile.
  • Input query Dialogflow:il testo inviato come input query all'agente Dialogflow dipende dal tipo di evento:
    • MESSAGE: il valore del campo argumentText del messaggio di chat.
    • APP_COMMAND: la stringa "APP_COMMAND_PAYLOAD".
    • ADDED_TO_SPACE: viene inviato un evento di benvenuto predefinito.
    • REMOVED_FROM_SPACE: la stringa "REMOVED_FROM_SPACE_PAYLOAD".
    • CARD_CLICKED: la stringa "BUTTON_CLICKED_PAYLOAD".
    • WIDGET_UPDATED: la stringa "WIDGET_UPDATED_PAYLOAD" (utilizzata per il completamento automatico).
  • Payload completo dell'evento:il payload JSON completo dell'evento di interazione di chat viene inviato a Dialogflow all'interno del campo WebhookRequest.payload. Puoi accedervi nel webhook di Dialogflow. Per saperne di più, consulta la documentazione relativa alla richiesta webhook di Dialogflow ES.
• Considerazioni per rispondere ai comandi e ricevere dati da schede o dialoghi:
  • Se l'agente Dialogflow deve elaborare il payload JSON dell'evento di interazione di chat, può farlo utilizzando un webhook Dialogflow per esaminare il payload personalizzato nel parametro di query.
  • Per visualizzare una finestra di dialogo dall'agente Dialogflow, rispondi con un singolo payload JSON personalizzato che contenga un oggetto RenderActions con la navigazione pushCard.
  • Per elaborare i dati inseriti dalle schede, puoi utilizzare un webhook Dialogflow e rispondere con un singolo payload JSON personalizzato contenente l'azione appropriata.
• Le anteprime dei link non sono supportate.
• Se l'agente Dialogflow risponde con un solo messaggio, questo viene inviato a Google Chat in modo sincrono. Se l'agente Dialogflow risponde con più messaggi, tutti i messaggi vengono inviati a Chat in modo asincrono chiamando il metodo create sulla risorsa spaces.messages nell'API Chat una volta per ogni messaggio.
• Quando utilizzi l'integrazione di Dialogflow ES con Chat, l'agente Dialogflow e l'app Chat devono essere configurati nello stesso progetto Google Cloud.

Risoluzione dei problemi

Per eseguire il debug dell'app Chat, inizia esaminando i log degli errori. Poiché questa app utilizza Dialogflow, hai a disposizione diverse risorse di logging e risoluzione dei problemi:

• Log dei componenti aggiuntivi di Google Workspace: esegui query sui log per informazioni dettagliate sul comportamento del componente aggiuntivo, incluse le interazioni con Chat. Consulta la sezione Eseguire query sui log per i componenti aggiuntivi di Google Workspace.

• Errori dell'app Google Chat:per messaggi di errore e correzioni generali dell'app Chat, consulta Risolvere i problemi e correggere gli errori dell'app Chat.

• Cronologia delle conversazioni di Dialogflow ES: Cronologia | Dialogflow ES

• Risoluzione dei problemi generali di Dialogflow: Risoluzione dei problemi | Dialogflow

Esegui la pulizia

Per evitare che al tuo account vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per questo tutorial, quando lo elimini, elimini anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL su appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più tutorial e guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google API, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

   Vai a Resource Manager

2. Nell'elenco dei progetti, seleziona quello da eliminare e fai clic su Elimina .
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Argomenti correlati

• Dialogflow CX è un altro modo per utilizzare Dialogflow con un'app di chat.