Responde a los comandos de la app de Google Chat

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:

1. 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 /search puede requerir texto de argumento que se usa para una búsqueda.
2. 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ú.

En las siguientes imágenes, se muestra cómo los usuarios descubren un menú de comandos de barra y comandos rápidos:

• 

  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

Nota: Las muestras de código de esta guía están escritas para ejecutarse como una función de Google Cloud para Node.js, Python y Java.

Node.js

Una app de Google Chat que recibe y responde eventos de interacción. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Apps Script

Una app de Google Chat que recibe y responde eventos de interacción. Para crear una app de Chat interactiva en Apps Script, completa esta guía de inicio rápido.

Python

Una app de Google Chat que recibe y responde eventos de interacción. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Java

Una app de Google Chat que recibe y responde eventos de interacción. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Configura el comando

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

1. Crea un nombre y una descripción para el comando.
2. 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 más detalles sobre cómo usar el comando:

Figura 3: El nombre y la descripción de un comando de barra.

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, usa Remind 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 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 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 como Learn 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:

1. En la consola de Google Cloud, haz clic en Menú > 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 Comandos, haz clic en Agregar un comando.

4. Ingresa un ID, una descripción, un tipo y un nombre para 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.
   • Descripción: Es el texto que describe lo que hace el comando. Las descripciones pueden tener hasta 50 caracteres y pueden incluir caracteres especiales.
   • Tipo de comando: Selecciona Comando rápido o Comando de barra.
   • Especifica un nombre para el comando rápido o de barra:
     • Nombre del comando rápido: Es el nombre visible que los usuarios seleccionan del menú para invocar el comando. Puede tener hasta 50 caracteres y puede incluir caracteres especiales. Por ejemplo, Remind me
     • Nombre del comando de barra: Es el texto que los usuarios escriben para invocar el comando en un mensaje. Debe comenzar con una barra diagonal, contener solo texto y puede tener hasta 50 caracteres. Por ejemplo, /remindMe

5. 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.

6. Haz clic en Guardar.

El comando ahora está configurado para la app de Chat.

Cómo responder un comando

Para obtener más ejemplos, consulta Ejemplos de apps de Google Chat.

Cuando los usuarios usan un comando, tu app de Chat recibe un evento de interacción. 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 mostrar una respuesta adecuada.

Una app de Chat responde de forma privada al comando de barra /help para explicar cómo obtener asistencia.

Para responder a cada tipo de comando, debes controlar diferentes tipos de eventos y objetos de metadatos en la carga útil del evento:

Tipo de comando	Tipo de evento	Metadatos del comando
Comando de barra	MESSAGE	message.slashCommand o message.annotation.slashCommand
Comando rápido	APP_COMMAND	appCommandMetadata

Para obtener información sobre cómo responder un comando con un mensaje, consulta las siguientes secciones.

Responde a un comando de barra

En el siguiente código, se muestra un ejemplo de una app de chat que responde al comando 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 muestra un mensaje privado:

Node.js

node/avatar-app/index.js

Ver en GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Ver en GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Ver en GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Ver en GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Reemplaza ABOUT_COMMAND_ID por el ID del comando que especificaste cuando lo configuraste en la consola de Google Cloud.

Cómo responder un comando rápido

En el siguiente código, se muestra un ejemplo de una app de Chat que responde al comando rápido Help. 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 muestra un mensaje privado:

Node.js

node/avatar-app/index.js

Ver en GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Ver en GitHub

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Ver en GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Ver en GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Reemplaza HELP_COMMAND_ID por el ID del comando que especificaste cuando lo configuraste en la consola de Google Cloud.

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
• Abre diálogos interactivos