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

Si creaste y publicaste una app de Chat que no es un complemento de Google Workspace, en esta página se muestra cómo convertirla en un complemento de Google Workspace que extienda Google Chat.

Cuando la conviertas, tu app de Google Chat podrá usar el framework de complementos de Google Workspace, lo que abrirá nuevas posibilidades de integración y funciones en Google Chat y en todo Google Workspace. Por ejemplo, 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 y consideraciones de los complementos de Google Workspace para asegurarte de que tu app de Chat que no es un complemento 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 Información .
  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 Chat que no son complementos. Debes actualizar tu código para usar objetos de eventos de complementos de Google Workspace (EventObject) en lugar de eventos de interacción de la API de Google Chat (Event) 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, activa Habilitar funciones interactivas.

  3. En Convert to Google Workspace add-on, haz clic en Convert to add-on.

  4. Habilita Activar la configuración de complementos.

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

  6. 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.

  7. 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 convertido de Google Workspace 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 generen cargos en 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 los campos de la API de Google Chat Event para una app de Chat que no es un complemento se asignan a los campos correspondientes en el complemento de Google Workspace EventObject.

App de Chat que no es un complemento (campo Event) 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 maneja de manera diferente. Consulta Solicita la verificación de 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 Chat que no son complementos y los complementos de Google Workspace que extienden Google Chat.

Caso de uso App de chat que no es un complemento (carga útil de Event) Carga útil del complemento de Google Workspace EventObject
Se agregó la app al espacio 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Quitar 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 para una app de Chat que no es un complemento a sus equivalentes de acción de complemento de Google Workspace.

Caso de uso App de chat que no es un complemento (respuesta de Message) 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 responder con un mensaje.
Actualiza un mensaje 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

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

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

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

Para obtener más información, consulta Vínculos de vista previa.

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

Para obtener más información, consulta Vínculos de vista previa.
Abrir un diálogo inicial 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Para obtener más información, consulta Cómo abrir diálogos interactivos.

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
La tarjeta que envías puede contener widgets con acciones de 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 diálogos interactivos.
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.

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

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

Para obtener más información, consulta Conéctate a un sistema externo (apps de Chat que no son complementos).

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

Para obtener más información, consulta Cómo conectar una app de Chat con otros servicios y herramientas.
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 leer los datos del formulario que ingresan los usuarios en las tarjetas.

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

Cuando conviertes una app de Chat HTTP que no es un complemento 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 usan una URL HTTP completa para el action.function de una tarjeta, mientras que las apps de Chat que no son complementos usan un nombre de función. En la siguiente tabla, se resumen estas diferencias.

App de Chat que no es un complemento 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 diálogos interactivos.



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Opcionalmente, puedes configurar extremos por evento en la consola de Google Cloud, pero esto no incluye los eventos de clics en tarjetas. Cuando implementes interacciones de 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 diálogos interactivos.



{
  "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 original de action.function 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 la opción 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 provengan de Google debe actualizarse cuando se conviertan en un complemento 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 Chat que no es un complemento 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 tu código de verificación de tokens 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.