Convierte una app interactiva de Google Chat en un complemento de Google Workspace

Si creaste y publicaste una app de Google Chat que usa eventos de interacción de la API de Google Chat, como una basada en la guía de inicio rápido de la app de Google Chat, en esta página, se muestra cómo convertirla en un complemento de Google Workspace que extienda Google Chat.

Con la conversión, tu app de Google Chat puede usar el framework de complementos de Google Workspace, lo que abre nuevas posibilidades de integración y funciones en Google Chat y en todo Google Workspace. Por ejemplo, en lugar de dos distribuciones (una app de Google Chat y un complemento de Google Workspace), puedes distribuir un solo complemento de Google Workspace a través de Google Workspace Marketplace que extienda las apps de Chat junto con otras aplicaciones host de Google Workspace, como Gmail, Calendario y Documentos.

Limitaciones

Antes de comenzar la conversión, revisa las limitaciones de los complementos de Google Workspace que extienden Google Chat para asegurarte de que tu app de Google Chat se pueda convertir sin perder la funcionalidad esencial.

Paso 1: Copia el código existente de tu app de Google Chat

El proceso de conversión requiere cambios en el código. Para evitar que se vea afectada tu app de Google Chat activa, crea y trabaja en una copia de tu código.

Apps Script

  1. Abre tu proyecto existente de Google Apps Script de la app de Google Chat.
  2. A la izquierda, haz clic en Descripción general .
  3. A la derecha, haz clic en Crear una copia .
  4. A la izquierda, haz clic en Configuración del proyecto .
  5. En Proyecto de Google Cloud, haz clic en Cambiar proyecto.
  6. Ingresa el mismo número de proyecto asociado con tu proyecto existente de la app de Google Chat.
  7. Haz clic en Establecer el proyecto.

HTTP

Crea una bifurcación o una copia de tu base de código existente y, luego, impleméntala como un servicio nuevo, independiente de tu app de Google Chat activa.

Si tu app se implementa en Google Cloud y depende de funciones vinculadas al proyecto de Google Cloud (por ejemplo, la identidad predeterminada de App Engine), el código nuevo se debe implementar en un servicio asociado al proyecto existente de la app de Google Chat.

Paso 2: Modifica el código copiado

Los complementos de Google Workspace que extienden Google Chat usan estructuras de solicitud y respuesta diferentes en comparación con las apps de Google Chat creadas con eventos de interacción de la API de Chat. Debes actualizar tu código para usar el complemento de Google Workspace EventObject en lugar de Event de la API de Google Chat para las solicitudes y respuestas. Usa la Guía de conversión de código para modificar tu código.

Paso 3: Habilita la configuración del complemento de Google Workspace para los usuarios de prueba

Usa la consola de Google Cloud para configurar los parámetros del complemento de Google Workspace para tu app de Google Chat:

  1. Ve a la página de configuración de la API de Google Chat en la consola de Google Cloud.

    Ir a la página de configuración de la API de Google Chat

  2. En Funciones interactivas, haz clic en Convertir en complemento.

  3. Habilita Activar la configuración de complementos.

  4. En la sección Visibilidad, agrega las direcciones de correo electrónico de tus usuarios de prueba.

  5. Si es necesario, actualiza la Configuración de conexión con la URL del extremo de implementación o el ID de implementación de Apps Script del código de la app de Google Chat que copiaste y modificaste en el paso 2.

  6. Haz clic en Guardar y probar.

Paso 4: Prueba la app convertida

Prueba a fondo la funcionalidad del complemento de Google Workspace con las cuentas de usuario de prueba configuradas en el paso 3. Verifica todas las funciones y las interacciones.

Paso 5: Completa la conversión para todos los usuarios

Después de verificar que el complemento de Google Workspace convertido funcione correctamente, puedes ponerlo a disposición de todos los usuarios.

  1. Ve a la página de configuración de la API de Google Chat en la consola de Google Cloud.

    Ir a la página de configuración de la API de Google Chat

  2. En Funciones interactivas, haz clic en Convertir en complemento. Se abrirá un panel lateral.

  3. En el panel lateral, haz clic en Convertir en complemento.

  4. Escribe el ID de tu proyecto y haz clic en Convertir.

Tu app de Google Chat ahora es un complemento de Google Workspace que extiende Google Chat.

Opcional: Borra o libera los recursos de Google Cloud que no se usan

De manera opcional, después de convertir tu app de Google Chat en un complemento de Google Workspace, para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usa la app de Google Chat y que ya no están en uso, considera desactivarlos.

Guía de conversión de código

En esta sección, se detalla la asignación entre el formato de interacción de la API de Google Chat Event y el formato del complemento de Google Workspace EventObject.

Asignación de solicitudes

En la siguiente tabla, se muestra cómo se asignan los campos de la API de Google Chat Event a los campos correspondientes del complemento de Google Workspace EventObject.

Campo Event de interacción de la API de Google Chat Campo EventObject del complemento de Google Workspace Notas
action.actionMethodName N/A En el caso de las interacciones con tarjetas, el nombre del método se puede pasar como un parámetro en commonEventObject.parameters. Consulta Cómo abrir un diálogo inicial.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Disponible en diferentes cargas útiles según el tipo de evento.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Disponible en diferentes cargas útiles según el tipo de evento.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Disponible en diferentes cargas útiles según el tipo de evento.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Disponible en diferentes cargas útiles según el tipo de evento.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Disponible en diferentes cargas útiles según el tipo de evento.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Disponible en diferentes cargas útiles según el tipo de evento.
token N/A La verificación se controla de manera diferente. Consulta Verificación de solicitudes para apps HTTP.
type N/A El tipo de evento se puede deducir del activador.
user chat.user

Asociación de solicitudes por caso de uso

En la siguiente tabla, se muestran las diferencias en las cargas útiles de las solicitudes para casos de uso comunes entre las apps de Google Chat creadas con eventos de interacción de la API de Chat y los complementos de Google Workspace que extienden Google Chat.

Caso de uso Carga útil de la interacción con la API de Chat Event Carga útil del complemento de Google Workspace EventObject
Se agregó la app al espacio 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Quitar la app del espacio 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
El usuario @menciona una app 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
El usuario menciona con @ a una app para agregarla al espacio. Debes controlar una solicitud de Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Debes controlar dos solicitudes de Google Chat.

Primera solicitud:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Segunda solicitud:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Comando de barra 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Comando de barra para agregar una app al espacio Debes controlar una solicitud de Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Debes controlar dos solicitudes de Google Chat.

Primera solicitud:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Segunda solicitud:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
El usuario hace clic en un botón de una tarjeta o un diálogo. 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Para los eventos de diálogo, common.formInputs contiene valores de widgets. Ejemplo de Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

Para los eventos de diálogo, commonEventObject.formInputs contiene valores de widgets. Ejemplo de Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
El usuario envía información en una tarjeta de la página principal de la app 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
El usuario invoca un comando de app con un comando rápido 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Vista previa del vínculo 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
El usuario actualiza un widget en un mensaje de tarjeta o diálogo. 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Asignación de respuestas por caso de uso

Los complementos de Google Workspace que extienden Google Chat devuelven acciones en lugar de un objeto Message. En la siguiente tabla, se asignan los tipos de respuesta Message de la API de Google Chat a sus equivalentes de acción de complementos de Google Workspace.

Caso de uso Respuesta Message de la API de Google Chat Respuesta de la acción de Chat del complemento de Google Workspace
Crea un mensaje en el espacio invocado 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse es opcional. Para obtener más información, consulta Cómo responder a un comando de barra.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Para obtener más información, consulta Cómo enviar un mensaje.
Actualiza un mensaje 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Para obtener más información, consulta Actualiza un mensaje (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Para obtener más información, consulta Actualiza un mensaje (complementos).
Vista previa del vínculo 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Para obtener más información, consulta Cómo obtener una vista previa de un vínculo (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Para obtener más información, consulta Cómo obtener una vista previa de un vínculo(complementos).
Abrir un diálogo inicial 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Para obtener más información, consulta Cómo abrir un diálogo (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
La tarjeta que envías puede contener widgets con acciones onClick. En el caso de los complementos de Google Workspace basados en HTTP, configura estas acciones para llamar a un extremo de función: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Para obtener más información, consulta Cómo abrir un diálogo (complementos).
Cómo cerrar un diálogo 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Para obtener más información, consulta Cómo cerrar un diálogo (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Para obtener más información, consulta Cómo cerrar un diálogo (complementos).
Conéctate a un sistema externo (solicita configuración) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Para obtener más información, consulta Cómo conectarse a un sistema externo.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Para obtener más información, consulta Cómo conectar tu complemento de Google Workspace a un servicio de terceros.
Elementos de autocompletado en widgets interactivos 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Para obtener más información, consulta Cómo agregar un menú de selección múltiple.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Para obtener más información, consulta Cómo recopilar y procesar información de los usuarios de Google Chat.

Cómo controlar las interacciones con tarjetas en mensajes creados antes de la conversión

Cuando conviertes una app de Google Chat HTTP en un complemento de Google Workspace, las interacciones con tarjetas en los mensajes creados antes de la conversión requieren un tratamiento especial. Los complementos de Google Workspace usan una URL HTTP completa para el action.function de una tarjeta, mientras que las apps de Google Chat creadas con eventos de interacción de la API de Google Chat usan un nombre de función. En la siguiente tabla, se resumen estas diferencias.

App de Google Chat compilada con eventos de interacción de la API de Google Chat Complemento de Google Workspace que extiende Google Chat
Configuration Configuras un solo extremo para todos los eventos en la consola de Google Cloud. Cuando se implementan interacciones de tarjetas, el action de una tarjeta solo contiene el nombre de la función que se ejecutará. Se invoca el extremo HTTP común para los eventos de clic en la tarjeta.

Para obtener más información, consulta Cómo abrir un diálogo (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 De manera opcional, puedes configurar extremos por evento en la consola de Google Cloud, pero esto no incluye los eventos de clics en tarjetas. Cuando implementes interacciones con tarjetas, el action de una tarjeta debe contener la URL completa del extremo HTTP que se invocará. Puedes establecer un extremo HTTP único por botón o usar un extremo común y pasar la acción como un parámetro en action.parameters.

Para obtener más información, consulta Cómo abrir un diálogo (complementos).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Para garantizar que las interacciones con tarjetas funcionen en los mensajes creados antes de la conversión, configura una URL de interacción con tarjetas en la página de configuración de la API de Google Chat.

Esta URL solo se usa para las interacciones en los mensajes creados antes de que convirtieras tu app. Cuando un usuario interactúa con uno de estos mensajes, el valor action.function original se pasa como un parámetro llamado __action_method_name__.

Ejemplo: Clic en la tarjeta

Si configuraste la URL de interacción de la tarjeta como https://.../card-interaction-handler y un usuario hace clic en una tarjeta de un mensaje histórico con la siguiente acción:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Se entrega un evento a la URL de interacción con la tarjeta configurada con el siguiente formato:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Ejemplo: Menú de selección múltiple

Si un usuario interactúa con un menú de selección múltiple con una fuente de datos externa, sucede lo siguiente:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Se entrega un evento a la URL de interacción con la tarjeta configurada con el siguiente formato:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Si activas Usar una URL de extremo HTTP común para todos los activadores para tus activadores HTTP, la URL común también se usará para los eventos de Button Clicked.

Verifica las solicitudes de complementos de Google Workspace HTTP que extienden Chat

En el caso de las apps de Google Chat basadas en HTTP, la lógica para verificar que las solicitudes provienen de Google debe actualizarse cuando se convierten en complementos de Google Workspace.

Las diferencias clave en la verificación de solicitudes son las siguientes:

Tipo de aplicación Público admitido Correo electrónico de la cuenta de servicio
App de Google Chat compilada con eventos de interacción de la API de Google Chat Número del proyecto chat@system.gserviceaccount.com
Complemento de Google Workspace que extiende Google Chat Solo extremo HTTP Correo electrónico de la cuenta de servicio por proyecto

El correo electrónico único de la cuenta de servicio de tu complemento de Google Workspace se encuentra en la sección Convertir en complementos de Google Workspace de la página de configuración de la API de Google Chat en la consola de Google Cloud.

Para verificar las solicitudes en tu complemento actualizado de Google Workspace, haz lo siguiente:

  1. Si usas Cloud Run Functions, otorga el rol roles/cloudfunctions.invoker a la cuenta de servicio por complemento. Consulta Autoriza el acceso con la IAM.
  2. Actualiza el código de verificación del token para usar la dirección de correo electrónico de la cuenta de servicio del complemento de Google Workspace y verificar la firma del token de portador. Consulta Cómo validar solicitudes de Google.