Envía mensajes a Google Chat con webhooks entrantes

Los webhooks entrantes te permiten enviar mensajes asíncronos a Google Chat desde aplicaciones que no son de Chat. Por ejemplo, puedes configurar una aplicación de supervisión para notificar al personal de guardia en Google Chat cuando se cae un servidor.

Para enviar, actualizar o borrar un mensaje de forma asíncrona en un espacio de Chat con una app de chat, consulta Cómo crear, leer, actualizar y borrar mensajes.

Arquitectura para que los webhooks entrantes envíen mensajes asíncronos a Google Chat

Requisitos previos

Para ejecutar el ejemplo de esta guía, necesitas lo siguiente:

Python

  • Python 3.10.7 o una versión posterior
  • Acceso a Internet y a un navegador web
  • Una cuenta de Google Workspace con acceso a Google Chat
  • Un espacio existente de Google Chat

  • La biblioteca httplib2. Si es necesario, ejecute el siguiente comando de la interfaz de línea de comandos (CLI) para instalar la biblioteca con pip:

    pip install httplib2

Node.js

Apps Script

Java

Crea un webhook

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

Paso 1: Registra el webhook entrante

  1. En un navegador web, abre Google Chat.
  2. Ve al espacio al que deseas agregar un webhook.
  3. En la parte superior, junto al título del espacio, haz clic en la flecha hacia abajo > Apps e integraciones.
  4. Haz clic en Administrar webhooks.
  5. Si este espacio ya tiene otros webhooks, haz clic en Agregar otro. De lo contrario, omite este paso.
  6. En Nombre, ingresa "quickstart Webhook".
  7. En Avatar URL, ingresa https://developers.google.com/chat/images/chat-product-icon.png.
  8. Haz clic en GUARDAR.
  9. Para copiar la URL completa de webhook, haz clic en Copiar.
  10. Haz clic fuera del cuadro para cerrar el diálogo de webhooks entrantes.

Paso 2: Escribe la secuencia de comandos del webhook

La secuencia de comandos del webhook de ejemplo publica un mensaje en el espacio en el que se registró mediante la publicación de una solicitud create message para crear la URL del webhook. La API de Google Chat responde con una instancia de Message.

Elige un idioma a continuación para obtener instrucciones específicas sobre cómo crear la secuencia de comandos de webhook:

Python

  1. En tu directorio de trabajo, crea un archivo llamado quickstart.py.

  2. En quickstart.py, copia y pega el siguiente código:

    python/webhook/quickstart.py.
    from json import dumps

from httplib2 import Http

WEBHOOK_URL = "[URL FROM WEBHOOK]"

def main():
    """Google Chat incoming webhook quickstart."""
    url = WEBHOOK_URL
    bot_message = {
        'text': 'Hello from a Python script!'}
    message_headers = {'Content-Type': 'application/json; charset=UTF-8'}
    http_obj = Http()
    response = http_obj.request(
        uri=url,
        method='POST',
        headers=message_headers,
        body=dumps(bot_message),
    )
    print(response)


if __name__ == '__main__':
    main()

  3. Reemplaza el valor de la variable url por la URL de webhook que copiaste en el Paso 1: Registra el webhook entrante.

Node.js

  1. En tu directorio de trabajo, crea un archivo llamado index.js.

  2. En index.js, copia y pega el siguiente código:

    node/webhook/index.js
    /**
 * Sends asynchronous message into Google Chat
 * @return{obj} response
 */
function webhook() {
  const fetch = require('node-fetch');
  const webhookURL = 'https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages?key=AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI&token=u9IG_MuTBXw-tnqupPrPNinY2spKFcRBDp6dSldGUAw%3D';

  const data = JSON.stringify({
    'text': 'Hello from a Node script!',
  });
  let resp;
  fetch(webhookURL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json; charset=UTF-8',
    },
    body: data,
  }).then((response) => {
    resp = response;
    console.log(response);
  });
  return resp;
}

  3. Reemplaza el valor de la variable webhookURL por la URL de webhook que copiaste en el Paso 1: Registra el webhook entrante.

Apps Script

  1. Ve a la página Apps Script.

  2. Haz clic en New Project.

  3. Copie y pegue el siguiente código:

    apps-script/webhook/webhook.gs
    function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
  const options = {
    "method": "post",
    "headers": {
      "Content-Type": "application/json; charset=UTF-8"
    },
    "payload": JSON.stringify({
      "text": "Hello from Apps Script!"
    })
  };
  const response = UrlFetchApp.fetch(url, options);
  Logger.log(response);
}

  4. Reemplaza el valor de la variable url por la URL de webhook que copiaste en el Paso 1: Registra el webhook entrante.

Java

  1. En tu directorio de trabajo, crea un archivo llamado pom.xml.

  2. En pom.xml, copia y pega lo siguiente:

    java/webhook/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.hangouts.chat.webhook</groupId>
  <artifactId>java-webhook-app</artifactId>
  <version>0.1.0</version>

  <name>java-webhook-app</name>
  <url>https://github.com/googleworkspace/hangouts-chat-samples/tree/main/java/webhook</url>

  <properties>
    <maven.compiler.target>11</maven.compiler.target>
    <maven.compiler.source>11</maven.compiler.source>
  </properties>

  <dependencies>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.9.1</version>
    </dependency>
  </dependencies>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.8.0</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

  3. En el directorio de trabajo, crea la siguiente estructura de directorio src/main/java.

  4. En el directorio src/main/java, crea un archivo llamado App.java.

  5. En App.java, copia y pega el siguiente código:

    java/webhook/src/main/java/com/google/hangouts/chat/webhook/App.java
    import com.google.gson.Gson;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Map;
import java.net.URI;

public class App {
  private static final String URL = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
  private static final Gson gson = new Gson();
  private static final HttpClient client = HttpClient.newHttpClient();

  public static void main(String[] args) throws Exception {
    String message = gson.toJson(Map.of("text", "Hello from Java!"));

    HttpRequest request = HttpRequest.newBuilder(
        URI.create(URL))
        .header("accept", "application/json; charset=UTF-8")
        .POST(HttpRequest.BodyPublishers.ofString(message))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}

  6. Reemplaza el valor de la variable URL por la URL de webhook que copiaste en el Paso 1: Registra el webhook entrante.

Paso 3: Ejecuta la secuencia de comandos del webhook

Ejecuta la muestra ejecutando el siguiente comando desde el directorio de trabajo en tu CLI:

Python

  python3 quickstart.py

Node.js

  node index.js

Apps Script

  • Haga clic en Ejecutar

Java

  mvn compile exec:java -Dexec.mainClass=App

Cuando ejecute el código de muestra, el webhook enviará un mensaje al espacio en el que lo registró.

Cómo iniciar o responder una conversación de mensajes

Puedes iniciar una conversación de mensajes o responder a una agregando el parámetro threadKey a la URL de webhook. Cada threadKey es único para la app que lo configura. Si dos apps o webhooks de Chat diferentes configuran el mismo threadKey, se inician dos subprocesos diferentes.

Cómo iniciar una conversación de mensajes

Para publicar el primer mensaje de un subproceso con un webhook, agrega los parámetros threadKey y messageReplyOption a la URL del webhook. Establece el threadKey en una string arbitraria, pero recuerda cuál es; deberás volver a especificarlo para publicar una respuesta en la conversación.

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=ARBITRARY_STRING&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD

Responde a una conversación de mensajes

Si deseas enviar un mensaje a una conversación de mensaje existente, agrega los parámetros threadKey y messageReplyOption a la URL de webhook configurada en el valor utilizado para iniciar la conversación. Por ejemplo, si se envía un mensaje a la siguiente URL, se publica una respuesta en la conversación en la que threadKey es MY-THREAD y messageReplyOption es REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD:

  https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?threadKey=MY-THREAD&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD

Límites y consideraciones

Cuando configures los webhooks, ten en cuenta estos límites y consideraciones:

  • Cada webhook funciona solo en el espacio de Chat en el que está registrado.

  • No puedes publicar webhooks en Google Workspace Marketplace.

  • Los webhooks no son conversacionales. No pueden responder ni recibir mensajes de usuarios ni eventos de Google Chat.

  • Si solo las unidades organizativas (UO) seleccionadas de tu dominio tienen apps de chat habilitadas, los webhooks entrantes muestran el siguiente error:

    {
  "error": {
    "code": 403,
    "message": "The caller does not have permission",
    "status": "PERMISSION_DENIED"
  }
}

  • Los webhooks entrantes funcionan en mensajes directos, pero solo cuando todos los usuarios tienen aplicaciones de Chat habilitadas.

  • Debido a que Ícono de administración de webhooks Administrar webhooks solo está disponible desde un navegador web, los webhooks se deben configurar desde la app web de Chat. Los webhooks no se pueden configurar desde la app para dispositivos móviles de Chat.