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, el mensaje solo es visible para el usuario y la app de Chat.
Para decidir si debes compilar comandos y comprender cómo diseñar las interacciones de los usuarios, consulta Define todos los recorridos del usuario.
Tipos de comandos de las apps de Chat
Puedes crear comandos de la app de Chat como comandos de barra, comandos rápidos o acciones de mensajes. Para usar cada tipo de comando, los usuarios pueden hacer lo siguiente:-
Comandos de barra: Los usuarios pueden seleccionar un comando de barra en el menú o escribir una barra (
/) y, luego, un texto predefinido, como/about. Por lo general, las apps de Chat requieren texto de argumento para el comando de barra.Crea un comando de barra si tu app de Chat requiere entradas adicionales del usuario. Por ejemplo, puedes crear un comando de barra llamado
/searchque se ejecute después de que el usuario ingrese una frase para buscar, como/search receipts. -
Comandos rápidos: Los usuarios usan comandos abriendo el menú desde el área de respuesta de un mensaje de Chat. Para usar un comando, deben hacer clic en Agregar
y seleccionar un comando del menú.
Crea una respuesta estándar rápida si tu app de Chat puede responder al usuario de inmediato, sin esperar entradas adicionales. Por ejemplo, puedes crear un comando rápido llamado Imagen aleatoria que responda de inmediato con una imagen.
-
Acciones de mensajes: Los usuarios usan las acciones de mensajes colocando el cursor sobre un mensaje y haciendo clic en el menú de tres puntos. Para usar un comando, abre el menú de tres puntos y selecciona un comando del menú.
Crea una acción de mensaje si tu app de Chat puede realizar acciones según el contexto de un mensaje.
En las siguientes imágenes, se muestra cómo los usuarios descubren el menú de comandos de barra, comandos rápidos y acciones de mensajes:
Requisitos previos
HTTP
Una app de Google Chat que recibe interacciones de los usuarios y responde a ellas Para compilar una, completa la guía de inicio rápido de HTTP.
Apps Script
Una app de Google Chat que recibe interacciones de los usuarios y responde a ellas Para compilar uno, completa la guía de inicio rápido de Apps Script.
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.
- Opcional: Asigna comandos a instrucciones de inicio.
Asigna un nombre y una descripción al comando
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 para otras apps de Chat, el usuario deberá filtrar los comandos similares para encontrar y usar el tuyo.
Para describir un comando, haz lo siguiente:
- 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 como
Remind me to do [something] at [time]. - Informa a los usuarios si la app de Chat responde a todos los miembros del espacio o
en privado 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, un comando rápido o una acción de mensaje, especifica información sobre el comando o la acción 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:
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 de la conexión, ve a Activadores y especifica los detalles del extremo. Debes usar este activador en la siguiente sección para responder al comando.
- URL del extremo HTTP: Puedes especificar una URL de extremo HTTP común aquí. Como alternativa, para usar diferentes extremos HTTP para diferentes activadores, especifica el extremo directamente en el campo Comando de la app.
- Apps Script: Ingresa el ID de implementación de Apps Script. De forma predeterminada,
se invocará la función
onAppCommand. Para usar una función de Apps Script diferente, especifica el nombre de la función personalizada en el campo Comando de la app.
En Comandos, haz clic en Agregar un comando.
Ingresa la siguiente información sobre el comando:
- ID de comando: Es un número del 1 al 1000 que usa tu app de Chat para reconocer el comando y devolver una respuesta.
- Descripción: Es el texto que describe cómo usar y dar formato al comando. Las descripciones pueden tener hasta 50 caracteres.
- Tipo de comando: Selecciona Comando rápido, Comando de barra o Acción de mensaje.
- Especifica un nombre para el comando:
- Nombre del comando rápido: Es el nombre visible que los usuarios seleccionan en el menú para invocar el comando. Puede tener hasta 50 caracteres y, además, incluir
caracteres especiales. Por ejemplo,
Remind me - Nombre del comando de barra: Es el texto que escriben los usuarios para invocar el
comando en un mensaje. Debe comenzar con una barra, contener solo texto y
puede tener hasta 50 caracteres. Por ejemplo,
/remindMe - Nombre de la acción de mensaje: Es el nombre visible que los usuarios seleccionan en el menú para invocar la acción de mensaje. Puede tener hasta 50 caracteres y
puede incluir caracteres especiales. Por ejemplo,
Remind me
- Nombre del comando rápido: Es el nombre visible que los usuarios seleccionan en el menú para invocar el comando. Puede tener hasta 50 caracteres y, además, incluir
caracteres especiales. Por ejemplo,
Opcional: Mensaje de notificación de carga: Es un mensaje de notificación de aviso que se muestra al usuario mientras se ejecuta la acción del mensaje. Solo está disponible para las acciones de mensajes que no abren diálogos.
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.
Asigna comandos a instrucciones de inicio
Puedes destacar tus comandos como instrucciones de inicio para que los usuarios los vean como chips interactivos cuando inicien un mensaje directo 1:1 vacío con tu app de Chat.
Para asignar un comando a una instrucción de inicio, sigue estos pasos:
- Asegúrate de que tu comando sea un comando de barra o un comando rápido. Las acciones de mensajes no se pueden asignar a instrucciones de inicio.
- En la consola de Google Cloud, ve a la página Configuración de la API de Chat.
- En Funciones interactivas > Instrucciones de inicio, haz clic en Agregar instrucción o comando predeterminado.
- Establece la Clasificación (del 1 al 3) para el orden de visualización. Cada instrucción configurada debe tener un rango único.
- En Selección de tipo, selecciona Comando.
- En el menú ID de comando, selecciona tu comando.
- Haz clic en Listo y, luego, en Guardar.
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 (event.chat.appCommandPayload) contiene un objeto appCommandPayload con detalles sobre el comando que se invocó (incluidos el ID y el tipo de comando) para que puedas devolver una respuesta adecuada.
El objeto de evento se envía al extremo HTTP o a la función de Apps Script
que especificaste cuando
configuraste el activador del comando de la app.
/help para explicar cómo obtener asistencia.Cómo responder a un comando de barra o un comando rápido
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
comandos de barra o comandos rápidos, la app de Chat controla
objetos de evento (event.chat.appCommandPayload) de un activador de comando de app.
Cuando la carga útil de un objeto de evento contiene un ID de comando coincidente, la app de Chat devuelve la acción DataActions con un objeto createMessageAction (hostAppDataAction.chatDataAction.createMessageAction):
Node.js
Python
Java
Apps Script
Para usar esta muestra de código, reemplaza ABOUT_COMMAND_ID por el
ID del comando que especificaste cuando
configuraste el comando en la API de Chat.
Cómo responder a una acción de mensaje
En el siguiente código, se muestra un ejemplo de una app de Chat que responde a la acción de mensaje Recordarme con un mensaje de texto. Para responder
a las acciones de mensajes, la app de Chat controla los objetos de evento
desde un activador de comando de la app. Cuando la carga útil de un objeto de evento contiene un
ID de comando de acción de mensaje, la app de Chat devuelve la
acción DataActions con un
objeto createMessageAction:
Node.js
/**
* Responds to an APP_COMMAND interaction event from Google Chat.
*
* @param {Object} event The interaction event from Google Chat.
* @param {Object} res The HTTP response object.
* @return {Object} The JSON response message with a confirmation.
*/
function onAppCommand(event, res) {
// Collect the command ID and type from the event metadata.
const {appCommandId, appCommandType} =
event.chat.appCommandPayload.appCommandMetadata;
if (appCommandType === 'MESSAGE_ACTION' &&
appCommandId === REMIND_ME_COMMAND_ID) {
// Message actions can access the context of the message they were
// invoked on, such as the text or sender of that message.
const messageText = event.chat.appCommandPayload.message.text;
// Return a response that includes details from the original message.
return res.json({
"hostAppDataAction": {
"chatDataAction": {
"createMessageAction": {
"message": {
"text": `Setting a reminder for message: "${messageText}"`
}
}
}
}
});
}
}
Python
def on_app_command(event):
"""Responds to an APP_COMMAND interaction event from Google Chat.
Args:
event (dict): The interaction event from Google Chat.
Returns:
dict: The JSON response message with a confirmation.
"""
# Collect the command ID and type from the event metadata.
payload = event.get('chat', {}).get('appCommandPayload', {})
metadata = payload.get('appCommandMetadata', {})
if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:
# Message actions can access the context of the message they were
# invoked on, such as the text or sender of that message.
message_text = payload.get('message', {}).get('text')
# Return a response that includes details from the original message.
return {
"hostAppDataAction": {
"chatDataAction": {
"createMessageAction": {
"message": {
"text": f'Setting a reminder for message: "{message_text}"'
}
}
}
}
}
Java
/**
* Responds to an APP_COMMAND interaction event from Google Chat.
*
* @param event The interaction event from Google Chat.
* @param response The HTTP response object.
*/
void onAppCommand(JsonObject event, HttpResponse response) throws Exception {
// Collect the command ID and type from the event metadata.
JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
JsonObject metadata = payload.getAsJsonObject("appCommandMetadata");
String appCommandType = metadata.get("appCommandType").getAsString();
if (appCommandType.equals("MESSAGE_ACTION")) {
int commandId = metadata.get("appCommandId").getAsInt();
if (commandId == REMIND_ME_COMMAND_ID) {
// Message actions can access the context of the message they were
// invoked on, such as the text or sender of that message.
String messageText = payload.getAsJsonObject("message").get("text").getAsString();
// Return a response that includes details from the original message.
JsonObject responseMessage = new JsonObject();
responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
JsonObject createMessageAction = new JsonObject();
createMessageAction.add("message", responseMessage);
JsonObject chatDataAction = new JsonObject();
chatDataAction.add("createMessageAction", createMessageAction);
JsonObject hostAppDataAction = new JsonObject();
hostAppDataAction.add("chatDataAction", chatDataAction);
JsonObject finalResponse = new JsonObject();
finalResponse.add("hostAppDataAction", hostAppDataAction);
response.getWriter().write(finalResponse.toString());
}
}
}
Apps Script
/**
* Responds to an APP_COMMAND interaction event in Google Chat.
*
* @param {Object} event The interaction event from Google Chat.
* @return {Object} The JSON response message with a confirmation.
*/
function onAppCommand(event) {
// Collect the command ID and type from the event metadata.
const {appCommandId, appCommandType} =
event.chat.appCommandPayload.appCommandMetadata;
if (appCommandType === 'MESSAGE_ACTION' &&
appCommandId === REMIND_ME_COMMAND_ID) {
// Message actions can access the context of the message they were
// invoked on, such as the text or sender of that message.
const messageText = event.chat.appCommandPayload.message.text;
// Return a response that includes details from the original message.
return CardService.newChatResponseBuilder()
.setText("Setting a reminder for message: " + messageText)
.build();
}
}
Para usar esta muestra de código, reemplaza REMIND_ME_COMMAND_ID por
el ID del comando que especificaste cuando
configuraste el comando en la API de Chat.
Prueba el comando
Para probar el comando y el código, consulta Prueba las funciones interactivas de las apps de Google Chat.
Para aprender a probar y usar el comando en la IU de Chat, consulta Usa apps en Google Chat en la documentación de ayuda de Google Chat.
Temas relacionados
- Consulta ejemplos de apps de Chat que usan comandos
- Enviar un mensaje
- Cómo abrir diálogos interactivos
Apps de Chat que no son complementos: Responden a comandos
La siguiente documentación se aplica a las apps de Chat que no son complementos de Google Workspace. Para migrar una app de Chat que no sea un complemento, consulta Cómo convertir una app de Google Chat en un complemento de Google Workspace.
Cuando los usuarios usan un comando, una app de Chat que no es un
complemento recibe un
evento de interacción
y puede responder devolviendo un objeto Message directamente.
La carga útil del evento contiene metadatos con detalles sobre el comando que se
invocó (incluidos el ID y el tipo de comando), para que puedas devolver
una respuesta adecuada.
Para responder a cada tipo de comando en una app de Chat que no sea un complemento, debes controlar diferentes tipos de eventos y objetos de metadatos en la carga útil del evento:
| Tipo de comando | Tipo de evento | Metadatos de comandos |
|---|---|---|
| Comando de barra | MESSAGE |
message.slashCommand
o message.annotation.slashCommand |
| Comando rápido | APP_COMMAND |
appCommandMetadata
|
| Acción de mensaje | APP_COMMAND |
appCommandMetadata
|
Cómo responder a un comando de barra
En el siguiente código, se muestra un ejemplo de una app de Chat que
no es un complemento que responde al comando de barra
/about. La app de Chat
controla los eventos de interacción MESSAGE, detecta si el evento de interacción
contiene el ID de comando coincidente y devuelve un objeto Message privado:
Node.js
Apps Script
Python
Java
Reemplaza ABOUT_COMMAND_ID por el ID de comando que
especificaste cuando configuraste el comando en la consola de Google Cloud.
Cómo responder a un comando rápido
En el siguiente código, se muestra un ejemplo de una app de Chat que
no es un complemento que responde al comando rápido
Ayuda. La app de Chat
controla los eventos de interacción APP_COMMAND, detecta si el evento de interacción
contiene el ID de comando coincidente y devuelve un objeto Message privado:
Node.js
Apps Script
Python
Java
Reemplaza HELP_COMMAND_ID por el ID de comando que
especificaste cuando configuraste el comando en la consola de Google Cloud.
Cómo responder a una acción de mensaje
En el siguiente código, se muestra un ejemplo de una app de Chat que no es un complemento que responde a la acción de mensaje Recordarme. La
app de Chat controla los eventos de interacción APP_COMMAND,
detecta si el evento de interacción contiene el ID de comando coincidente y
devuelve un objeto Message privado:
Node.js
/**
* Responds to an APP_COMMAND interaction event from Google Chat.
*
* @param {Object} event The interaction event from Google Chat.
* @param {Object} res The HTTP response object.
* @return {Object} The JSON response message with a confirmation.
*/
function handleAppCommand(event, res) {
// Collect the command ID and type from the event metadata.
const {appCommandId, appCommandType} = event.appCommandMetadata;
// Use appCommandType to detect message actions.
if (appCommandType === 'MESSAGE_ACTION' &&
appCommandId === REMIND_ME_COMMAND_ID) {
// Message actions can access the context of the message they were
// invoked on, such as the text or sender of that message.
const messageText = event.message.text;
// Return a response that includes details from the original message.
return res.send({
text: `Setting a reminder for this message: "${messageText}"`
});
}
}
Apps Script
/**
* Responds to an APP_COMMAND interaction event in Google Chat.
*
* @param {Object} event The interaction event from Google Chat.
* @return {Object} The JSON response message with a confirmation.
*/
function onAppCommand(event) {
// Collect the command ID and type from the event metadata.
const {appCommandId, appCommandType} = event.appCommandMetadata;
if (appCommandType === 'MESSAGE_ACTION' &&
appCommandId === REMIND_ME_COMMAND_ID) {
// Message actions can access the context of the message they were
// invoked on, such as the text or sender of that message.
const messageText = event.message.text;
// Return a response that includes details from the original message.
return { "text": "Setting a reminder for message: " + messageText };
}
}
Python
def handle_app_command(event):
"""Responds to an APP_COMMAND interaction event from Google Chat.
Args:
event (dict): The interaction event from Google Chat.
Returns:
dict: The JSON response message with a confirmation.
"""
# Collect the command ID and type from the event metadata.
metadata = event.get('appCommandMetadata', {})
if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:
# Message actions can access the context of the message they were
# invoked on, such as the text or sender of that message.
message_text = event.get('message', {}).get('text')
# Return a response that includes details from the original message.
return {
"text": f'Setting a reminder for message: "{message_text}"'
}
Java
/**
* Responds to an APP_COMMAND interaction event from Google Chat.
*
* @param event The interaction event from Google Chat.
* @param response The HTTP response object.
*/
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
// Collect the command ID and type from the event metadata.
JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
String appCommandType = metadata.get("appCommandType").getAsString();
if (appCommandType.equals("MESSAGE_ACTION")) {
int commandId = metadata.get("appCommandId").getAsInt();
if (commandId == REMIND_ME_COMMAND_ID) {
// Message actions can access the context of the message they were
// invoked on, such as the text or sender of that message.
String messageText = event.getAsJsonObject("message").get("text").getAsString();
// Return a response that includes details from the original message.
JsonObject responseMessage = new JsonObject();
responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
response.getWriter().write(responseMessage.toString());
}
}
}
Reemplaza REMIND_ME_COMMAND_ID por el ID de comando que
especificaste cuando configuraste el comando en la consola de Google Cloud.