En esta página, se explica cómo configurar y responder a los comandos de barra para tus App de Google Chat
Un comando de barra es una forma común en que los usuarios invocan un App de Chat Los comandos de barra también ayudan a los usuarios a descubrir usar las funciones clave de una app de Chat.
Para usar un comando de barra, los usuarios escriben una barra (/
) y, luego, un comando de texto corto,
como /about
, para obtener información sobre la app de Chat.
Los usuarios pueden descubrir los comandos de barra disponibles si escriben una barra
Google Chat, que muestra una ventana con los comandos disponibles para el
App de Chat:
![Ventana de comandos de barra](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/slash-command-window.png?authuser=5&hl=es)
Para decidir si debes configurar comandos de barra y comprender cómo diseñar interacciones de los usuarios, ver Define todos los recorridos del usuario.
Comandos de barra con respuestas privadas
Cuando un usuario envía un mensaje que contiene un comando de barra, el mensaje solo visibles para el usuario y la app de Chat. Si Configuraste tu app de Chat para que se agregue a los espacios con varias personas, podrías responder al comando de barra de forma privada, para mantener la privacidad de la interacción entre el usuario y el App de Chat
Por ejemplo, para saber sobre una app de Chat
descubrir en un espacio, los usuarios pueden usar comandos como /about
o /help
.
Para evitar notificar a todas las demás personas del espacio,
Chat puede responder de forma privada con información sobre lo siguiente:
cómo usar la app de Chat y obtener asistencia.
Requisitos previos
Node.js
Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.
Apps Script
Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva en Apps Script, completa esta guía de inicio rápido.
Python
Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.
Configura un comando de barra
En esta sección, se explica cómo completar los siguientes pasos para configurar una barra :
- Crea un nombre para tu comando de barra.
- Configura el comando de barra en la API de Google Chat.
Asigna un nombre a tu comando de barra
El nombre de un comando de barra es lo que los usuarios escriben en un mensaje de Chat para invocar la app de Chat. Una descripción breve también debajo del nombre, para solicitar más información a los usuarios sobre cómo usar el comando:
![Nombre y descripción del comando de barra](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/slash-command-description.png?authuser=5&hl=es)
Cuando elijas un nombre y una descripción para tu comando de barra, ten en cuenta la las siguientes recomendaciones:
Para asignarle un nombre a tu comando de barra, sigue estos pasos:
- Usa palabras o frases cortas, descriptivas y prácticas para que la
comandos claros y simples para el usuario. Por ejemplo, en lugar de decir
/createAReminder
, usa/remindMe
. - Si tu comando contiene más de una palabra, ayuda a los usuarios a leerlo.
Usando todas las letras en minúscula para la primera palabra y, luego, con mayúscula en la primera
una letra de palabras adicionales. Por ejemplo, en lugar de
/updatecontact
, usa/updateContact
. - Considera si debes 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 reconocen y esperan, como
/settings
/feedback
De lo contrario, intenta usar nombres de comandos únicos, ya que si tu comando es el mismo que el de otras apps de Chat, el usuario filtrar usando comandos similares para encontrar y usar el tuyo.
- Usa palabras o frases cortas, descriptivas y prácticas para que la
comandos claros y simples para el usuario. Por ejemplo, en lugar de decir
Para describir tu comando de barra, haz lo siguiente:
- Mantén una descripción breve y clara para que los usuarios sepan qué esperar. cuando invocan el comando.
- Informa a los usuarios si hay algún requisito de formato para el comando.
Por ejemplo, si creas un comando
/remindMe
que requiere argumentos texto, establece la descripción en algo comoRemind me to do [something] at [time]
. - Informa a los usuarios si la app de Chat responde
con todos los miembros del espacio o de forma privada para el usuario que invoca el comando.
Por ejemplo, para el comando de barra
/about
, podrías describirlo de la siguiente manera:Learn about this app (Only visible to you)
Para responder de forma privada a un comando de barra, consulta la sección Responder con un mensaje privado.
Configura tu comando de barra en la API de Google Chat
Para crear un comando de barra, debes especificar información sobre el comando en la configuración de tu app de Chat para la API de Google Chat.
Para configurar un comando de barra en la API de Google Chat, completa los siguientes pasos: pasos:
En la consola de Google Cloud, haz clic en Menú > APIs y Servicios > APIs habilitadas y Servicios > API de Google Chat
Haz clic en Configuración.
En Comandos de barra, haz clic en Agregar un comando de barra.
Ingresa un nombre, un ID y una descripción para el comando:
- Nombre: El nombre visible del comando y lo que escriben los usuarios para invocar a tu app. Debe empezar con una barra, solo puede contener texto y puede tener hasta 50 caracteres.
- Descripción: El texto que describe cómo se debe usar y aplicar el formato el comando. Las descripciones pueden tener hasta 50 caracteres.
- ID de comando: un número del 1 al 1000 que el La app de Chat lo usa para reconocer el comando de barra y devolver una respuesta.
Opcional: Si quieres que tu app de Chat responda el comando con un diálogo, selecciona Casilla de verificación Abrir un diálogo.
Haz clic en Guardar.
El comando de barra ahora está configurado para la app de Chat.
Responde a un comando de barra
Cuando los usuarios crean un mensaje de Chat que contiene un comando de barra,
Tu app de Chat recibe un evento de interacción MESSAGE
.
La carga útil del evento contiene el slashCommand
y slashCommandMetadata
objetos. Estos objetos contienen detalles sobre el comando que se usó en el mensaje
(incluido el ID del comando), para que puedas devolver una respuesta adecuada.
![Mensaje privado para el
App de Chat de Cymbal Labs. El mensaje dice que la
Cymbal Labs creó una app de Chat, que comparte un vínculo
en la documentación y un vínculo
para comunicarse con el equipo de asistencia.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/private-message.png?authuser=5&hl=es)
/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 /help
controlando
MESSAGE
eventos de interacción y detección
si el mensaje contiene el ID de comando coincidente. Si el mensaje contiene
el ID del comando, la app de Chat
que explica cómo obtener ayuda:
Node.js
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
return res.send('Hello! This function is meant to be used in Google Chat app.');
}
const event = req.body;
// Checks for the presence of event.message.slashCommand.
// If the slash command is "/help", responds with a private text message.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case 'ID': // The ID for your slash command
return res.json({
privateMessageViewer: event.user, // Optional. Responds privately to the slash command.
text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
});
}
}
// If the Chat app doesn't detect a slash command, it responds
// with a private text message
return res.json({
privateMessageViewer: event.user,
text: 'Try a slash command.'
});
};
Apps Script
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
return {
"privateMessageViewer": event.user, // Optional. Responds privately to the slash command.
"text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
};
}
}
else {
return { "text": "Try a slash command.", "privateMessageViewer": event.user };
}
}
Python
from typing import Any, Mapping
import flask
import functions_framework
@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
"""Responds to a MESSAGE event in Google Chat.
Args:
req (flask.Request): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
if req.method == 'GET':
return 'Hello! This function must be called from Google Chat.'
request = req.get_json(silent=True)
# Checks for the presence of event.message.slashCommand.
# If the slash command is "/help", responds with a private text message.
if request.get('message', {}).get('slashCommand'):
command_id = request.get('message', {}).get('slashCommand').get('commandId')
if command_id == 'ID': # The ID for your slash command
return {
'privateMessageViewer': request.get('user'),
'text': (
'This Chat app was created by Cymbal Labs. To get help with this'
' app, <https://cymbalgroup.com/docs|see our documentation> or'
' <https://cymbalgroup.com/support|contact our support team>.'
),
}
return {
'privateMessageViewer': request.get('user'), # Optional. Responds privately to the slash command.
'text': 'Try a slash command.',
}
Reemplaza ID
por el ID del comando que estableciste.
que se especifica cuando
configuraste el comando de barra en la API de Chat.
Para probar este código, consulta
Prueba las funciones interactivas de las apps de Google Chat.
Temas relacionados
- Consulta ejemplos de la app de Chat que usan comandos de barra
- Envía un mensaje
- Cómo enviar mensajes privados
- Cómo abrir diálogos interactivos