Compila interfaces de Google Chat

En esta página, se proporciona una descripción general de cómo compilar interfaces de usuario (IU) para complementos de Google Workspace que extienden Google Chat.

En Google Chat, los complementos aparecen para los usuarios como apps de Google Chat. Para obtener más información, consulta la descripción general de la extensión de Google Chat.

Para compilar interfaces para apps de Chat, usa los siguientes componentes de complementos:

  • Activadores: Son las formas en que los usuarios de Google Chat pueden invocar una app de Chat, como agregarla a un espacio o enviarle un mensaje.
  • Objetos de evento: Son los datos que las apps de Chat reciben de los activadores o las interacciones de la IU.
  • Acciones: Son las formas en que las apps de Chat pueden responder a las interacciones, como enviar mensajes o mostrar una interfaz de usuario basada en tarjetas.
La app de Chat recibe un objeto de evento de un activador de agregado al espacio
Figura 1: Cuando un usuario agrega una app de Chat a un espacio, se activa el activador Added to space y se envía un objeto de evento. Para responder con un mensaje, la app de Chat controla el objeto del evento y muestra una acción que crea el mensaje.

Las apps de chat pueden crear y mostrar tarjetas en las siguientes interfaces:

  • Mensajes que pueden contener texto, botones y tarjetas estáticas o interactivas.
  • Diálogos, que son tarjetas que se abren en una ventana nueva y, por lo general, solicitan a los usuarios que envíen información.
  • Vistas previas de vínculos, que son tarjetas que muestran información preliminar sobre un servicio externo.

Activadores

En esta sección, se explican los activadores que usan los complementos de Google Workspace en Chat.

Los activadores son las formas específicas en que los usuarios invocan una app de Chat con la IU de Chat, como usar @menciones o comandos de la app.

En la siguiente tabla, se muestran los activadores de Chat, una descripción y cómo suelen responder las apps de Chat:

Activador Descripción Respuesta típica
Se agregó al espacio

Un usuario agrega la app de Chat a un espacio, o un administrador de Google Workspace instala la app de Chat en espacios de mensajes directos para los usuarios de su organización. Para obtener información sobre las apps de Chat que instalan los administradores, consulta Cómo instalar apps de Marketplace en tu dominio en la documentación de ayuda para administradores de Google Workspace.

 La app de Chat envía un mensaje de integración que explica qué hace y cómo los usuarios del espacio pueden interactuar con ella.
Mensaje

Un usuario interactúa con la app de Chat en un mensaje de una de las siguientes maneras:

  • Envía un mensaje en un espacio de mensaje directo (MD) con la app de Chat.
  • @menciona la app de Chat en cualquier tipo de espacio.
  • Envía un mensaje que contiene un vínculo que coincide con el patrón de URL para las vistas previas de vínculos.
  • Escribe texto en el menú de selección múltiple de un widget selectionInput.
 La app de chat responde según el contenido del mensaje. Por ejemplo, una app de Chat responde al comando /about con un mensaje que explica las tareas que puede realizar la app de Chat.
Se quitó del espacio

Un usuario quita la app de Chat de un espacio o un administrador de Google Workspace desinstala la app de Chat de un usuario de su organización.

Los usuarios no pueden quitar las apps de Chat que instaló su administrador. Si un usuario instaló la app de Chat con anterioridad, esta permanecerá instalada, independientemente de que un administrador de Google Workspace intente desinstalarla.

 La app de Chat quita las notificaciones entrantes configuradas para el espacio (como borrar un webhook) y borra el almacenamiento interno. Las apps de chat no pueden responder con mensajes a este activador, ya que ya no son miembros del espacio.
Comando de la app

Un usuario usa un comando rápido o un comando de barra desde la app de Chat.

 La app de Chat responde al comando. Por ejemplo, responde con un mensaje o abre un diálogo.

A diferencia de otros complementos de Google Workspace, debes configurar las funciones de devolución de llamada para estos activadores con la API de Google Chat. Para obtener orientación, consulta Configura una app de Google Chat.

Para responder a un activador, consulta las siguientes guías:

Objetos de eventos

En esta sección, se definen y explican todos los elementos de los objetos de eventos de chat. Para obtener más información, consulta Objetos de evento.

Objeto de evento
commonEventObject object (CommonEventObject)
Un objeto que contiene información común a todos los objetos de evento, independientemente de la aplicación host.
chat object (Chat)
Un objeto que contiene toda la información sobre las interacciones de Chat.

Chat

Chat
chat.user object (User)
El usuario de Chat que interactuó con la app de Chat.
chat.space object (Space)
Es el espacio de Chat en el que un usuario interactuó con la app de Chat.
chat.eventTime

string (Timestamp format)

Es la hora en que ocurrió la interacción.

Campo de unión payload.

payload puede ser una de las siguientes opciones:
chat.messagePayload

object (MessagePayload)

Es la carga útil que las apps de Chat reciben de un activador de mensaje.
chat.addedToSpacePayload

object (AddedToSpacePayload)

La carga útil que las apps de Chat reciben de un activador de Se agregó al espacio
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

La carga útil que las apps de Chat reciben de un activador de Quitado del espacio
chat.buttonClickedPayload

object (ButtonClickedPayload)

La carga útil que reciben las apps de Chat cuando los usuarios hacen clic en un botón de un mensaje o una tarjeta. Si un usuario hace clic en un botón para enviar información, el objeto commonEventObject.formInputs contiene los valores recopilados del usuario. Para obtener más información, consulta Cómo recopilar información de los usuarios de Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

La carga útil que reciben las apps de chat cuando los usuarios escriben texto en el menú de selección múltiple de un widget selectionInput. Las apps de chat pueden usar este objeto de evento para propagar elementos sugeridos desde una fuente de datos dinámica. Por ejemplo, para propagar casos de asistencia desde una fuente de datos externa, una app de chat puede consultar la fuente de datos en función de lo que el usuario escribe en el menú y, luego, mostrar los casos de asistencia coincidentes como elementos seleccionables.

El objeto CommonEventObject.parameters['autocomplete_widget_query'] contiene el valor de cadena que el usuario escribe en el menú.

chat.appCommandPayload

object (AppCommandPayload)

La carga útil que reciben las apps de Chat cuando un usuario usa un comando de la app de Chat.

Carga útil

Según el tipo de interacción, el evento contiene una carga útil con uno o más recursos de la API de Chat.

Carga útil del mensaje
MessagePayload
chat.messagePayload.message object (Message)
Es el mensaje de Chat que activó el evento.
chat.messagePayload.space object (Space)
Es el espacio de Chat en el que un usuario envió el mensaje que invocó la app de Chat.

Se agregó a la carga útil del espacio
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Es el espacio de Chat al que el usuario agregó o instaló la app de Chat.

Cuando los administradores instalan apps de Chat, el campo space.adminInstalled se establece en true.

chat.addedToSpacePayload.interactionAdd boolean
Indica si un usuario agrega la app de Chat a un espacio con un mensaje. Por ejemplo, @menciona la app de Chat o usa un comando de barra. Si es true, Chat envía otro objeto de evento con un messagePayload que contiene información sobre el mensaje.

Se quitó de la carga útil del espacio
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
El espacio de Chat desde el que el usuario quitó o desinstaló la app de Chat.

Cuando los administradores desinstalan apps de Chat, el campo space.adminInstalled se establece en false.

Carga útil de clic en el botón
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Es el mensaje de Chat que contiene el botón en el que hizo clic un usuario.
chat.buttonClickedPayload.space object (Space)
Es el espacio de Chat en el que el usuario hizo clic en un botón de un mensaje de la app de Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Indica si el usuario hizo clic en el botón para interactuar con un diálogo.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Si isDialogEvent es true, es el tipo de interacción en un diálogo.

Enum DialogEventType.

El valor de dialogEventType puede ser solo una de las siguientes opciones:
TYPE_UNSPECIFIED Valor predeterminado Sin especificar.
REQUEST_DIALOG Un usuario solicita un diálogo. Por ejemplo, usan un comando de barra diagonal o hacen clic en un botón de un mensaje.
SUBMIT_DIALOG Un usuario hace clic en un elemento interactivo dentro de un diálogo. Por ejemplo, un usuario completa información en un diálogo y hace clic en un botón para enviarla.

Carga útil actualizada del widget
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Es el espacio de Chat en el que se produjo la interacción.

Carga útil del comando de la app
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Son metadatos sobre el comando que usó el usuario y cómo activó el comando.
chat.appCommandPayload.space object (Space)
Es el espacio de Chat en el que un usuario usó el comando.
chat.appCommandPayload.thread object (Thread)
Si la interacción se produjo en un subproceso, el subproceso de chat en el que el usuario usó el comando.
chat.appCommandPayload.message object (Message)
Es el mensaje que el usuario envió con el comando de barra.
chat.appCommandPayload.configCompleteRedirectUri string
Si se requiere autorización o configuración para el comando, es una URL a la que se redireccionará al usuario después de que complete el proceso fuera de Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Indica si el comando abre un diálogo.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Es el tipo de interacción con un diálogo.

Enum DialogEventType.

El valor de dialogEventType puede ser solo una de las siguientes opciones:
TYPE_UNSPECIFIED Valor predeterminado Sin especificar.
REQUEST_DIALOG Un usuario solicita un diálogo. Por ejemplo, usan un comando de barra diagonal o hacen clic en un botón de un mensaje.
SUBMIT_DIALOG Un usuario hace clic en un elemento interactivo dentro de un diálogo. Por ejemplo, un usuario completa información en un diálogo y hace clic en un botón para enviarla.
Metadatos de los comandos de la app
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

Es el ID del comando.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Es el tipo de comando.

Enum AppCommandType.

El valor de AppCommandType puede ser solo una de las siguientes opciones:
APP_COMMAND_TYPE_UNSPECIFIED Valor predeterminado Sin especificar.
SLASH_COMMAND Para usar el comando, el usuario envía un mensaje que comienza con una barra /.

Acciones del chat

En esta sección, se explica cómo las apps de Chat pueden usar acciones de complementos para responder a las interacciones del usuario.

Para responder con una acción de complemento, una app de Chat debe responder en un plazo de 30 segundos, y la respuesta debe publicarse en el espacio donde se produjo la interacción. De lo contrario, la app de Chat debe configurar la autenticación y llamar a la API de Google Chat para responder.

Las apps de chat pueden controlar y responder interacciones de muchas maneras. En muchos casos, las apps de Chat responden con un mensaje. Las apps de chat también pueden buscar información en una fuente de datos, registrar la información del objeto del evento o cualquier otra cosa. Este comportamiento de procesamiento es, en esencia, lo que define la app de Google Chat.

Para responder a las interacciones del usuario, las apps de Chat deben controlar el objeto de evento correspondiente y mostrar uno de los siguientes objetos JSON:

Respuesta deseada de la app de chat Acción obligatoria para devolver el producto
Envía o actualiza un mensaje. DataActions
Abrir, actualizar o cerrar un diálogo RenderActions
Para recopilar información de una tarjeta o un diálogo, sugiere elementos de selección según lo que los usuarios escriben en un menú de selección múltiple. RenderActions
Vista previa de los vínculos en los mensajes que los usuarios de Chat envían en un espacio. DataActions

Responde con la API de Google Chat

En lugar de mostrar una acción de complemento, es posible que las apps de Chat deban usar la API de Google Chat para responder a una interacción. Por ejemplo, las apps de Chat deben llamar a la API de Google Chat para realizar cualquiera de las siguientes acciones:

  • Responder una interacción después de 30 segundos
  • Realizar tareas fuera del espacio en el que se produjo la interacción
  • Realizar tareas en Chat que no están disponibles como acciones de complementos Por ejemplo, enumera los espacios de los que es miembro un usuario o una app de Chat, o bien agrega usuarios a un espacio.
  • Realizar tareas en nombre del usuario de Chat (lo que requiere la autenticación del usuario)

Para obtener información sobre cómo autenticar y llamar a la API de Chat, consulta la descripción general de la API de Chat.