Recibe interacciones de los usuarios y responde a ellas

En esta página, se describe cómo tu app de Google Chat puede recibir y responder a las interacciones de los usuarios, también conocidas como eventos de interacción de la app de Google Chat.

En esta página, se describe cómo hacer lo siguiente:

  • Configura tu app de Chat para que reciba eventos de interacción.
  • Procesa el evento de interacción en tu infraestructura.
  • Si corresponde, responde a los eventos de interacción.

Compila una app de Chat interactiva como complemento de Google Workspace

Para compilar una app de Chat que interactúe con los usuarios de Chat, puedes compilar un complemento de Google Workspace que extienda Chat. En lugar de recibir eventos de interacción de la API de Chat, la app de Chat recibe y responde objetos de eventos de complementos. Para obtener más información, consulta Cómo extender Google Chat en la documentación de complementos de Google Workspace.

Requisitos previos

Una app de Google Chat habilitada para funciones interactivas Para crear una app de Chat interactiva, completa una de las siguientes guías de inicio rápido según la arquitectura de la app que quieras usar:

Tipos de eventos de interacción

Un evento de interacción con la app de Google Chat representa cualquier acción que un usuario realiza para invocar o interactuar con una app de Chat, como @mencionar una app de Chat o agregarla a un espacio.

Cuando los usuarios interactúan con una app de Chat, Google Chat le envía un evento de interacción, representado como un tipo Event en la API de Chat. La app de Chat puede usar el evento para procesar la interacción y, de manera opcional, responder con un mensaje.

Para cada tipo de interacción del usuario, Google Chat envía un tipo diferente de evento de interacción que ayuda a tu app de Chat a controlar cada tipo de evento según corresponda. El tipo de evento de interacción se representa con el objeto eventType.

Por ejemplo, Google Chat usa el tipo de evento ADDED_TO_SPACE para cualquier interacción en la que un usuario agrega la app de Chat a un espacio, de modo que la app de Chat pueda responder inmediatamente con un mensaje de bienvenida en el espacio.

La app de chat publica un mensaje de bienvenida.
Figura 1: Cuando un usuario agrega una app de Chat a un espacio, la app de Chat recibe un evento de interacción ADDED_TO_SPACE que la app de Chat controla para enviar un mensaje de bienvenida en el espacio.

En la siguiente tabla, se muestran las interacciones comunes de los usuarios, el tipo de evento de interacción que reciben las apps de Chat y cómo suelen responder:

Interacción con los usuarios eventType Respuesta típica de una app de chat
Un usuario invoca una app de Chat cuando la @menciona o usa un comando de barra. MESSAGE La app de Chat responde según el contenido del mensaje. Por ejemplo, una app de Chat responde al comando /about con un mensaje que explica las tareas que puede realizar la app de Chat.
Un usuario agrega una app de Chat a un espacio. ADDED_TO_SPACE La app de Chat envía un mensaje de integración que explica qué hace y cómo los usuarios del espacio pueden interactuar con él.
Un usuario quita una app de Chat de un espacio. REMOVED_FROM_SPACE La app de Chat quita las notificaciones entrantes configuradas para el espacio (como borrar un webhook) y borra el almacenamiento interno.
Un usuario hace clic en un botón de una tarjeta desde un mensaje, un diálogo o la página principal de la app de Chat. CARD_CLICKED La app de Chat procesa y almacena los datos que envió el usuario, o muestra otra tarjeta.
Un usuario hace clic en la pestaña Página principal de un mensaje 1:1 para abrir la página principal de la app de Chat. APP_HOME La app de Chat muestra una tarjeta estática o interactiva desde la página principal.
Un usuario envía un formulario desde la página principal de la app de Chat. SUBMIT_FORM La app de Chat procesa y almacena los datos que envió el usuario, o muestra otra tarjeta.

Para ver todos los eventos de interacción compatibles, consulta la documentación de referencia de EventType.

Eventos de interacción de diálogos

Si tu app de Chat abre diálogos, el evento de interacción contiene la siguiente información adicional que puedes usar para procesar una respuesta:

  • isDialogEvent se configura en true.
  • DialogEventType aclara si la interacción activa un diálogo para que se abra, envía información desde un diálogo o lo cierra.

En la siguiente tabla, se muestran las interacciones comunes con los diálogos, los tipos de eventos de diálogo correspondientes y una descripción de cómo suelen responder las apps de Chat:

Interacción del usuario con un diálogo Tipo de evento de diálogo Respuesta típica
Un usuario activa una solicitud de diálogo. Por ejemplo, usan una barra diagonal o hacen clic en un botón de un mensaje. REQUEST_DIALOG La app de Chat abrirá el diálogo.
Un usuario hace clic en un botón para enviar información en el diálogo. SUBMIT_DIALOG La app de Chat navega a otro diálogo o lo cierra para completar la interacción.
Un usuario sale o cierra el diálogo antes de enviar información. CANCEL_DIALOG De manera opcional, la app de Chat puede responder con un mensaje nuevo o actualizar el mensaje o la tarjeta desde la que el usuario abrió el diálogo.

Para obtener más información, consulta Cómo abrir diálogos interactivos.

Cómo recibir eventos de interacción de la app de Chat

En esta sección, se describe cómo recibir y procesar eventos de interacción para tu app de chat.

Configura tu app de Chat para recibir eventos de interacción

No todas las apps de Chat son interactivas. Por ejemplo, los webhooks entrantes solo pueden enviar mensajes salientes y no pueden responder a los usuarios. Si compilas una app de chat interactiva, debes elegir un extremo que le permita recibir, procesar y responder a eventos de interacción. Para obtener más información sobre cómo diseñar tu app de Chat, consulta Arquitecturas de implementación de apps de Chat.

Para cada una de las funciones interactivas que deseas compilar, debes actualizar la configuración en la API de Chat para que Google Chat pueda enviar eventos de interacción relacionados a tu app de Chat:

  1. En la consola de Google Cloud, ve a la página de la API de Chat y haz clic en la página Configuración:

    Ve a la página Configuración de la API de Chat

  2. En Funciones interactivas, revisa la configuración y actualízala según las funciones que deseas compilar:

    Campo Descripción
    Funcionalidad Obligatorio. Un conjunto de campos que determinan cómo la app de Chat puede interactuar con los usuarios:
    • Recibir mensajes 1:1: Los usuarios pueden buscar la app de Chat y enviarle mensajes directamente a través de Google Chat.
    • Unirse a espacios y conversaciones grupales: Los usuarios pueden agregar la app de Chat a espacios y conversaciones grupales.
    Configuración de conexión Obligatorio. El extremo de la app de Chat, que es uno de los siguientes:
    • URL del extremo HTTP: Es un extremo HTTPS que aloja la implementación de la app de Chat.
    • Apps Script: Es un ID de implementación para un proyecto de Apps Script que implementa una app de Chat.
    • Nombre de tema de Cloud Pub/Sub: Es un tema de Pub/Sub al que se suscribe la app de Chat como extremo.
    • Dialogflow: Registra la app de Chat con una integración de Dialogflow. Para obtener más información, consulta Cómo compilar una app de Google Chat de Dialogflow que comprenda el lenguaje natural.
    Comandos de barra Opcional. Son comandos que se pueden mostrar a los usuarios en Google Chat. Permite que los usuarios vean las acciones principales de tu app de Chat en Google Chat y elijan una acción específica con la que quieran interactuar. Para obtener más información, consulta Cómo responder a comandos de barra como una app de Chat.
    Vistas previas de vínculos Opcional. Patrones de URL que la app de Chat reconoce y para los que proporciona contenido adicional cuando los usuarios envían vínculos. Para obtener más información, consulta Vínculos de vista previa.
    Visibilidad Opcional. Hasta cinco personas o uno o más Grupos de Google que puedan ver e instalar tu app de Chat. Usa este campo para probar tu app de Chat o para compartirla con tu equipo. Para obtener más información, consulta Cómo probar funciones interactivas.

  3. Haz clic en Guardar. Cuando guardas la configuración de la app de Chat, esta estará disponible para los usuarios especificados en tu organización de Google Workspace.

Tu app de Chat ya está configurada para recibir eventos de interacción de Google Chat.

Controla las reintentos de llamadas HTTP a tu servicio

Si una solicitud HTTPS a tu servicio falla (por ejemplo, se agota el tiempo de espera, se produce una falla de red temporal o se muestra un código de estado HTTPS que no es 2xx), es posible que Google Chat vuelva a intentar la entrega varias veces en unos minutos (pero esto no está garantizado). Como resultado, una app de chat podría recibir el mismo mensaje varias veces en ciertas situaciones. Si la solicitud se completa correctamente, pero muestra una carga útil de mensaje no válida, Google Chat no vuelve a intentarla.

Procesa o responde eventos de interacción

En esta sección, se explica cómo las apps de Google Chat pueden procesar y responder a eventos de interacción.

Después de que tu app de Chat recibe un evento de interacción de Google Chat, puede responder de muchas maneras. En muchos casos, las apps de chat interactivo le responden al usuario con un mensaje. La app de Google Chat también puede buscar información en una fuente de datos, registrar la información del evento de interacción o cualquier otra cosa. Este comportamiento de procesamiento es, en esencia, lo que define la app de Google Chat.

Para responder de forma síncrona, una app de Chat debe responder en un plazo de 30 segundos, y la respuesta debe publicarse en el espacio donde se produjo la interacción. De lo contrario, la app de Chat puede responder de forma asíncrona.

Para cada evento de interacción, las apps de Chat reciben un cuerpo de la solicitud, que es la carga útil de JSON que representa el evento. Puedes usar la información para procesar una respuesta. Para ver ejemplos de cargas útiles de eventos, consulta Tipos de eventos de interacción de la app de Chat.

En el siguiente diagrama, se muestra cómo la app de Google Chat suele procesar o responder a diferentes tipos de eventos de interacción:

Arquitectura de cómo las apps de Google Chat procesan los eventos de interacción.

Ver respuestas en tiempo real

Los eventos de interacción permiten que las apps de Chat respondan en tiempo real o de forma síncrona. Las respuestas síncronas no requieren autenticación.

Para responder en tiempo real, la app de Chat debe mostrar un objeto Message. Para responder con un mensaje en el espacio, el objeto Message puede contener objetos text, cardsV2 y accessoryWidgets. Para usarlo con otros tipos de respuestas, consulta las siguientes guías:

Responder con un mensaje

En este ejemplo, la app de Chat crea y envía un mensaje de texto cada vez que se agrega a un espacio. Para obtener información sobre las prácticas recomendadas para integrar a los usuarios, consulta Presenta a los usuarios tu app de Chat.

Para enviar un mensaje de texto cuando un usuario agrega tu app de Chat a un espacio, la app de Chat responde a un evento de interacción ADDED_TO_SPACE. Para responder a los eventos de interacción ADDED_TO_SPACE con un mensaje de texto, usa el siguiente código:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

La muestra de código muestra el siguiente mensaje de texto:

Ejemplo de mensaje de integración.

Cómo responder de forma asíncrona

A veces, las apps de Chat deben responder a un evento de interacción después de 30 segundos o realizar tareas fuera del espacio en el que se generó el evento de interacción. Por ejemplo, una app de chat podría necesitar responder al usuario después de completar una tarea de larga duración. En este caso, las apps de Chat pueden responder de forma asíncrona llamando a la API de Google Chat.

Para crear un mensaje con la API de Chat, consulta Cómo crear un mensaje. Si quieres obtener guías para usar métodos adicionales de la API de Chat, consulta la descripción general de la API de Chat.