Conecta una app de Chat con otros servicios y herramientas

En esta página, se describe cómo conectar una app de Google Chat con un servicio o una herramienta fuera de Google Chat. Si bien las apps de Chat son potentes por sí solas, a menudo funcionan en conjunto con otros sistemas y requieren aplicaciones complementarias para conectar cuentas, autorizar el acceso a los datos, mostrar datos adicionales o configurar las preferencias del usuario.

Para autenticar usuarios con un servicio de terceros o un flujo de OAuth, tu app de Chat realiza los siguientes pasos:

  1. Detecta cuándo se requiere autorización o configuración.
  2. Devuelve una tarjeta de autorización básica que le solicite al usuario que acceda o configure el servicio.
  3. Redirige al URI de finalización para que Google Chat vuelva a intentar automáticamente la interacción original después de que el usuario complete la autorización.

Arquitectura de cómo las apps de Google Chat se autentican con un servicio de terceros.

Requisitos previos

HTTP

Una app de Google Chat que recibe y responde a las interacciones del usuario. Para compilar uno, completa la guía de inicio rápido de HTTP.

Apps Script

Una app de Google Chat que recibe y responde a las interacciones del usuario. Para compilar una, completa la guía de inicio rápido de Apps Script.

Detectar que se requiere autorización

Cuando interactúan con tu app de Chat, es posible que los usuarios no tengan autorización para acceder a un recurso protegido por varios motivos, como los siguientes:

  • Aún no se generó un token de acceso para conectarse al servicio de terceros o este venció.
  • El token de acceso no cubre el recurso solicitado.
  • El token de acceso no abarca los permisos requeridos de la solicitud.

Tu app de Chat debe detectar estos casos para que los usuarios puedan acceder y autorizar el acceso a tu servicio.

Si compilas en Apps Script, puedes usar la biblioteca de OAuth2 para Google Apps Script (o la versión de OAuth1), en la que la función hasAccess verifica si el usuario autorizó el acceso a un servicio. Como alternativa, cuando uses solicitudes de UrlFetchApp.fetch, puedes establecer el parámetro muteHttpExceptions en true para inspeccionar el código de respuesta y el contenido en el objeto HttpResponse devuelto.

Mostrar a los usuarios una tarjeta de autorización básica

Cuando tu app de Chat detecte que se requiere autorización o configuración, devuelve una respuesta AuthorizationError para mostrarle al usuario una tarjeta de autorización básica privada.

En la siguiente imagen, se muestra un ejemplo de la tarjeta de autorización básica de Google:

Es el mensaje básico de autorización para la cuenta de ejemplo.
Figura 1: Mensaje de autorización básica para la cuenta de ejemplo. El mensaje indica que la app de Chat desea mostrar información adicional, pero necesita la aprobación del usuario para acceder a la cuenta.

Para mostrar a los usuarios una tarjeta de autorización básica, devuelve un objeto AuthorizationError:

HTTP

Devuelve la siguiente respuesta JSON:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Reemplaza lo siguiente:

  • AUTHORIZATION_URL: Es la URL HTTPS de la app web que controla la autenticación, la autorización o la configuración.
  • RESOURCE_DISPLAY_NAME: Es el nombre visible del recurso o servicio protegido. Este nombre se muestra al usuario en el mensaje de autorización. Por ejemplo, si tu RESOURCE_DISPLAY_NAME es Example Account, el mensaje indica que la app necesita aprobación para acceder a tu Example Account.

Completa la solicitud de configuración

En Chat, el usuario puede completar el proceso de autorización y hacer que Chat vuelva a intentar automáticamente la interacción original sin una actualización manual. Chat admite reintentos automáticos si el activador es Mensaje, Se agregó al espacio o Comando de la app.

En el caso de estos activadores, tu app de Chat recibe un URI de redireccionamiento de finalización (configCompleteRedirectUri / completeRedirectUri) en la carga útil del evento:

  • Mensaje: chat.messagePayload.configCompleteRedirectUri
  • Se agregó al espacio: chat.addedToSpacePayload.configCompleteRedirectUri
  • Comando de la app: chat.appCommandPayload.configCompleteRedirectUri

Debes codificar este URI de redireccionamiento en tu <var>AUTHORIZATION_URL</var> y redireccionar el navegador del usuario a él después de que se complete el flujo de autorización. El redireccionamiento a esta URL indica a Google Chat que se cumplió la solicitud de autorización o configuración.

Cuando se redirecciona correctamente a un usuario al URI de redireccionamiento de finalización proporcionado en la carga útil del evento original, Google Chat realiza los siguientes pasos:

  1. Borra el mensaje de autorización privada que se muestra al usuario que inicia la acción.
  2. Convierte el mensaje original en público, lo que lo hace visible para otros miembros del espacio.
  3. Envía el objeto de evento original a tu app de Chat por segunda vez.

Si no redireccionas al URI de redireccionamiento de finalización, el usuario podrá completar el flujo de autorización, pero Google Chat no volverá a intentar automáticamente la ejecución anterior, y el usuario deberá invocar manualmente tu app de Chat.

Visitar un URI de redireccionamiento de finalización solo afecta una interacción del usuario. Si un usuario envió mensajes a una app de Chat varias veces y recibió varias indicaciones, completar el proceso de autenticación y configuración para una indicación solo reintenta esa interacción específica.

Autentica al usuario de Chat fuera de Chat

Cuando vinculas una URL fuera de Chat (como una devolución de llamada web de OAuth), a menudo necesitas correlacionar la sesión web externa con la identidad del usuario en Chat. Te recomendamos que protejas la app web de destino con el Acceso con Google.

Usa el token de identidad que se emitió durante el acceso para obtener el ID de usuario. El reclamo sub contiene el ID único de Google del usuario y se puede correlacionar con el nombre del recurso del usuario (chat.user.name) de Google Chat.

Para correlacionar el reclamo sub con un nombre de recurso users/{user} de Google Chat, antepone el valor del reclamo sub con users/. Por ejemplo, un valor de la reclamación sub de 123 corresponde a users/123 en los objetos de eventos enviados a tu app de Chat.

Muestras de código

En los siguientes ejemplos de código, se muestra cómo una app de Chat puede solicitar credenciales de OAuth2 sin conexión con una tarjeta de autorización básica, almacenarlas en una base de datos, redireccionar al URI de finalización y realizar llamadas a la API con autenticación del usuario:

Apps de Chat que no son complementos: Conecta una app de Chat con otros servicios y herramientas

Si mantienes una app de Chat que no es un complemento de Google Workspace, tu app de Chat solicita la configuración con un actionResponse de tipo REQUEST_CONFIG y lee configCompleteRedirectUrl desde el objeto Event de nivel superior.

Para actualizar una app de Chat que no es un complemento al framework de complementos de Google Workspace, consulta Cómo convertir una app de Google Chat en un complemento de Google Workspace.

Solicita la configuración a un usuario en una app de Chat que no sea un complemento

En una app de Chat que no sea un complemento, devuelve una URL de configuración al usuario con el siguiente formato:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

Esto le indica a Google Chat que le presente al usuario una instrucción privada, en la que CONFIGURATION_URL es un vínculo que el usuario puede visitar para obtener autenticación, autorización o configuración adicionales. Una respuesta de REQUEST_CONFIG es mutuamente exclusiva con un mensaje de respuesta normal; se ignoran todos los textos, las tarjetas o cualquier otro atributo.

Completa la solicitud de configuración en una app de Chat que no sea un complemento

Cada interacción de MESSAGE, ADDED_TO_SPACE y APP_COMMAND Event que recibe una app de Chat que no es un complemento incluye el campo de nivel superior configCompleteRedirectUrl. Codifica esta URL en la URL de configuración y redirecciona al usuario a ella cuando se complete la acción para que Google Chat borre la instrucción, convierta el mensaje original en público y vuelva a enviar el evento de interacción original a tu app de Chat.

Para ver ejemplos de implementaciones, consulta la app de ejemplo de conectividad de Node.js y la app de ejemplo de autenticación de MyProfile de Python en GitHub.