Compila una app de Google Chat como webhook (original) (raw)

En esta página, se describe cómo configurar un webhook para enviar mensajes asíncronos a un espacio de Chat con activadores externos. Por ejemplo, puedes configurar una aplicación de supervisión para notificar al personal de guardia en Chat cuando un servidor deja de funcionar. Para enviar un mensaje síncrono con una app de Chat, consultaEnvía un mensaje.

Con este tipo de diseño de arquitectura, los usuarios no pueden interactuar con el webhook ni con la aplicación externa conectada porque la comunicación es unidireccional. Los webhooks no son conversacionales. No pueden responder ni recibir mensajes de los usuarios nieventos de interacción de la app de Chat. Para responder mensajes,crea una app de Chaten lugar de un webhook.

Si bien un webhook no es técnicamente una app de Chat (los webhooks conectan aplicaciones mediante solicitudes HTTP estándar), en esta página se hace referencia a él como una app de Chat para simplificarlo. Cada webhook solo funciona en el espacio de Chat en el que está registrado. Los webhooks entrantes funcionan en mensajes directos, pero solo cuando todos los usuarios tienenhabilitadas las apps de Chat. No puedes publicar webhooks en Google Workspace Marketplace.

En el siguiente diagrama, se muestra la arquitectura de un webhook conectado a Chat:

Arquitectura de los webhooks entrantes para enviar mensajes asíncronos a Chat.

En el diagrama anterior, una app de Chat tiene el siguiente flujo de información:

  1. La lógica de la app de Chat recibe información de servicios externos de terceros, como un sistema de administración de proyectos o una herramienta de emisión de tickets.
  2. La lógica de la app de Chat se aloja en un sistema en la nube o local que puede enviar mensajes mediante una URL de webhook a un espacio de Chat específico.
  3. Los usuarios pueden recibir mensajes de la app de Chat en ese espacio de Chat específico, pero no pueden interactuar con la app de Chat.

Requisitos previos

Node.js

Python

pip install httplib2

Java

Apps Script

Crea un webhook

Para crear un webhook, regístralo en el espacio de Chat en el que deseas recibir mensajes y, luego, escribe una secuencia de comandos que envíe mensajes.

Registra el webhook entrante

  1. En un navegador, abreChat. Los webhooks no se pueden configurar desde la app de Chat para dispositivos móviles.
  2. Ve al espacio en el que deseas agregar un webhook.
  3. Junto al título del espacio, haz clic en la flecha expandir más y, luego, en Apps e integraciones.
  4. Haz clic en Agregar webhooks.
  5. En el campo Nombre, ingresa Quickstart Webhook.
  6. En el campo URL del avatar, ingresahttps://developers.google.com/chat/images/chat-product-icon.png.
  7. Haz clic en Guardar.
  8. Para copiar la URL del webhook, haz clic enMás y, luego, enCopiar vínculo.
    La URL del webhook contiene dos parámetros: key, un valor común compartido entre los webhooks, y token que es un valor único que debe mantenerse en secreto para preservar la seguridad del webhook.

Escribe la secuencia de comandos del webhook

La secuencia de comandos de webhook de ejemplo envía un mensaje al espacio en el que está registrado el webhook mediante el envío de una solicitud POST a la URL del webhook. La API de Chat responde con una instancia deMessage.

Selecciona un lenguaje para aprender a crear una secuencia de comandos de webhook:

Node.js

  1. En tu directorio de trabajo, crea un archivo llamado index.js.
  2. En index.js, pega el siguiente código:
  3. Reemplaza el valor de la variable url por la URL del webhook que copiaste cuando registraste el webhook.

Python

  1. En tu directorio de trabajo, crea un archivo llamado quickstart.py.
  2. En quickstart.py, pega el siguiente código:
  3. Reemplaza el valor de la variable url por la URL del webhook que copiaste cuando registraste el webhook.

Java

  1. En tu directorio de trabajo, crea un archivo llamado pom.xml.
  2. En pom.xml, copia y pega lo siguiente:
  3. En tu directorio de trabajo, crea la siguiente estructura de directorios src/main/java.
  4. En el directorio src/main/java, crea un archivo llamado App.java.
  5. En App.java, pega el siguiente código:
  6. Reemplaza el valor de la variable URL por la URL del webhook que copiaste cuando registraste el webhook.

Apps Script

  1. En un navegador, ve aApps Script.
  2. Haz clic en Proyecto nuevo.
  3. Pega el siguiente código:
  4. Reemplaza el valor de la variable url por la URL del webhook que copiaste cuando registraste el webhook.

Ejecuta la secuencia de comandos del webhook

En una CLI, ejecuta la secuencia de comandos:

Node.js

  node index.js

Python

  python3 quickstart.py

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script

Cuando ejecutas el código, el webhook envía un mensaje al espacio en el que lo registraste.

Inicia o responde una conversación

  1. Especificaspaces.messages.thread.threadKeycomo parte del cuerpo de la solicitud de mensaje. Según si inicias o respondes una conversación, usa los siguientes valores para threadKey:
    • Si inicias una conversación, configura threadKey en una cadena arbitraria, pero anota este valor para publicar una respuesta en la conversación.
    • Si respondes una conversación, especifica el threadKey que se configuró cuando se inició la conversación. Por ejemplo, para publicar una respuesta en la conversación en la que el mensaje inicial usó MY-THREAD, configura MY-THREAD.
  2. Define el comportamiento de la conversación si no se encuentra el threadKey especificado:
    • Responde una conversación o inicia una nueva. Agrega el parámetro messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD a la URL del webhook. Si pasas este parámetro de URL, Chat buscará una conversación existente con el threadKey especificado. Si se encuentra una, el mensaje se publicará como respuesta a esa conversación. Si no se encuentra ninguna, el mensaje iniciará una conversación nueva correspondiente a ese threadKey.
    • Responde una conversación o no hagas nada. Agrega el parámetro messageReplyOption=REPLY_MESSAGE_OR_FAIL a la URL del webhook. Si pasas este parámetro de URL, Chat buscará una conversación existente con el threadKey especificado. Si se encuentra una, el mensaje se publicará como respuesta a esa conversación. Si no se encuentra ninguna, el mensaje no se enviará.
      Para obtener más información, consulta messageReplyOption.

En el siguiente ejemplo de código, se inicia o se responde una conversación:

Node.js

Python

Java

Apps Script

Soluciona errores

Las solicitudes de webhook pueden fallar por varios motivos, incluidos los siguientes:

Cuando crees tu webhook, debes controlar los errores de forma adecuada de la siguiente manera:

La API de Google Chat muestra errores como ungoogle.rpc.Status, que incluye un error HTTP code que indica el tipo de error que se produjo: un error del cliente (serie 400) o un error del servidor (serie 500). Para revisar todas las asignaciones de HTTP, consultagoogle.rpc.Code.

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

Para obtener información sobre cómo interpretar los códigos de estado HTTP y controlar errores, consultaErrores.

Limitaciones y consideraciones