Creare interfacce di Google Chat

Questa pagina fornisce una panoramica su come creare interfacce utente per i componenti aggiuntivi di Google Workspace che estendono Google Chat.

Per creare interfacce per le app di chat, utilizza i seguenti componenti aggiuntivi:

  • Trigger: i modi in cui gli utenti di Google Chat possono richiamare un'app di Chat, ad esempio aggiungendola a uno spazio o inviandole un messaggio.
  • Oggetti evento: i dati che le app di chat ricevono da trigger o interazioni con la UI.
  • Azioni: i modi in cui le app di chat possono rispondere alle interazioni, ad esempio inviando messaggi o restituendo un'interfaccia utente basata su schede.
L'app di chat riceve un oggetto evento da un trigger Aggiunto allo spazio
Figura 1: quando un utente aggiunge un'app Chat a uno spazio, viene attivato il trigger Aggiunta allo spazio e viene inviato un oggetto evento. Per rispondere con un messaggio, l'app Chat gestisce l'oggetto evento e restituisce un'azione che crea il messaggio.

Le app di chat possono creare e visualizzare schede nelle seguenti interfacce:

  • Messaggi che possono contenere testo, schede statiche o interattive e pulsanti.
  • Finestre di dialogo, ovvero schede che si aprono in una nuova finestra e in genere richiedono agli utenti di inviare informazioni.
  • Anteprime dei link, ovvero schede che mostrano in anteprima le informazioni su un servizio esterno.

Trigger

Questa sezione spiega i trigger utilizzati dai componenti aggiuntivi di Google Workspace in Chat.

I trigger sono i modi specifici in cui gli utenti richiamano un'app di chat utilizzando l'interfaccia utente di Chat, ad esempio utilizzando @menzioni o comandi dell'app.

La tabella seguente mostra i trigger di Chat, una descrizione e la risposta tipica delle app di chat:

Trigger Descrizione Risposta tipica
Aggiunta allo spazio

Un utente aggiunge l'app Chat a uno spazio oppure un amministratore di Google Workspace installa l'app Chat negli spazi di messaggistica diretta per gli utenti della sua organizzazione. Per informazioni sulle app di chat installate dagli amministratori, vedi Installare le app del Marketplace nel tuo dominio nella documentazione del Centro assistenza per gli amministratori di Google Workspace.

 L'app Chat invia un messaggio di onboarding che spiega cosa fa e come gli utenti dello spazio possono interagire con l'app.
Messaggio

Un utente interagisce con l'app Chat in un messaggio in uno dei seguenti modi:

  • Invia un messaggio in uno spazio di messaggi diretti con l'app di Chat.
  • @menziona l'app di chat in qualsiasi tipo di spazio.
  • Invia un messaggio che contiene un link che corrisponde al pattern URL per le anteprime dei link.
  • Digita il testo nel menu a selezione multipla di un selectionInput widget.
 L'app Chat risponde in base ai contenuti del messaggio. Ad esempio, un'app di chat risponde al comando slash /about con un messaggio che spiega le attività che l'app di chat può svolgere.
Rimossa dallo spazio

Un utente rimuove l'app Chat da uno spazio oppure un amministratore di Google Workspace disinstalla l'app Chat per un utente della sua organizzazione.

Gli utenti non possono rimuovere le app di chat installate dall'amministratore. Se un utente aveva precedentemente installato l'app Chat, questa rimane installata indipendentemente dal fatto che un amministratore di Google Workspace tenti di disinstallarla.

 L'app Chat rimuove tutte le notifiche in arrivo configurate per lo spazio (ad esempio l'eliminazione di un webhook) e cancella la memoria interna. Le app di chat non possono rispondere con messaggi a questo trigger perché non sono più membri dello spazio.
Comando app

Un utente utilizza un comando dell'app Chat.

 L'app Chat risponde al comando. Ad esempio, risposte con un messaggio o apre una finestra di dialogo.

A differenza di altri componenti aggiuntivi di Google Workspace, devi configurare le funzioni di callback per questi trigger utilizzando l'API Google Chat. Per indicazioni, vedi Configurare un'app Google Chat.

Per rispondere a un trigger, consulta le seguenti guide:

Oggetti evento

Le app di chat ricevono oggetti evento quando viene attivato un trigger di Chat o quando gli utenti di Chat interagiscono con un'interfaccia utente dell'app Chat (ad esempio, facendo clic su un pulsante). L'oggetto evento contiene dati sull'interazione che l'app Chat può utilizzare per rispondere o aggiornare un'interfaccia utente.

Per informazioni sulla gestione degli oggetti evento, consulta le seguenti guide:

Per informazioni sugli oggetti evento dei componenti aggiuntivi in Chat e altre applicazioni Google Workspace, vedi Oggetti evento.

Azioni chat

Questa sezione spiega come le app di chat possono utilizzare le azioni dei componenti aggiuntivi per rispondere alle interazioni degli utenti.

Per rispondere con un'azione del componente aggiuntivo, un'app di chat deve rispondere entro 30 secondi e la risposta deve essere pubblicata nello spazio in cui si è verificata l'interazione. In caso contrario, l'app di Chat deve configurare l'autenticazione e chiamare l'API Google Chat per rispondere.

Le app di chat possono gestire e rispondere alle interazioni in molti modi. In molti casi, le app di chat rispondono con un messaggio. Le app di chat possono anche cercare alcune informazioni da una fonte di dati, registrare le informazioni sull'oggetto dell'evento o qualsiasi altra cosa. Questo comportamento di elaborazione definisce essenzialmente l'app Google Chat.

Per rispondere alle interazioni degli utenti, le app Chat devono gestire l'oggetto evento corrispondente e restituire uno dei seguenti oggetti JSON:

Risposta dell'app di chat Azione richiesta per il reso
Inviare o aggiornare un messaggio. DataActions
Apri, aggiorna o chiudi una finestra di dialogo. RenderActions
Per raccogliere informazioni da una scheda o una finestra di dialogo, suggerisci elementi di selezione in base a ciò che gli utenti digitano in un menu a selezione multipla. RenderActions
Visualizzare l'anteprima dei link nei messaggi che gli utenti di Chat inviano in uno spazio. DataActions

Rispondere utilizzando l'API Google Chat

Anziché restituire un'azione del componente aggiuntivo, le app di chat potrebbero dover utilizzare l'API Google Chat per rispondere a un'interazione. Ad esempio, le app Chat devono chiamare l'API Google Chat per eseguire una delle seguenti operazioni:

  • Rispondere a un'interazione dopo 30 secondi.
  • Eseguire attività al di fuori dello spazio in cui si è svolta l'interazione.
  • Svolgere attività in Chat che non sono disponibili come azioni dei componenti aggiuntivi. Ad esempio, elenca gli spazi di cui un utente o un'app di chat è membro oppure aggiungi utenti a uno spazio.
  • Esegui attività per conto dell'utente di Chat (che richiede l'autenticazione dell'utente).

Per scoprire di più sull'autenticazione e sulla chiamata dell'API Chat, consulta la Panoramica dell'API Chat.