Cómo conectar una app de Chat con otros servicios y herramientas

Si bien las apps 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.

Solicita la configuración de la app

Además de presentar las URL como parte de una respuesta normal, las apps pueden presentar de forma privada una URL de configuración al usuario en respuesta a un mensaje.

Cómo mostrar una URL de configuración

Si completar una solicitud requiere una configuración adicional que no se puede completar directamente en la aplicación, muestra una respuesta del siguiente formato:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

Esto le indica a Google Chat que presenta un mensaje privado al usuario con un vínculo para visitar la URL de configuración proporcionada a fin de realizar la autenticación, la autorización o la configuración. Una respuesta de configuración de solicitud es mutuamente excluyente con un mensaje de respuesta normal. Se ignorará cualquier texto, tarjeta o cualquier otro atributo.

La app solicita al usuario que proporcione una URL de configuración.

Todos los eventos para tu app también incluyen un parámetro configCompleteRedirectUrl. Esta URL debe estar codificada en tu URL de configuración para usarla al finalizar el proceso. El redireccionamiento a esta URL le indica a Google Chat que se completó la solicitud de configuración.

Cuando tu app inicia el flujo, puede depender del mensaje específico recibido. En respuesta a un mensaje como @app help, una app debe responder con un mensaje sin requerir configuración adicional.

Cuando un usuario se redirecciona correctamente a la configCompleteRedirectUrl proporcionada en el mensaje original, Google Chat realiza los siguientes pasos:

  1. Borrar el mensaje que se le mostró al usuario inicial
  2. Convierte el mensaje original en público para que lo vean otros miembros del espacio
  3. Envía el mensaje original a la misma app por segunda vez

Visitar un objeto configCompleteRedirectUrl solo afecta a un único mensaje de los usuarios. Si un usuario intentó enviar un mensaje a una app varias veces y, como resultado, recibió varios mensajes, hacer clic en un mensaje particular y completar el proceso de autenticación o configuración solo afecta a ese mensaje o mensaje en particular. Los demás mensajes y mensajes no se modifican.

Cuando se vuelve a enviar un evento de esta manera, normalmente debería ser idéntico al evento original. Sin embargo, hay algunas situaciones en las que los eventos pueden diferir. Por ejemplo, cuando un mensaje menciona la app A y la B, el usuario podrá editar el texto del mensaje si la app A responde con un mensaje regular antes de autenticarse con la app B. En este caso, la app B recibirá el texto del mensaje editado una vez que el usuario complete la autenticación.

Identifica al usuario en los mensajes de la app

Cada mensaje enviado a tu app incluye la identidad del usuario que interactúa con ella.

El siguiente fragmento JSON de ejemplo muestra el formato esperado de la identidad del usuario en un mensaje a tu app.

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

Usa el valor de la propiedad users.name como ID principal del usuario. El valor es un ID estable y único para cada usuario.

Cómo identificar al usuario de Chat fuera de Google Chat

En algunos casos, como cuando solicitas la autorización de OAuth para una API, tu app necesita vincularse a una URL fuera de Google Chat mientras mantiene la identidad del usuario. La mejor manera de identificar al usuario en estos casos es proteger la app de destino con el Acceso con Google.

Usa el token de identidad emitido durante el acceso para obtener el ID del usuario. La reclamación sub contiene el ID único del usuario y puede correlacionarse con el ID de Google Chat.

Si bien los dos ID no son exactamente idénticos, se los coerciona de manera sencilla. Para convertir el valor de la reclamación sub en un nombre de usuario de Google Chat, debes anteponer el valor con "users/". Por ejemplo, el valor del reclamo de 123 es equivalente al nombre de usuario users/123 en los mensajes de tu app de Chat.

Ejemplo completo

En la app de MyProfile, se muestra cómo usar la respuesta de REQUEST_CONFIG para iniciar la configuración de la app y se usa el token de identidad de la respuesta de Acceso con Google a fin de identificar al usuario.