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.google.cn/static/workspace/chat/images/slash-command-window.png?authuser=5&hl=es)
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.
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.
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.google.cn/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 información sobre el comando de barra
incluido slashCommand
y slashCommandMetadata
. Usarás estos campos para identificar el ID del comando y mostrar un valor
respuesta.
En el siguiente ejemplo, se muestra la carga útil de JSON para un evento de interacción MESSAGE
.
que incluya el comando de barra /vote
:
{
...
"message": {
...
"text": "/vote yes",
"argumentText": " yes",
"slashCommand": {
"commandId": 2
},
"annotations": [
{
"length": 5,
"startIndex": 0,
"type": "SLASH_COMMAND",
"slashCommand": {
"commandName":"/vote",
"commandId":1,
"type": "INVOKE",
"bot": {
"avatarUrl": "https://www.example.com/images/vote-app-icon.png",
"displayName": "Voter Chat App",
"name": "users/1234567890987654321",
"type": "BOT"
}
}
}
]
}
}
Para responder a un comando de barra, puedes detectar si el campo slashCommand
está presente en la carga útil del evento y, de ser así, devolverá una respuesta al comando.
En la siguiente muestra de código, se indica cómo responder a un evento de interacción MESSAGE
que contiene un comando de barra:
Node.js
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} function in response to a slash command.
*/
exports.onMessage = function onMessage(req, res) {
// Stores the Google Chat event as a variable.
var event = req.body;
// Checks for the presence of event.message.slashCommand.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
res.json(runFunction); // The response to the slash command.
}
}
Apps Script
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} function in response to a slash command.
*/
function onMessage(event) {
// Checks for the presence of event.message.slashCommand
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
return runFunction; // The response to the slash command.
}
}
}
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 that includes a slash command.
Args:
req (flask.Request): the event object from Chat API.
Returns:
Mapping[str, Any]: function in response to a slash command.
"""
if req.method == 'GET':
return 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if slash_command := request.get('message', dict()).get('slashCommand'):
command_id = slash_command['commandId']
if command_id == ID:
return runFunction
Para usar el código, reemplaza lo siguiente:
ID
: Es el ID del comando que especificas cuando configura el comando de barra en la API de Google Chat.runFunction
: Es una función que crea una respuesta a el comando de barra.
Opcional: Responde con un mensaje privado
Los mensajes que contienen comandos de barra solo son visibles para el usuario que envió el y la app de Chat que recibe el comando. 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, si un equipo usa una app de Chat que administra
un servicio de atención al cliente, los usuarios pueden invocar un comando de barra como
/myCases
para ver los casos de asistencia que se le asignaron. Si el equipo agrega
de Chat a un espacio (un usuario que usa este comando de barra)
en el espacio podría querer que la app de Chat responda
de ellos. Para evitar publicar los casos de asistencia del usuario para todas las personas en el espacio,
La app de Chat puede responder de forma privada.
Para responder a un comando de barra de forma privada, consulta Envía mensajes privados a usuarios de Google Chat.
Ejemplo completo: Configura contactos con la app de Rolodex Chat
En el siguiente ejemplo, se muestra una app de Chat que responde los siguientes comandos de barra:
- El comando
/help
devuelve un mensaje de texto que explica cómo obtener asistencia con la app de Chat. El ID del comando está configurado a1
. - El comando
/createContact
abre un cuadro de diálogo en el que los usuarios pueden ingresar detalles sobre un contacto. El ID del comando está configurado como2
.
Antes de ejecutar esta muestra, sigue los pasos para Configura los comandos de barra en la API de Google Chat.
Node.js
/**
* Responds to messages that have links whose URLs
* match URL patterns configured for link previews.
*
* @param {Object} event The event object from Chat
* API.
*
* @return {Object} Response from the Chat app
* attached to the message with the previewed link.
*/
exports.onMessage = function onMessage(req, res) {
// Store the Google Chat event as a variable.
const event = req.body;
if (req.method === "GET" || !event.message) {
res.send("Hello! This function is meant to be used in a Google Chat " +
"Space.");
}
// Checks for the presence of event.message.slashCommand.
// If the slash command is "/help", responds with a text message.
// If the slash command is "/createContact", opens a dialog.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case 1: // /help
res.json({"text": "Contact bot helps you update your address book!"});
case 2: // /createContact
res.json(openDialog(event));
}
}
// If the Chat app doesn"t detect a slash command, it responds
// with a card that prompts the user to add a contact
else {
res.json({
"cardsV2": [{
"cardId": "addContact",
"card": {
"header": {
"title": "Rolodex",
"subtitle": "Manage your contacts!",
"imageUrl": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"imageType": "CIRCLE"
},
"sections": [
{
"widgets": [
{
"buttonList": {
"buttons": [
{
"text": "Add Contact",
"onClick": {
"action": {
"function": "openDialog",
"interaction": "OPEN_DIALOG"
}
}
}
]
}
}
]
}
]
}
}]
});
}
// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {
if (event.common.invokedFunction === "openDialog") {
res.json(openDialog(event));
}
if (event.common.invokedFunction === "openSequentialDialog") {
res.json(openSequentialDialog(event));
}
if (event.common.invokedFunction === "confirmDialogSuccess") {
res.json(confirmDialogSuccess(event));
}
}
};
/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
return {
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"textInput": {
"label": "Name",
"type": "SINGLE_LINE",
"name": "name"
}
},
{
"textInput": {
"label": "Address",
"type": "MULTIPLE_LINE",
"name": "address"
}
},
{
"decoratedText": {
"text": "Add to favorites",
"switchControl": {
"controlType": "SWITCH",
"name": "saveFavorite"
}
}
},
{
"decoratedText": {
"text": "Merge with existing contacts",
"switchControl": {
"controlType": "SWITCH",
"name": "mergeContact",
"selected": true
}
}
},
{
"buttonList": {
"buttons": [
{
"text": "Next",
"onClick": {
"action": {
"function": "openSequentialDialog"
}
}
}
]
}
}
]
}
]
}
}
}
}
};
};
/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openSequentialDialog(event) {
return {
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"textInput": {
"label": "Notes",
"type": "MULTIPLE_LINE",
"name": "notes"
}
},
{
"selectionInput": {
"type": "RADIO_BUTTON",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
{
"buttonList": {
"buttons": [
{
"text": "Submit",
"onClick": {
"action": {
"function": "confirmDialogSuccess",
"parameters": [
{
"key": "confirmDialogSuccess",
"value": "confirmDialogSuccess"
}
]
}
}
}
]
},
"horizontalAlignment": "END"
}
]
}
]
}
}
}
}
};
}
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.contactName.stringInputs.value[0] === "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": {
"statusCode": "OK",
"userFacingMessage": "Don't forget to name your new contact!"
}
}
}
};
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
Apps Script
En este ejemplo, se envía un mensaje de tarjeta mostrando JSON de la tarjeta. También puedes usar Servicio de tarjetas de Apps Script.
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 that includes the /createContact
slash command by opening a dialog.
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 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if request.get('type') == 'CARD_CLICKED':
invoked_function = request.get('common', dict()).get('invokedFunction')
if invoked_function == 'open_dialog':
return open_dialog(request)
elif invoked_function == 'open_sequential_dialog':
return open_dialog(request)
elif invoked_function == "receive_dialog":
return receive_dialog(request)
else:
return {
'cardsV2': [{
'cardId': 'addContact',
'card': {
'header': {
'title': 'Rolodex',
'subtitle': 'Manage your contacts!',
'imageUrl': 'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
'imageType': 'CIRCLE'
},
'sections': [
{
'widgets': [
{
'buttonList': {
'buttons': [
{
'text': 'Add Contact',
'onClick': {
'action': {
'function': 'open_dialog',
'interaction': 'OPEN_DIALOG'
}
}
}
]
}
}
]
}
]
}
}]
}
def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a dialog in Google Chat.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return {
'action_response': {
'type': 'DIALOG',
'dialog_action': {
'dialog': {
'body': {
'sections': [
{
'header': 'Add new contact',
'widgets': [
{
'textInput': {
'label': 'Name',
'type': 'SINGLE_LINE',
'name': 'name'
}
},
{
'textInput': {
'label': 'Address',
'type': 'MULTIPLE_LINE',
'name': 'address'
}
},
{
'decoratedText': {
'text': 'Add to favorites',
'switchControl': {
'controlType': 'SWITCH',
'name': 'saveFavorite'
}
}
},
{
'decoratedText': {
'text': 'Merge with existing contacts',
'switchControl': {
'controlType': 'SWITCH',
'name': 'mergeContact',
'selected': True
}
}
},
{
'buttonList': {
'buttons': [
{
'text': 'Next',
'onClick': {
'action': {
'function': 'open_sequential_dialog'
}
}
}
]
}
}
]
}
]
}
}
}
}
}
def open_sequential_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a second dialog that lets users add more contact details.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return {
'action_response': {
'type': 'DIALOG',
'dialog_action': {
'dialog': {
'body': {
'sections': [
{
'header': 'Add new contact',
'widgets': [
{
'textInput': {
'label': 'Notes',
'type': 'MULTIPLE_LINE',
'name': 'notes'
}
},
{
'selectionInput': {
'type': 'RADIO_BUTTON',
'label': 'Contact type',
'name': 'contactType',
'items': [
{
'text': 'Work',
'value': 'Work',
'selected': False
},
{
'text': 'Personal',
'value': 'Personal',
'selected': False
}
]
}
},
{
'buttonList': {
'buttons': [
{
'text': 'Submit',
'onClick': {
'action': {
'function': 'receive_dialog',
'parameters': [
{
'key': 'receiveDialog',
'value': 'receiveDialog'
}
]
}
}
}
]
},
'horizontalAlignment': 'END'
}
]
}
]
}
}
}
}
}
def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
"""Checks for a form input error, the absence of a "name" value, and returns
an error if absent. Otherwise, confirms successful receipt of a dialog.
Args:
event (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: the response.
"""
if event.get('common', dict()) \
.get('formInputs', dict()).get('contactName', dict()) \
.get('stringInputs').get('value', list()):
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'OK'
}
}
}
else:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': "Don't forget to name your new contact!"
}
}
}