Creare interfacce di Google Chat

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

In Google Chat, i componenti aggiuntivi vengono visualizzati dagli utenti come app Google Chat. Per saperne di più, consulta la panoramica di Estensione di 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 attivatori o interazioni con l'interfaccia utente.
  • Azioni: i modi in cui le app di chat possono rispondere alle interazioni, ad esempio inviare messaggi o restituire un'interfaccia utente basata su schede.
L'app Chat riceve un oggetto evento da un trigger Aggiunto allo spazio
Figura 1: quando un utente aggiunge un'app di chat a uno spazio, l'attivatore Aggiunto allo spazio si attiva e invia 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 un'anteprima delle informazioni su un servizio esterno.

Trigger

Questa sezione spiega gli attivatori utilizzati dai componenti aggiuntivi di Google Workspace in Chat.

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

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

Trigger Descrizione Risposta tipica
Aggiunto allo spazio

Un utente aggiunge l'app Chat a uno spazio o un amministratore di Google Workspace installa l'app Chat negli spazi di messaggi diretti per gli utenti della sua organizzazione. Per informazioni sulle app di chat installate dagli amministratori, consulta Installare le app del Marketplace nel tuo dominio nella documentazione della Guida 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 essa.
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 (DM) con l'app Chat.
  • @menziona l'app Chat in qualsiasi tipo di spazio.
  • Invia un messaggio contenente un link che corrisponde al pattern URL per le anteprime dei link.
  • Digita il testo nel menu di 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 /about con un messaggio che spiega le attività che può svolgere.
Rimossi dallo spazio

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

Gli utenti non possono rimuovere le app di Chat installate dal loro amministratore. Se un utente ha installato in precedenza l'app Chat, l'app Chat rimane installata indipendentemente dal fatto che un amministratore di Google Workspace provi a disinstallarla.

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

Un utente utilizza un comando rapido o un comando con barra dall' app Chat.

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

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

Per rispondere a un trigger, consulta le seguenti guide:

Eventi

Questa sezione definisce e spiega tutti gli elementi degli oggetti evento Chat. Per saperne di più, consulta Oggetti evento.

Oggetto evento
commonEventObject object (CommonEventObject)
Un oggetto contenente informazioni comuni a tutti gli oggetti evento, indipendentemente dall'applicazione host.
chat object (Chat)
Un oggetto contenente tutte le informazioni sulle interazioni di Chat.

Chat

Chat
chat.user object (User)
L'utente Chat che ha interagito con l'app Chat.
chat.space object (Space)
Lo spazio di Chat in cui un utente ha interagito con l'app Chat.
chat.eventTime

string (Timestamp format)

L'ora in cui si è verificata l'interazione.

Campo unione payload.

payload può essere solo uno dei seguenti:
chat.messagePayload

object (MessagePayload)

Il payload che le app di Chat ricevono da un attivatore Message.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Il payload che le app di Chat ricevono da un trigger Aggiunto allo spazio.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Il payload che le app Chat ricevono da un attivatore Rimosso dallo spazio.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Il payload che le app di Chat ricevono quando gli utenti fanno clic su un pulsante di un messaggio o di una scheda. Se un utente fa clic su un pulsante per inviare informazioni, l'oggetto commonEventObject.formInputs contiene i valori raccolti dall'utente. Per maggiori dettagli, consulta Raccogliere informazioni dagli utenti di Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Il payload che le app di Chat ricevono quando gli utenti digitano del testo nel menu di selezione multipla di un selectionInput widget. Le app di chat possono utilizzare questo oggetto evento per compilare gli elementi suggeriti da un'origine dati dinamica. Ad esempio, per compilare le richieste di assistenza da un'origine dati esterna, un'app Chat può eseguire query sull'origine dati in base a quanto digitato dall'utente nel menu e poi restituire le richieste di assistenza corrispondenti come elementi selezionabili.

L'oggetto CommonEventObject.parameters['autocomplete_widget_query'] contiene il valore di stringa digitato dall'utente nel menu.

chat.appCommandPayload

object (AppCommandPayload)

Il payload che le app di Chat ricevono quando un utente utilizza un comando dall'app Chat.

Payload

A seconda del tipo di interazione, l'evento contiene un payload con una o più risorse dell'API Chat.

Payload del messaggio
MessagePayload
chat.messagePayload.message object (Message)
Il messaggio di Chat che ha attivato l'evento.
chat.messagePayload.space object (Space)
Lo spazio di Chat in cui un utente ha inviato il messaggio che ha richiamato l'app Chat.

Aggiunto al payload dello spazio
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Lo spazio di Chat a cui l'utente ha aggiunto o installato l'app Chat.

Quando gli amministratori installano le app di Chat, il campo space.adminInstalled viene impostato su true.

chat.addedToSpacePayload.interactionAdd boolean
Indica se un utente aggiunge l'app Chat a uno spazio utilizzando un messaggio. Ad esempio, @menziona l'app Chat o utilizza un comando con barra. Se true, Chat invia un altro oggetto evento con un messagePayload contenente informazioni sul messaggio.

Rimosso dal payload dello spazio
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Lo spazio di Chat da cui l'utente ha rimosso o disinstallato l'app Chat.

Quando gli amministratori disinstallano le app di Chat, il campo space.adminInstalled viene impostato su false.

Payload del clic sul pulsante
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Il messaggio di Chat contenente il pulsante su cui un utente ha fatto clic.
chat.buttonClickedPayload.space object (Space)
Lo spazio di Chat in cui l'utente ha fatto clic su un pulsante da un messaggio dell'app Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Indica se l'utente ha fatto clic sul pulsante per interagire con una finestra di dialogo.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Se isDialogEvent è true, il tipo di interazione in un dialogo.

Enum DialogEventType.

Il valore di dialogEventType può essere solo uno dei seguenti:
TYPE_UNSPECIFIED Valore predefinito. Non specificato.
REQUEST_DIALOG Un utente richiede una finestra di dialogo. Ad esempio, utilizzano un comando con barra diagonale o fanno clic su un pulsante di un messaggio.
SUBMIT_DIALOG Un utente fa clic su un elemento interattivo all'interno di una finestra di dialogo. Ad esempio, un utente compila le informazioni in una finestra di dialogo e fa clic su un pulsante per inviarle.

Payload del widget aggiornato
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Lo spazio di Chat in cui si è verificata l'interazione.

Payload del comando dell'app
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Metadati relativi al comando utilizzato dall'utente e al modo in cui lo ha attivato.
chat.appCommandPayload.space object (Space)
Lo spazio di Chat in cui un utente ha utilizzato il comando.
chat.appCommandPayload.thread object (Thread)
Se l'interazione si è verificata in un thread, il thread Chat in cui l'utente ha utilizzato il comando.
chat.appCommandPayload.message object (Message)
Il messaggio inviato dall'utente con il comando slash.
chat.appCommandPayload.configCompleteRedirectUri string
Se per il comando è richiesta l'autorizzazione o la configurazione, un URL a cui indirizzare l'utente al termine della procedura al di fuori di Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Indica se il comando apre una finestra di dialogo.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Il tipo di interazione con una finestra di dialogo.

Enum DialogEventType.

Il valore di dialogEventType può essere solo uno dei seguenti:
TYPE_UNSPECIFIED Valore predefinito. Non specificato.
REQUEST_DIALOG Un utente richiede una finestra di dialogo. Ad esempio, utilizzano un comando con barra diagonale o fanno clic su un pulsante di un messaggio.
SUBMIT_DIALOG Un utente fa clic su un elemento interattivo all'interno di una finestra di dialogo. Ad esempio, un utente compila le informazioni in una finestra di dialogo e fa clic su un pulsante per inviarle.
Metadati dei comandi dell'app
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

L'ID comando.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Il tipo di comando.

Enum AppCommandType.

Il valore di AppCommandType può essere solo uno dei seguenti:
APP_COMMAND_TYPE_UNSPECIFIED Valore predefinito. Non specificato.
SLASH_COMMAND Un utente utilizza il comando inviando un messaggio che inizia con una slash /.

Azioni chat

Questa sezione spiega in che modo le app di Chat possono utilizzare azioni dei componenti aggiuntivi per rispondere alle interazioni degli utenti.

Per rispondere con un'azione del componente aggiuntivo, un'app 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 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 un'origine data, registrare le informazioni sull'oggetto dell'evento o qualsiasi altra cosa. Questo comportamento di elaborazione è essenzialmente ciò che definisce l'app Google Chat.

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

Risposta desiderata 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 gli elementi di selezione in base a ciò che gli utenti digitano in un menu di selezione multipla. RenderActions
Visualizza l'anteprima dei link nei messaggi inviati dagli utenti di Chat 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 di 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 è verificata l'interazione.
  • Eseguire in Chat attività non disponibili come azioni dei componenti aggiuntivi. Ad esempio, elenca gli spazi di cui un utente o un'app di Chat è membro o aggiungi utenti allo spazio.
  • Eseguire attività per conto dell'utente di Chat (che richiede l'autenticazione dell'utente).

Per scoprire di più sull'autenticazione e sull'uso dell'API Chat, consulta la panoramica dell'API Chat.