Responde a comandos de barra en Google Chat

En esta página, se explica cómo configurar una app de Google Chat para que responda a los comandos de barra.

En Google Chat, los complementos aparecen para los usuarios como apps de Google Chat. Para obtener más información, consulta la descripción general de la extensión de Google Chat.

Un comando de barra es una forma común en la que los usuarios invocan e interactúan con una app de Chat. Los comandos de barra también ayudan a los usuarios a descubrir y usar funciones clave de una app de Chat. Para decidir si debes configurar comandos de barra y comprender cómo diseñar interacciones del usuario, consulta Define todos los recorridos del usuario en la documentación de la API de Chat.

Cómo usan los usuarios los comandos de barra

Para usar un comando de barra, los usuarios escriben una barra (/) y, luego, un comando de texto breve, como /about, para obtener información sobre la app de Chat. Los usuarios pueden descubrir los comandos de barra disponibles escribiendo una barra en Google Chat, que muestra una ventana con una lista de los comandos disponibles para la app de Chat:

Cuando un usuario envía un mensaje que contiene un comando de barra, solo el usuario y la app de Chat pueden verlo. Si configuraste tu app de Chat para que se agregue a espacios con varias personas, te recomendamos que respondas el comando de barra de forma privada para mantener la interacción privada entre el usuario y la app de Chat.

Por ejemplo, para obtener información sobre una app de Chat que descubren en un espacio, los usuarios pueden usar comandos como /about o /help. Para evitar notificar a todos los demás usuarios del espacio, la app de Chat puede responder de forma privada con información sobre cómo usar la app de Chat y obtener asistencia.

Requisitos previos

Configura un comando de barra

En esta sección, se explica cómo completar los siguientes pasos para configurar un comando de barra:

1. Crea un nombre para tu comando de barra.
2. Configura el comando de barra en la API de Google Chat.

Asigna un nombre al 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. También aparece una descripción breve debajo del nombre para indicarles a los usuarios cómo usar el comando:

Cuando elijas un nombre y una descripción para tu comando de barra, ten en cuenta las siguientes recomendaciones:

• Para asignar un nombre a tu comando de barra, sigue estos pasos:

  • Usa palabras o frases cortas, descriptivas y prácticas para que los comandos sean claros y simples para el usuario. Por ejemplo, en lugar de decir /createAReminder, usa /remindMe.
  • Si el comando contiene más de una palabra, usa todas las letras minúsculas para la primera palabra y, luego, mayúsculas para la primera letra de las palabras adicionales para ayudar a los usuarios a leerlo. Por ejemplo, en lugar de /updatecontact, usa /updateContact.
  • Considera si usarás 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 /settings o /feedback. 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 tu comando de barra, haz lo siguiente:

  • Mantén la descripción breve y clara para que los usuarios sepan qué esperar cuando invoquen 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 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 en el espacio o de forma privada al usuario que invoca el comando. Por ejemplo, para el comando de barra /about, puedes describirlo como Learn about this app (Only visible to you).

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 la 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:

1. En la consola de Google Cloud, haz clic en Menú menu > APIs y servicios > APIs y servicios habilitados > API de Google Chat

   Ir a la página de la API de Google Chat

2. Haz clic en Configuración.

3. En Configuración avanzada, ve a Activadores y verifica que el campo MESSAGE 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 slash.

4. En Comandos de barra, haz clic en Agregar un comando de barra.

5. Ingresa un nombre, un ID de comando y una descripción para el comando:

   1. Nombre: Es el nombre visible del comando y lo que los usuarios escriben para invocar tu app. Debe comenzar con una barra, contener solo texto y puede tener hasta 50 caracteres.
   2. Descripción: Es el texto que describe cómo usar y dar formato al comando. Las descripciones pueden tener hasta 50 caracteres.
   3. ID de comando: Es un número de 1 a 1,000 que usa tu app de Chat para reconocer el comando de barra y mostrar una respuesta.

6. Opcional: Si deseas que tu app de Chat responda al comando con un diálogo, selecciona la casilla de verificación Abrir un diálogo.

7. Haz clic en Guardar.

El comando de barra ya está configurado para la app de Chat.

Responde a un comando de barra

Cuando los usuarios crean un mensaje de Chat, tu app de Chat recibe un objeto de evento que contiene información sobre el mensaje. El objeto del evento contiene una carga útil con detalles sobre el comando que se usó en el mensaje (incluido el ID del comando) para que puedas mostrar una respuesta adecuada.

Para responder a un comando de barra, debes implementar el activador de mensaje para que tu app de Chat pueda controlar cualquier objeto de evento que contenga metadatos de comando de barra.

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 mensaje. 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}});
        }
    }

    // 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;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}};
        }
    }

    // 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 }
                    }]
                }]
            }
        }]
    }}}}};
}

Para usar esta muestra de código, reemplaza ABOUT_COMMAND_ID por el ID de comando que especificaste cuando configuraste el comando slash en la API de Chat.