¿Tienes 5 minutos? Responde una breve encuesta para ayudarnos a mejorar la documentación para desarrolladores de Google Chat.

Se usó la API de Cloud Translation para traducir esta página.

Switch to English

Recibe interacciones con tu app de Google Chat y respóndelas

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 conocidos como eventos de interacción con apps de Google Chat.

Un evento de interacción con la app de Google Chat representa cualquier acción que realiza un usuario para invocar una app de Chat o interactuar con ella, como @mencionar una app de Chat o agregarla a un 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 siguientes acciones:

Ejemplo de un evento de interacción	Respuesta típica de una app de Chat
Un usuario invoca una app de Chat mediante una @mención o el uso de un comando de barra.	La app de Chat procesa lo que dice el mensaje para crear un mensaje. Por ejemplo, una app de Chat responde al comando `/about` con un mensaje en el que se explican las tareas que puede realizar la app de Chat.
Un usuario agrega una app de Chat a un espacio.	La app de Chat envía un mensaje de integración en el que se explica lo que hace y cómo los usuarios del espacio pueden interactuar con ella.
Un usuario quita una app de Chat de un espacio.	La app de Chat quita las notificaciones entrantes configuradas para el espacio (como borrar un webhook) y libera el almacenamiento interno.
Un usuario hace clic en un botón de una tarjeta o un diálogo enviado por la app de Chat.	La app de Chat procesa y almacena los datos que envió el usuario o muestra otra tarjeta o diálogo.

Para cada tipo de interacción del usuario, Google Chat envía un tipo diferente de evento de interacción. Por ejemplo, Google Chat usa el tipo de evento MESSAGE para cualquier interacción en la que un usuario invoca la app de Chat en un mensaje. Para obtener información detallada, consulta Tipos de eventos de interacción con apps de Google Chat.

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

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

Recibe eventos de interacción con apps de Chat

En esta sección, se describe cómo recibir y procesar eventos de interacción con 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 usuarios. Si estás compilando una app de Chat interactiva, debes elegir un extremo que permita que esta reciba, procese y responda a eventos de interacción. Si deseas obtener más información para diseñar tu app de Chat, consulta Arquitecturas de implementación de apps de chat.

Si compilaste una app de Chat interactiva, debes configurar la API de Google Chat para que Google Chat pueda enviarte eventos de interacción:

En la consola de Google Cloud, abre la página de la API de Google Chat:
Ir a la página de la API de Google Chat
Haz clic en la pestaña Configuración.
En la sección Funciones interactivas, haz clic en el botón de activación Habilitar funciones interactivas.
En Funcionalidad, selecciona una de las siguientes casillas de verificación o ambas:
1. Recibir mensajes 1:1: Permite que los usuarios interactúen con tu app de Chat en espacios de mensajes directos (MD). Tu app de Chat recibe eventos de interacción cada vez que un usuario envía un mensaje en el espacio de MD.
2. Unirse a espacios y conversaciones grupales: Permite que los usuarios agreguen y quiten tu app de Chat en espacios con más de una persona. Tu app de Chat recibe eventos de interacción cada vez que se la agrega o quita del espacio, y cada vez que los usuarios mencionan con @o usan un comando de barra en el espacio.
En Configuración de la conexión, especifica a qué lugar Google Chat envía los eventos de interacción con la app de Chat.
Opcional: En los comandos de barra, agrega y configura uno o más comandos de barra. Para obtener más información, consulta Cómo configurar comandos de barra.
Opcional: En Vistas previas de vínculos, agrega y configura uno o más patrones de URL de los que previsualice tu app de Chat. Si deseas obtener más información, consulta Cómo obtener una vista previa de los vínculos.
Haz clic en Guardar.

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

Autentica solicitudes de Google Chat

En el caso de las apps compiladas en extremos HTTP, en esta sección se explica cómo verificar que las solicitudes a tu extremo provengan de Google Chat.

Para enviar eventos de interacción al extremo de tu app de Chat, Google realiza solicitudes a tu servicio. Para verificar que la solicitud provenga de Google, Google Chat incluye un token del portador en el encabezado Authorization de cada solicitud HTTPS a tu extremo. Por ejemplo:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

La string AbCdEf123456 del ejemplo anterior es el token de autorización del portador. Este es un token criptográfico producido por Google. Puedes verificar el token del portador mediante una biblioteca cliente de la API de Google de código abierto:

Java: https://github.com/google/google-api-java-client
Python: https://github.com/google/google-api-python-client
.NET: https://github.com/google/google-api-dotnet-client

Para los tokens del portador enviados en las solicitudes de Google Chat, la entidad emisora es chat@system.gserviceaccount.com y el campo audience se establece en el número del proyecto de Google Cloud que usaste para compilar tu app de Chat. Por ejemplo, si el número de proyecto de Cloud de tu app de Chat es 1234567890, el campo audience en el token del portador es 1234567890.

Si el token no se verifica para la app de Chat, el servicio debe responder a la solicitud con un código de respuesta HTTPS 401 (Unauthorized).

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

Controla los reintentos de llamadas HTTP al servicio

Si falla una solicitud HTTPS a tu servicio (como un tiempo de espera, una falla temporal de la red o un código de estado HTTPS que no es 2xx), Google Chat vuelve a intentar la entrega dos veces, con un retraso de al menos diez segundos entre cada reintento. Como resultado, una app de Chat puede recibir el mismo mensaje hasta tres veces en determinadas situaciones. Si la solicitud se completa correctamente, pero muestra una carga útil de mensaje no válida, Google Chat no vuelve a intentar la solicitud.

Cómo procesar eventos de interacción o responder a ellos

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

Una vez 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 casi cualquier otra cosa. En esencia, este comportamiento de procesamiento es lo que define la app de Google Chat.

Para cada evento de interacción, las apps de chat reciben un cuerpo de solicitud, que es la carga útil 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 apps 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 eventos de interacción.

Responder 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 crear respuestas síncronas a eventos de interacción, consulta las siguientes guías:

Para responder de manera síncrona, una app de Chat debe responder en 30 segundos, y la respuesta debe publicarse en el espacio en el que ocurrió la interacción. De lo contrario, la app de Chat puede responder de forma asíncrona.

Responde de forma asíncrona

En ocasiones, 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ó ese evento. 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 cómo usar métodos adicionales de la API de Chat, consulta la descripción general de la API de Chat.