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.
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 una vista previa de la información 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 barra.
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 del administrador 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:
|
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. |
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:
- Envía mensajes de Google Chat
- Abrir diálogos interactivos
- Obtén una vista previa de los vínculos en los mensajes de Google Chat
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 |
|
Campo de unión
|
|
chat.messagePayload |
Es la carga útil que las apps de Chat reciben de un activador de mensaje. |
chat.addedToSpacePayload |
La carga útil que las apps de Chat reciben de un activador de Se agregó al espacio |
chat.removedFromSpacePayload |
La carga útil que las apps de Chat reciben de un activador de Quitado del espacio |
chat.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 |
chat.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
El objeto |
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 |
chat.addedToSpacePayload.interactionAdd |
booleanIndica 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 |
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 |
booleanIndica 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 El valor de |
|
TYPE_UNSPECIFIED |
Valor predeterminado Sin especificar. |
REQUEST_DIALOG |
Un usuario solicita un diálogo. Por ejemplo, usan una 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. |
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:
DataActions: Crea o actualiza datos de Google Workspace. Para enviar o actualizar mensajes de chat, el objeto debe contener el marcado que define los cambios en los datosMessage, representados comochatDataActionMarkup.RenderActions: Muestra o navega entre tarjetas en mensajes y diálogos.basic_authorization_prompt: Solicita a los usuarios una tarjeta de autorización para acceder o autenticarse en un servicio externo a Google. Para obtener más información, consulta Cómo conectar tu complemento de Google Workspace a un servicio de terceros.
| 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.