Cómo recibir y responder a eventos de interacción

En esta página, se describe cómo tu app de Google Chat puede recibir y responder a las interacciones del usuario, 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:

• Configurar tu app de Chat para recibir eventos de interacción
• Procesar el evento de interacción en tu infraestructura
• Responder a los eventos de interacción, si corresponde

Requisitos previos

• Una cuenta de Google Workspace Business o Enterprise con acceso a Google Chat.
• Crea un proyecto de Google Cloud.
• Configurar la pantalla de consentimiento de OAuth.
• Habilitar la API de Google Chat.

Tipos de eventos de interacción

Un evento de interacción de la app de Google Chat representa cualquier acción que realiza un usuario para invocar o interactuar con una app de Chat, como hacer una mención con @a 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 Event tipo 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 en consecuencia. El tipo de evento de interacción se representa con el eventType objeto.

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 de inmediato con un mensaje de bienvenida en el espacio.

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

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

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 como true.
• El DialogEventType aclara si la interacción activa la apertura de un diálogo, envía información desde un diálogo o cierra un diálogo.

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:

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

Recibe 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 permita que tu app de Chat reciba, procese y responda a los eventos de interacción. Para obtener más información sobre el diseño de 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 tu 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:

   Ir a la página de 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. Es un conjunto de campos que determinan cómo puede interactuar la app de Chat con los usuarios. De forma predeterminada, los usuarios pueden encontrar y enviar mensajes a la app de Chat directamente en 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. Es el extremo de la app de Chat, que es una de las siguientes opciones: URL del extremo HTTP: Un extremo HTTPS que aloja la implementación de la app de Chat. Apps Script: Un ID de implementación para un proyecto de Apps Script que implementa una app de Chat. Nombre de tema de Cloud Pub/Sub: 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 Compila una app de Google Chat basada en Dialogflow que comprenda el lenguaje natural.
   Comandos	Es opcional. Comandos de barra y comandos rápidos para la app de Chat. Los comandos permiten que los usuarios soliciten una acción o usen una función específica de tu app de Chat. Para obtener más información, consulta Responde a los comandos de la app de Google Chat.
   Vistas previas de vínculos	Es 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 Obtén una vista previa de los vínculos.
   Visibilidad	Es opcional. Hasta cinco personas o uno o más Grupos de Google que pueden 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 Prueba las funciones interactivas.

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

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

Controla los reintentos de llamadas HTTP a tu servicio

Si falla una solicitud HTTPS a tu servicio (como un tiempo de espera, una falla de red temporal o un código de estado HTTPS que no sea 2xx), es posible que Google Chat vuelva a intentar la entrega varias veces en unos minutos (pero no se garantiza). 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 a 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 interactivas responden al usuario con un mensaje. La app de Google Chat también puede buscar información de una fuente de datos, registrar la información del evento de interacción o cualquier otra cosa. Este comportamiento de procesamiento es esencialmente 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 en el que 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 las apps de Google Chat suelen procesar o responder a diferentes tipos de 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 Message objeto. Para responder con un mensaje en el espacio, el objeto Message puede contener text, cardsV2 y accessoryWidgets objetos. Para usar con otros tipos de respuestas, consulta las siguientes guías:

• Cómo abrir diálogos interactivos
• Obtén una vista previa de los vínculos
• Procesa la información que envían los usuarios

Responder con un mensaje

En este ejemplo, tu 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 incorporar 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, tu app de Chat responde a un ADDED_TO_SPACE evento de interacción. Para responder a los eventos de interacción ADDED_TO_SPACE con un mensaje de texto, usa el siguiente código:

/**
 * 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.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // 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`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

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

El ejemplo de código muestra el siguiente mensaje de texto:

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, es posible que una app de Chat deba 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 Crea un mensaje. Para obtener guías sobre el uso de métodos adicionales de la API de Chat, consulta la Descripción general de la API de Chat.

Temas relacionados

• Enviar un mensaje
• Cómo abrir diálogos interactivos
• Obtén una vista previa de los vínculos
• Lee los datos de formulario que ingresan los usuarios en las tarjetas
• Responder a comandos
• Compila una página principal para una app de Chat
• Verifica las solicitudes de Chat
• Prueba las funciones interactivas de las apps de Google Chat