Responde a los comandos de la app de Google Chat

En esta página, se explica cómo configurar y responder a comandos como una app de Google Chat.

Nota: En Google Chat, los complementos aparecen para los usuarios como apps de Google Chat. También puedes crear tu app de Chat con eventos de interacción de la API de Google Chat. Para obtener más información, consulta la descripción general de la extensión 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 será visible para el usuario y la app de Chat.

Para decidir si debes crear 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 apps 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:

1. 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 entrada adicional del usuario. Por ejemplo, puedes crear un comando de barra llamado /search que se ejecute después de que el usuario ingrese una frase para buscar, como /search receipts.

2. Comandos rápidos: Los usuarios abren el menú desde el área de respuesta de un mensaje de Chat para usar los comandos. Para usar un comando, el usuario hace clic en Agregar y selecciona un comando del menú.

   Crea un comando rápido si tu app de Chat puede responder al usuario de inmediato, sin esperar información adicional. Por ejemplo, puedes crear un comando rápido llamado Imagen aleatoria que responda de inmediato con una imagen.

3. 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 y rápidos, y las acciones de mensajes:

Los usuarios descubren un menú de comandos de barra y comandos rápidos.

Los usuarios descubren un menú contextual de mensajes que contiene una acción de mensaje "Recordarme".

Requisitos previos

HTTP

Un complemento de Google Workspace que extiende Google Chat. Para compilar uno, completa la guía de inicio rápido de HTTP.

Nota: Las muestras de código de esta guía se escribieron para ejecutarse como una función de Cloud Run de Google Cloud para Node.js.

Apps Script

Un complemento de Google Workspace que extiende Google Chat. Para compilar una, 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:

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 agrégale una descripción

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:

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 entre 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 en algo 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 de forma privada al usuario que invoca el comando. Por ejemplo, para el comando rápido About, podrías 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, un comando rápido o una acción de mensaje, debes especificar información sobre el comando o la acción en la configuración de tu 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 Configuración de conexión, ve a Activadores y especifica los detalles de tu extremo. Debes usar este activador en la siguiente sección para responder al comando.

   1. URL del extremo HTTP: Aquí puedes especificar una URL de extremo HTTP común. Como alternativa, para usar diferentes extremos HTTP para diferentes activadores, especifica el extremo directamente en el campo Comando de la app.
   2. 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.

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

5. Ingresa la siguiente información sobre el comando:

   1. ID de comando: Es un número del 1 al 1,000 que tu app de Chat usa para reconocer el comando y devolver una respuesta.
   2. Descripción: Es el texto que describe cómo usar y dar formato al comando. Las descripciones pueden tener hasta 50 caracteres.
   3. Tipo de comando: Selecciona Comando rápido, Comando de barra o Acción de mensaje.
   4. 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 puede 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 tener hasta 50 caracteres. Por ejemplo, /remindMe
      • Nombre de la acción del mensaje: Es el nombre visible que los usuarios seleccionan en el menú para invocar la acción del mensaje. Puede tener hasta 50 caracteres y puede incluir caracteres especiales. Por ejemplo, Remind me

6. Opcional: Mensaje de notificación de carga: Es un mensaje de notificación emergente que se muestra al usuario mientras se ejecuta la acción de mensaje. Solo está disponible para las acciones de mensajes que no abren diálogos.

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

8. Haz clic en Guardar.

Ahora el comando está configurado para la app de Chat.

Asigna comandos del mapa a instrucciones de inicio

Versión preliminar para desarrolladores: Disponible como parte del Programa de versión preliminar para desarrolladores de Google Workspace, que otorga acceso anticipado a ciertas funciones.

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, haz lo siguiente:

1. Asegúrate de que el comando no requiera argumentos personalizados adicionales (solo se admiten como instrucciones iniciales los comandos con Sin argumentos o Argumentos básicos).
2. En la consola de Google Cloud, ve a la página Configuración de la API de Chat.
3. En Funciones interactivas > Mensajes iniciales, haz clic en Agregar un mensaje.
4. Establece la Clasificación (1-3) para el orden de visualización.
5. En Selección de tipo, elige Símbolo del sistema y selecciona tu comando en el menú desplegable.
6. Haz clic en Listo y, luego, en Guardar.

Nota: Si un comando está asignado a una instrucción de inicio activa, no puedes borrar el comando ni cambiar su tipo en la tabla Comandos hasta que quites su asignación en Instrucciones de inicio.

Cómo responder a un comando

Cuando los usuarios usan un comando, tu app de Chat recibe un objeto de evento. La carga útil del evento contiene un objeto appCommandPayload con detalles sobre el comando que se invocó (incluidos el ID y el tipo de comando), de modo 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 de Comando de la app.

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

El siguiente código 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 objetos de eventos desde un activador de Comando de app. Cuando la carga útil de un objeto de evento contiene un ID de comando de barra, la app de Chat devuelve la acción DataActions con un objeto createMessageAction:

Node.js

node/chat/avatar-app/index.js

Ver en GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/chat/avatar-app/main.py

Ver en GitHub

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

Ver en GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

Apps Script

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

Ver en GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'The Avatar app replies to Google Chat messages.'
      }}}}};
  }
}

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

Acción del mensaje de respuesta

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 eventos de un activador de Comando de 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 de comando que especificaste cuando configuraste el comando en la API de Chat.

Prueba el comando

Para probar el comando y el código, consulta Cómo probar funciones interactivas para las apps de Google Chat.

Para obtener información sobre cómo 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 muestras de apps de Chat que usan comandos
• Enviar un mensaje
• Abrir diálogos interactivos