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.

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 las apps de Chat

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 información 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 usan comandos abriendo el menú desde el área de respuesta de un mensaje de Chat. 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 entradas adicionales. Por ejemplo, puedes crear un comando rápido llamado Imagen aleatoria que responda de inmediato con una imagen.

3. Acciones de mensajes: (science Versión preliminar para desarrolladores) 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 basadas en el contexto de un mensaje.

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

Requisitos previos

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 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, ten en cuenta las siguientes recomendaciones:

Para asignar un nombre a un comando, haz lo siguiente:

• 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, 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ú 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 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: (science Versión preliminar para desarrolladores) 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: (science Versión preliminar para desarrolladores) 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.

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

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 del comando de la app.

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

// 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.'
      };
  }
}

# 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 {}

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

// 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 este código de muestra, reemplaza ABOUT_COMMAND_ID por el ID del comando que especificaste cuando configuraste el comando en la API de Chat.

Responder a una acción de mensaje

En el siguiente código, se muestra un ejemplo de una app de Chat que responde a la acción de mensaje Recordatorio con un mensaje de texto. Para responder a las acciones de mensajes, la app de Chat controla objetos de eventos desde un activador de comando de la 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:

/**
 * 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}"`
            }
          }
        }
      }
    });
  }
}

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}"'
                        }
                    }
                }
            }
        }

/**
 * 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());
    }
  }
}

/**
 * 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 este código de muestra, reemplaza REMIND_ME_COMMAND_ID por el ID del 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 las funciones interactivas de 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 la app de Chat que usan comandos
• Enviar un mensaje
• Abrir diálogos interactivos