Questa pagina spiega come configurare e rispondere ai comandi come app Google Chat.
I comandi aiutano gli utenti a scoprire e utilizzare le funzionalità chiave di un'app di chat. Solo le app di chat possono vedere i contenuti di un comando. Ad esempio, se un utente invia un messaggio con un comando barra, il messaggio è visibile solo all'utente e all'app Chat.
Per decidere se creare comandi e per capire come progettare le interazioni degli utenti, consulta Definire tutti i percorsi degli utenti.
Tipi di comandi dell'app Chat
Puoi creare comandi per l'app Chat come comandi con barra o comandi rapidi. Per scoprire e utilizzare ogni tipo di comando, gli utenti devono:-
Comandi slash: gli utenti inviano comandi come messaggi digitando una barra (
/
) e poi un testo predefinito, ad esempio/about
. Le app di chat possono anche richiedere il testo dell'argomento per il comando slash. Ad esempio, il comando barra/search
può richiedere il testo dell'argomento utilizzato per una query di ricerca. -
Comandi rapidi:gli utenti utilizzano i comandi aprendo il menu dall'area di risposta di un messaggio di Chat. Per utilizzare un comando, fa clic su Aggiungi
e seleziona un comando dal menu.
-
Figura 1. Gli utenti scoprono e utilizzano i comandi slash digitando una barra /
nell'area di risposta seguita dal nome del comando. -
Figura 2. Gli utenti scoprono e utilizzano i comandi rapidi dal menu nell'area di risposta di un messaggio di Chat.
Prerequisiti
- Un account Google Workspace Business o Enterprise con accesso a Google Chat.
- Crea un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Abilita le seguenti API Google Workspace:
- API Google Chat
- API Google Workspace Add-ons
- Un endpoint HTTP che ospita l'architettura di servizio per la tua app Chat.
- Un account Google Workspace Business o Enterprise con accesso a Google Chat.
- Crea un progetto Google Cloud.
- Configura la schermata per il consenso OAuth.
- Abilita l'API Google Chat.
- Crea un progetto Apps Script autonomo e attiva il servizio Chat avanzato.
- Configura Chat nel file manifest,
aggiungendo l'oggetto
addons.chat
e gli eventuali ambiti richiesti (oauthScopes
) o i prefissi degli URL HTTPS (urlFetchWhitelist
).
Configura il comando
Questa sezione spiega come completare i seguenti passaggi per configurare un comando:
- Crea un nome e una descrizione per il comando.
- Configura il comando nella console Google Cloud.
Assegna un nome e una descrizione al comando
Il nome di un comando è ciò che gli utenti digitano o selezionano per richiamare l'app Chat. Sotto il nome viene visualizzata anche una breve descrizione per fornire agli utenti ulteriori informazioni su come utilizzare il comando:

Quando scegli un nome e una descrizione per il comando, tieni presente i seguenti consigli:
Per assegnare un nome a un comando:
- Utilizza parole o frasi brevi, descrittive e strategiche per rendere i comandi chiari per l'utente. Ad esempio, anziché il nome
Create a reminder
, utilizzaRemind me
. - Valuta la possibilità di utilizzare un nome univoco o comune per il comando. Se il comando descrive una
funzionalità o un'interazione tipica, puoi utilizzare un nome comune riconosciuto e previsto dagli utenti,
ad esempio
Settings
oFeedback
. In caso contrario, prova a utilizzare nomi di comandi unici, perché se il nome del comando è lo stesso per altre app di chat, l'utente deve filtrare i comandi simili per trovare e utilizzare il tuo.
Per descrivere un comando:
- Mantieni la descrizione breve e chiara in modo che gli utenti sappiano cosa aspettarsi quando utilizzano il comando.
- Comunica agli utenti se sono previsti requisiti di formattazione per il comando. Ad esempio, se
crei un comando slash che richiede il testo dell'argomento, imposta la descrizione su qualcosa come
Remind me to do [something] at [time]
. - Comunica agli utenti se l'app Chat risponde a tutti gli utenti nello spazio o
in privato all'utente che richiama il comando. Ad esempio, per il comando rapido
About
, puoi descriverlo comeLearn about this app (Only visible to you)
.
Configura il comando nella console Google Cloud
Per creare un comando rapido o con barra, specifica le informazioni sul comando nella configurazione dell'app Chat per l'API Google Chat.
Per configurare un comando nell'API Google Chat, completa i seguenti passaggi: o per configurare un comando con barra nell'API Google Chat, completa i seguenti passaggi:
Nella console Google Cloud, fai clic su Menu > API e servizi > API e servizi abilitati > API Google Chat
Fai clic su Configurazione.
In Impostazioni avanzate, vai a Trigger e controlla che il campo Comando app contenga un trigger, ad esempio un endpoint HTTP o una funzione di Apps Script. Devi utilizzare questo trigger nella sezione seguente per rispondere al comando.
In Comandi, fai clic su Aggiungi un comando.
Inserisci le seguenti informazioni sul comando:
- ID comando:un numero compreso tra 1 e 1000 utilizzato dall'app Chat per riconoscere il comando e restituire una risposta.
- Tipo di comando:seleziona Comando rapido o Comando slash.
- Se stai configurando un comando slash, inserisci un valore per il campo Nome comando slash per specificare cosa devono digitare gli utenti per richiamare il comando. Deve iniziare con una barra, contenere solo testo e può avere fino a 50 caratteri. Ad esempio,
/remindMe
. - Nome:il nome facile da usare per il comando. I nomi possono contenere fino a 50 caratteri e possono includere caratteri speciali.
- Descrizione:il testo che descrive come utilizzare e formattare il comando. Le descrizioni possono contenere fino a 50 caratteri.
(Facoltativo) Se vuoi che l'app Chat risponda al comando con una finestra di dialogo, seleziona la casella di controllo Apri una finestra di dialogo.
Fai clic su Salva.
Il comando è ora configurato per l'app Chat.
Rispondere a un comando
Quando gli utenti utilizzano un comando, l'app Chat riceve un oggetto evento.
Il payload dell'evento contiene un oggetto
appCommandPayload
con dettagli sul comando invocato (incluso l'ID comando e il tipo di comando), in modo da poter restituire una risposta appropriata. L'oggetto evento viene inviato all'endpoint HTTP o alla funzione Apps Script specificata quando hai configurato l'attivatore Comando app.

/help
per spiegare come ricevere assistenza.Il codice seguente mostra un esempio di app Chat
che risponde al comando barra /about
con un messaggio. Per rispondere ai comandi slash, l'app Chat gestisce gli oggetti evento da un attivatore Comando app. Quando il payload di un oggetto evento contiene un ID comando con barra, l'app Chat restituisce l'azione DataActions
con un oggetto createMessageAction
:
// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;
/**
* Google Cloud Function that responds to events sent from a
* Google Chat space.
*
* @param {Object} req Request sent from Google Chat space
* @param {Object} res Response to send back
*/
exports.avatarApp = function avatarApp(req, res) {
if (req.method === 'GET' || !req.body.chat) {
return res.send('Hello! This function is meant to be used ' +
'in a Google Chat Space.');
}
// Stores the Google Chat event as a variable.
const chatEvent = req.body.chat;
// Handles events that contain payloads about commands
if (chatEvent.appCommandPayload) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;
// Executes the slash command logic based on its ID.
// Slash command IDs are set in the Google Chat API configuration.
switch (appCommandMetadata.appCommandId) {
case ABOUT_COMMAND_ID :
return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'The Avatar app replies to Google Chat messages.'
}}}}});
}
// Handles MESSAGE events
} else if (chatEvent.messagePayload) {
// Stores the Google Chat event as a variable.
const chatMessage = chatEvent.messagePayload.message;
// Replies with the sender's avatar in a card otherwise.
const displayName = chatMessage.sender.displayName;
const avatarUrl = chatMessage.sender.avatarUrl;
res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Here\'s your avatar',
cardsV2: [{
cardId: 'avatarCard',
card: {
name: 'Avatar Card',
header: {
title: `Hello ${displayName}!`,
},
sections: [{
widgets: [{
textParagraph: { text: 'Your avatar picture: ' }
}, {
image: { imageUrl: avatarUrl }
}]
}]
}
}]
}}}}});
}
};
// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
// Stores the Google Chat event as a variable.
const chatMessage = event.chat.messagePayload.message;
// Replies with the sender's avatar in a card otherwise.
const displayName = chatMessage.sender.displayName;
const avatarUrl = chatMessage.sender.avatarUrl;
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Here\'s your avatar',
cardsV2: [{
cardId: 'avatarCard',
card: {
name: 'Avatar Card',
header: {
title: `Hello ${displayName}!`,
},
sections: [{
widgets: [{
textParagraph: { text: 'Your avatar picture: ' }
}, {
image: { imageUrl: avatarUrl }
}]
}]
}
}]
}}}}};
}
/**
* Responds to an APP_COMMAND event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onAppCommand(event) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;
// Executes the slash command logic based on its ID.
// Slash command IDs are set in the Google Chat API configuration.
switch (appCommandMetadata.appCommandId) {
case ABOUT_COMMAND_ID :
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'The Avatar app replies to Google Chat messages.'
}}}}};
}
}
Per utilizzare questo esempio di codice, sostituisci ABOUT_COMMAND_ID
con l'ID comando specificato quando hai configurato il comando nell'API Chat.
Testa il comando
Per testare il comando e il codice, consulta Testare le funzionalità interattive per le app Google Chat.
Per scoprire come testare e utilizzare il comando nell'interfaccia utente di Chat, consulta Utilizzare le app in Google Chat nella documentazione della guida di Google Chat.
Argomenti correlati
- Visualizza esempi di app Chat che utilizzano i comandi
- Invia un messaggio
- Aprire finestre di dialogo interattive