En esta página, se explica cómo configurar y responder comandos como una app de Google Chat.
Los comandos ayudan a los usuarios a descubrir y usar las funciones clave de una app de chat. Solo las apps de chat pueden ver el contenido de un comando. Por ejemplo, si un usuario envía un mensaje con un comando de barra, solo el usuario y la app de Chat pueden verlo.
Para decidir si debes compilar comandos y comprender cómo diseñar las interacciones del usuario, consulta Define todos los recorridos del usuario.
Tipos de comandos de la app de Chat
Puedes compilar comandos de la app de Chat como comandos de barra o comandos rápidos. Para descubrir y usar cada tipo de comando, los usuarios hacen lo siguiente:-
Comandos de barra: Los usuarios envían comandos como mensajes escribiendo una barra (
/) y, luego, un texto predefinido, como/about. Las apps de chat también pueden requerir texto de argumento para el comando de barra. Por ejemplo, el comando barra/searchpuede requerir texto de argumento que se usa para una búsqueda. -
Comandos rápidos: Los usuarios usan comandos abriendo el menú desde el área de respuesta de un mensaje de Chat. Para usar un comando, hace clic en Agregar
y selecciona un comando del menú.
-
Figura 1: Para descubrir y usar los comandos de barra, los usuarios deben escribir una barra /en el área de respuesta, seguida del nombre del comando. -
Figura 2: Los usuarios descubren y usan los comandos rápidos desde el menú en el área de respuesta de un mensaje de Chat.
Requisitos previos
- Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat
- Crea un proyecto de Google Cloud
- Configura la pantalla de consentimiento de OAuth.
- Habilita las siguientes APIs de Google Workspace:
- API de Google Chat
- API de complementos de Google Workspace
- Un extremo HTTP que aloja la arquitectura de servicios de tu app de chat.
- Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat
- Crea un proyecto de Google Cloud
- Configura la pantalla de consentimiento de OAuth.
- Habilita la API de Google Chat.
- Crea un proyecto independiente de Apps Script y activa el servicio de Chat avanzado.
- Configura Chat en el manifiesto. Para ello, agrega el objeto
addons.chaty los permisos necesarios (oauthScopes) o los prefijos de URL HTTPS (urlFetchWhitelist).
Configura el comando
En esta sección, se explica cómo completar los siguientes pasos para configurar un comando:
- Crea un nombre y una descripción para el comando.
- Configura el comando en la consola de Google Cloud.
Asigna un nombre al comando y descríbelo
El nombre de un comando es lo que los usuarios escriben o seleccionan para invocar la app de Chat. También aparece una breve descripción debajo del nombre para indicarles a los usuarios cómo usar el comando:
Cuando elijas un nombre y una descripción para tu comando, ten en cuenta las siguientes recomendaciones:
Para asignar un nombre a un comando, sigue estos pasos:
- Usa palabras o frases cortas, descriptivas y prácticas para que los comandos sean claros para el usuario. Por ejemplo, en lugar del nombre
Create a reminder, usaRemind me. - Considera usar un nombre único o común para tu comando. Si tu comando describe una interacción o función típica, puedes usar un nombre común que los usuarios reconozcan y esperen, como
SettingsoFeedback. De lo contrario, intenta usar nombres de comandos únicos, ya que, si el nombre de tu comando es el mismo que el de otras apps de Chat, el usuario deberá filtrar comandos similares para encontrar y usar el tuyo.
Para describir un comando, sigue estos pasos:
- Mantén la descripción breve y clara para que los usuarios sepan qué esperar cuando usen el comando.
- Informa a los usuarios si hay algún requisito de formato para el comando. Por ejemplo, si creas un comando de barra que requiere texto de argumento, establece la descripción en algo como
Remind me to do [something] at [time]. - Informa a los usuarios si la app de Chat responde a todos los usuarios del espacio o de forma privada al usuario que invoca el comando. Por ejemplo, para el comando rápido
About, puedes describirlo comoLearn about this app (Only visible to you).
Configura el comando en la consola de Google Cloud
Para crear un comando de barra o rápido, debes especificar información sobre el comando en la configuración de la app de Chat para la API de Google Chat.
Para configurar un comando en la API de Google Chat, completa los siguientes pasos: o configurar un comando de barra en la API de Google Chat, completa los siguientes pasos:
En la consola de Google Cloud, haz clic en Menú > APIs y servicios > APIs y servicios habilitados > API de Google Chat
Haz clic en Configuración.
En Configuración avanzada, ve a Activadores y verifica que el campo App command contenga un activador, como un extremo HTTP o una función de Apps Script. Debes usar este activador en la siguiente sección para responder al comando.
En Comandos, haz clic en Agregar un comando.
Ingresa la siguiente información sobre el comando:
- ID de comando: Es un número de 1 a 1,000 que usa tu app de chat para reconocer el comando y mostrar una respuesta.
- Tipo de comando: Selecciona Comando rápido o Comando de barra.
- Si estás configurando un comando de barra, ingresa un valor para el campo Nombre del comando de barra para especificar lo que los usuarios escriben para invocar el comando. Debe comenzar con una barra diagonal, contener solo texto y
puede tener hasta 50 caracteres. Por ejemplo,
/remindMe - Nombre: Es el nombre fácil de usar para el comando. Los nombres pueden tener hasta 50 caracteres y pueden incluir caracteres especiales.
- Descripción: Es el texto que describe cómo usar y dar formato al comando. Las descripciones pueden tener hasta 50 caracteres.
Opcional: Si quieres que tu app de Chat responda al comando con un diálogo, selecciona la casilla de verificación Abrir un diálogo.
Haz clic en Guardar.
El comando ahora está configurado para la app de Chat.
Cómo responder un comando
Cuando los usuarios usan un comando, tu app de Chat recibe un objeto de evento.
La carga útil del evento contiene un objeto appCommandPayload con detalles sobre el comando que se invocó (incluidos el ID y el tipo de comando) para que puedas mostrar una respuesta adecuada. El objeto del evento se envía al extremo HTTP o a la función de Apps Script que especificaste cuando configuraste el activador de comando de la app.
/help para explicar cómo obtener asistencia.En el siguiente código, se muestra un ejemplo de una app de chat que responde al comando de barra /about con un mensaje de texto. Para responder a los comandos de barra, la app de Chat controla los objetos de eventos de un activador de comando de app. Cuando la carga útil de un objeto de evento contiene un ID de comando de barra, la app de Chat muestra la acción DataActions con un objeto 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.'
}}}}};
}
}
Para usar esta muestra de código, reemplaza ABOUT_COMMAND_ID por el
ID de comando que especificaste cuando
configuraste el comando en la API de Chat.
Prueba el comando
Para probar el comando y el código, consulta Cómo probar funciones interactivas para apps de Google Chat.
Para aprender a probar y usar el comando en la IU de Chat, consulta Cómo usar apps en Google Chat en la documentación de ayuda de Google Chat.
Temas relacionados
- Consulta muestras de apps de Chat que usan comandos
- Envía un mensaje
- Abrir diálogos interactivos