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 del usuario, también conocida como app de Google Chat eventos de interacción.

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

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

Requisitos previos

Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva, completa una de las siguientes guías de inicio rápido en la arquitectura de app que quieres usar:

Cómo funcionan los eventos de interacción

Un evento de interacción con la app de Google Chat representa cualquier acción que que el usuario toma para invocar una app de Chat o interactuar con ella, como como @mencionar una app de Chat o agregarla a una espacio. Cuando los usuarios interactúan con una app de Chat, Google Chat envía un evento de interacción a la app de Chat. La app de Chat puede usar el evento para procesar la interacción y crear una respuesta.

Por ejemplo, las apps de Chat usan eventos de interacción para realizar cualquiera de las lo siguiente:

Ejemplo de un evento de interacción Respuesta típica de una app de Chat
Un usuario invoca una app de Chat mediante @mencionarla o usar un comando de barra. El La app de Chat procesa lo que dice el mensaje crear un mensaje. Por ejemplo, una app de Chat responde el comando /about con un mensaje que explica las tareas que que puede hacer la app de Chat.
Un usuario agrega una app de Chat a un espacio. La app de Chat envía una información mensaje en el que se explique qué hace y cómo pueden interactuar los usuarios del espacio que la modifica.
Un usuario quita un App de Chat desde un espacio. El La app de Chat quita las notificaciones entrantes configurados para el espacio (por ejemplo, borrar webhook) y aclara almacenamiento interno.
Un usuario hace clic en un botón de una tarjeta o un diálogo enviado por el App de Chat La app de Chat procesa y almacena que el usuario envió, o bien devuelve otra tarjeta o diálogo.

Para cada tipo de interacción del usuario, Google Chat envía de interacción que ayuda a tu app de Chat a manejar cada según corresponda. Por ejemplo, Google Chat usa el tipo de evento ADDED_TO_SPACE para cualquier interacción en la que un usuario agregue el elemento de Chat a un espacio La app de Chat puede administrar una respuesta, como publicar un mensaje de bienvenida al espacio. Para ver todos los eventos de interacción admitidos, consulta el Referencia de EventType documentación.

Recibe eventos de interacción con 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 estás creando una app app de Chat, debes elegir un extremo que le permita La app de Chat recibe, procesa y responde a las interacciones eventos. 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 quieras compilar, debes actualizar la configuración de la API de Chat para que Google Chat pueda enviar eventos de interacción relacionados con la app de Chat:

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

    Ir 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 quieres 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 enviar 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 de la app: Es un extremo HTTPS que aloja la implementación de la app de Chat.
    • Proyecto de Apps Script: Es un ID de implementación para un proyecto de Apps Script que implementa una app de Chat.
    • Nombre del tema de Cloud Pub/Sub: Es un tema de Pub/Sub al que se suscribe la app de Chat como un 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 de Dialogflow que comprenda el lenguaje natural.
    Comandos de barra Opcional. Comandos que se pueden mostrar a los usuarios en Google Chat. Les permite a los usuarios ver las acciones principales de tu app de Chat en Google Chat y elegir una acción específica con la que quieran interactuar. Si deseas obtener más información, consulta Responde a los 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 Si deseas obtener más información, consulta Vista previa de vínculos.
    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 compartir la app de Chat con tu equipo. Para obtener más información, consulta Cómo probar funciones interactivas.

  3. Haz clic en Guardar. Cuando guardas la app de Chat de Chat, tu app de Chat estará disponible para usuarios específicos de tu organización de Google Workspace.

Tu app de Chat ya está configurada para recibir interacciones eventos de Google Chat.

Controla los reintentos de llamada HTTP en tu servicio

Si falla una solicitud HTTPS a tu servicio (como un tiempo de espera, una conexión de red o un código de estado HTTPS que no sea 2xx), es posible que Google Chat reintente varias veces en pocos minutos (pero esto no está garantizado). Como resultado, un Chat podría recibir el mismo mensaje varias veces en en ciertas situaciones. Si la solicitud se completa correctamente, pero muestra un resultado no válido carga útil del mensaje, Google Chat no reintentará la solicitud.

Procesa eventos de interacción o responde a ellos

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, pueden responder de muchas maneras. En muchos casos, la interacción Las apps de Chat responden al usuario con un mensaje. La app de Google Chat también puede buscar información en un registrar la información del evento de interacción o simplemente cualquier otra cosa. En esencia, este comportamiento del procesamiento es lo que define la App de Google Chat

Para responder de forma síncrona, una app de Chat debe responder dentro de 30 segundos, y la respuesta debe publicarse en el espacio donde interacción existente. De lo contrario, la app de Chat responden 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 útil para procesar una respuesta. Para ver ejemplos de cargas útiles de eventos, consulta Tipos de eventos de interacción con 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 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. de forma síncrona. Las respuestas síncronas no requieren autenticación.

Responde para unirte a un espacio

En este ejemplo, tu app de Chat crea y envía un mensaje cada vez que se agrega a un espacio. Si quieres conocer las prácticas recomendadas para integrar usuarios, consulta Presenta tu app de Chat a los usuarios.

Para enviar un mensaje de texto cuando un usuario agrega tu app de Chat a un espacio, la app de Chat responde a un ADDED_TO_SPACE evento de interacción. Para responder a 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 devuelve el siguiente mensaje de texto:

Ejemplo de mensaje de integración.

Otros ejemplos de respuestas a interacciones

Para crear respuestas síncronas a los eventos de interacción, consulta lo siguiente guías:

Responde de forma asíncrona

A veces, las apps de Chat deben responder a un evento de interacción después de los 30 días segundos o realizar tareas fuera del espacio donde ocurrió el evento de interacción de red. Por ejemplo, una app de Chat podría necesitar responderán al usuario luego de completar una tarea prolongada. 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 guías sobre el uso métodos adicionales de la API de Chat, consulta la Descripción general de la API de Chat.