Para evitar el cambio de contexto cuando los usuarios comparten un vínculo en Google Chat, la app de Chat puede obtener una vista previa del vínculo adjuntando una tarjeta al mensaje que proporcione más información y permita que las personas realicen acciones directamente desde Google Chat.
Por ejemplo, imagina un espacio de Google Chat que incluya a todos los agentes de atención al cliente de una empresa, además de una app de Chat llamada Case-y. Con frecuencia, los agentes comparten vínculos a casos de atención al cliente en el espacio de Chat y, cada vez que lo hagan, sus colegas deberán abrir el vínculo del caso para ver detalles como el destinatario, el estado y el asunto. Del mismo modo, si alguien desea hacerse cargo de un caso o cambiar el estado, deberá abrir el vínculo.
La vista previa de vínculos permite que Case-y, la app de Chat residente del espacio, adjunte una tarjeta que muestre al destinatario, el estado y el asunto cada vez que alguien comparte el vínculo de un caso. Los botones de la tarjeta permiten que los agentes se hagan cargo del caso y cambien el estado directamente desde el flujo del chat.
Cómo funciona la vista previa de vínculos
Cuando alguien agrega un vínculo a su mensaje, aparece un chip que le informa que una app de Chat podría obtener una vista previa del vínculo.
Después de enviar el mensaje, se envía el vínculo a la app de Chat, que genera la tarjeta y la adjunta al mensaje del usuario.
Junto al vínculo, la tarjeta proporciona información adicional sobre el vínculo, incluidos elementos interactivos como botones. Tu app de Chat puede actualizar la tarjeta adjunta en respuesta a las interacciones del usuario, como los clics en botones.
Si alguien no desea que la app de Chat adjunte una tarjeta al mensaje para obtener una vista previa de su vínculo, puede hacer clic en
en el chip de vista previa y evitar que se muestre la vista previa. Los usuarios pueden quitar la tarjeta adjunta en cualquier momento haciendo clic en Quitar vista previa.Cómo configurar las vistas previas de vínculos
Registra vínculos específicos, como example.com
, support.example.com
y support.example.com/cases/
, como patrones de URL en la página de configuración de tu app de Chat en la consola de Google Cloud para que tu app de Chat pueda obtener una vista previa de ellos.
- Abre la consola de Google Cloud
- Junto a “Google Cloud”, haz clic en la flecha hacia abajo y abre el proyecto de tu app de Chat.
- En el campo de búsqueda, escribe
Google Chat API
y haz clic en API de Google Chat. - Haz clic en Administrar > Configuración.
- En Vistas previas de vínculos, agrega o edita un patrón de URL.
- Si deseas configurar las vistas previas de vínculos para un patrón de URL nuevo, haz clic en Agregar patrón de URL.
- Para editar la configuración de un patrón de URL existente, haz clic en la flecha hacia abajo .
En el campo Patrón de host, ingresa el dominio del patrón de URL. La app de Chat obtendrá una vista previa de los vínculos a este dominio.
Para que la app de Chat obtenga una vista previa de los vínculos de un subdominio específico, como
subdomain.example.com
, incluye el subdominio.Para que la app de Chat obtenga una vista previa de los vínculos de todo el dominio, especifica un carácter comodín y un asterisco (*) como subdominio. Por ejemplo,
*.example.com
coincide consubdomain.example.com
yany.number.of.subdomains.example.com
.En el campo Prefijo de la ruta de acceso, ingresa una ruta de acceso para adjuntar al dominio del patrón de host.
Para que todas las URLs del dominio del patrón de host coincidan, deja vacío el campo Prefijo de la ruta de acceso.
Por ejemplo, si el patrón de host es
support.example.com
, ingresacases/
para que coincida con las URLs de los casos alojados ensupport.example.com/cases/
.Haz clic en Listo.
Haz clic en Guardar.
Ahora, cada vez que alguien incluya un vínculo que coincida con un patrón de URL de vista previa del vínculo con un mensaje en un espacio de Chat que incluya tu app de Chat, la app obtendrá una vista previa del vínculo.
Cómo obtener una vista previa de un vínculo
Una vez que configures la vista previa de un vínculo determinado, la app de Chat podrá reconocerlo y obtener una vista previa si le adjunta más información.
Dentro de los espacios de Chat que incluyen tu app de Chat, cuando el mensaje de una persona contiene un vínculo que coincide con un patrón de URL de vista previa del vínculo, tu app de Chat recibe un evento de interacción MESSAGE
. La carga útil de JSON para el evento de interacción contiene el campo matchedUrl
:
JSON
"message": {
. . . // other message attributes redacted
"matchedUrl": {
"url": "https://support.example.com/cases/case123"
},
. . . // other message attributes redacted
}
Si verificas la presencia del campo matchedUrl
en la carga útil del evento MESSAGE
, tu app de Chat puede agregar información al mensaje con el vínculo de la vista previa. Tu app de Chat puede responder con un mensaje de texto simple o adjuntar una tarjeta.
Responder con un mensaje de texto
Para obtener respuestas simples, tu app de Chat puede obtener una vista previa de un vínculo respondiendo con un mensaje de texto simple a un vínculo. En este ejemplo, se adjunta un mensaje que repite la URL del vínculo que coincide con un patrón de URL de vista previa.
Node.js
Apps Script
Adjuntar una tarjeta
Para adjuntar una tarjeta a un vínculo en la vista previa, muestra un objeto ActionResponse
de tipo UPDATE_USER_MESSAGE_CARDS
. En este ejemplo, se adjunta una tarjeta simple.
Node.js
Apps Script
En este ejemplo, se muestra el JSON de la tarjeta para enviar un mensaje de tarjeta. También puedes usar el servicio de tarjetas de Apps Script.
Actualizar una tarjeta
Para actualizar la tarjeta adjunta a un vínculo de la vista previa, muestra un ActionResponse
de tipo UPDATE_USER_MESSAGE_CARDS
. Las apps de chat solo pueden actualizar tarjetas con vistas previas de los vínculos como respuesta a un evento de interacción de la app de Chat.
Las apps de Chat no pueden actualizar estas tarjetas llamando a la API de Chat de forma asíncrona.
La vista previa del vínculo no admite que se muestre un ActionResponse
de tipo UPDATE_MESSAGE
. Dado que UPDATE_MESSAGE
actualiza todo el mensaje en lugar de solo la tarjeta, solo funciona si la app de Chat creó el mensaje original. La vista previa de vínculos adjunta una tarjeta a un mensaje creado por el usuario, por lo que la app de Chat no tiene permiso para actualizarla.
Para garantizar que una función actualice las tarjetas creadas por usuarios y por apps en el flujo de Chat, configura dinámicamente ActionResponse
según si la app de Chat o un usuario creó el mensaje.
- Si un usuario creó el mensaje, configura
ActionResponse
comoUPDATE_USER_MESSAGE_CARDS
. - Si una app de Chat creó el mensaje, configura
ActionResponse
comoUPDATE_MESSAGE
.
Existen dos maneras de hacerlo: especificar y verificar un actionMethodName
personalizado como parte de la propiedad onclick
de la tarjeta adjunta (que identifica el mensaje como creado por el usuario) o comprobar si un usuario creó el mensaje.
Opción 1: Busca actionMethodName
Para usar actionMethodName
a fin de controlar correctamente los eventos de interacción con CARD_CLICKED
en las tarjetas que ya tienen una vista previa, establece una actionMethodName
personalizada como parte de la propiedad onclick
de la tarjeta adjunta:
JSON
. . . // Preview card details
{
"textButton": {
"text": "ASSIGN TO ME",
"onClick": {
// actionMethodName identifies the button to help determine the
// appropriate ActionResponse.
"action": {
"actionMethodName": "assign",
}
}
}
}
. . . // Preview card details
Si "actionMethodName": "assign"
identifica el botón como parte de la vista previa de un vínculo, es posible mostrar el ActionResponse
correcto de forma dinámica si se busca un actionMethodName
que coincida:
Node.js
Apps Script
En este ejemplo, se muestra el JSON de la tarjeta para enviar un mensaje de tarjeta. También puedes usar el servicio de tarjetas de Apps Script.
Opción 2: Verifica el tipo de remitente
Verifica si message.sender.type
es HUMAN
o BOT
. Si es HUMAN
, establece ActionResponse
en UPDATE_USER_MESSAGE_CARDS
; de lo contrario, establece ActionResponse
en UPDATE_MESSAGE
. Aquí te indicamos cómo hacerlo:
Node.js
Apps Script
En este ejemplo, se muestra el JSON de la tarjeta para enviar un mensaje de tarjeta. También puedes usar el servicio de tarjetas de Apps Script.
Un motivo típico para actualizar una tarjeta es en respuesta a un clic en un botón. Recuerda el botón Asignar a mí de la sección anterior, Adjuntar una tarjeta. En el siguiente ejemplo completo, se actualiza la tarjeta para que indique que se asignó a “Tú” cuando un usuario hace clic en Asignar a mí. En el ejemplo, se verifica el tipo de remitente para establecer ActionResponse
de forma dinámica.
Ejemplo completo: Case-y, la app de Chat de atención al cliente
Este es el código completo de Case‐y, una app de chat que muestra una vista previa de los vínculos a casos compartidos en un espacio de Chat en el que colaboran los agentes de atención al cliente.
Node.js
Apps Script
En este ejemplo, se muestra el JSON de la tarjeta para enviar un mensaje de tarjeta. También puedes usar el servicio de tarjetas de Apps Script.
Límites y consideraciones
Cuando configures las vistas previas de vínculos para tu app de Chat, ten en cuenta estos límites y consideraciones:
- Cada app de Chat admite vistas previas de vínculos para un máximo de 5 patrones de URL.
- Las apps de chat obtienen una vista previa de un vínculo por mensaje. Si un único mensaje contiene varios vínculos con vista previa, solo se mostrará la vista previa del primer vínculo.
- Las apps de Chat solo obtienen una vista previa de los vínculos que comienzan con
https://
, por lo que se usahttps://support.example.com/cases/
para obtener una vista previa, perosupport.example.com/cases/
no lo hace. - A menos que el mensaje incluya otra información que se envía a la app de Chat, como un comando de barra, solo la URL del vínculo se envía a la app de Chat a través de las vistas previas.
- Las tarjetas adjuntas a los vínculos de vista previa solo admiten un elemento
ActionResponse
de tipoUPDATE_USER_MESSAGE_CARDS
y solo en respuesta a un evento de interacción de la app de Chat. Las vistas previas de vínculos no admitenUPDATE_MESSAGE
ni solicitudes asíncronas para actualizar tarjetas adjuntas a un vínculo de vista previa mediante la API de Chat. Para obtener más información, consulta Cómo actualizar una tarjeta.
Cómo depurar vistas previas de vínculos
Cuando implementes vistas previas de vínculos, es posible que debas leer sus registros para depurar tu app de Chat. Para leer los registros, visita el Explorador de registros en la consola de Google Cloud.