Recopila y administra contactos en Google Chat

En este instructivo, se muestra cómo crear una app de Google Chat que ayude a los usuarios de Google Chat a administrar sus contactos personales y comerciales. Para recopilar información, la app de Chat les solicita a los usuarios que completen un formulario de contacto en mensajes de tarjetas y diálogos.

Mira la app de Chat en acción:

Requisitos previos

• Una cuenta de Google Workspace para empresas o Enterprise con acceso a Google Chat
• Crea un proyecto de Google Cloud

Objetivos

• Diseñar y compilar interfaces de usuario (IU) como objetos card, y mostrar las IU en mensajes y diálogos
• Recibir y procesar la información que los usuarios envían a través de widgets de entrada de formularios
• Responder a comandos con mensajes que contienen texto, tarjetas y widgets de accesorios

Arquitectura

La app de Chat está integrada en Google Apps Script (como un complemento de Google Workspace que extiende Google Chat) y responde a las interacciones del usuario (onMessage, onAppCommand y clics en botones que invocan openInitialDialog, openConfirmationDialog y submitForm) para procesar y responder a los usuarios de Chat.

A continuación, se muestra cómo un usuario podría interactuar normalmente con la app de Chat:

1. Un usuario abre un mensaje directo con la app de Chat o agrega la app de Chat a un espacio existente.

2. La app de Chat le solicita al usuario que agregue un contacto creando y mostrando un formulario de contacto como un objeto card. Para presentar el formulario de contacto, la app de Chat responde a los usuarios de las siguientes maneras:

   • Responde a las @menciones y los mensajes directos (onMessage) con un mensaje de tarjeta que contiene el formulario de contacto.
   • Responde al comando de barra /addContact (onAppCommand) abriendo un diálogo con el formulario de contacto.
   • Responde al comando de barra /about (onAppCommand) con un mensaje de texto que tiene un botón Agregar un contacto en el que los usuarios pueden hacer clic para invocar openInitialDialog y abrir un diálogo con el formulario de contacto.

3. Cuando se le presenta el formulario de contacto, el usuario ingresa la información de contacto en los siguientes campos y widgets:

   • Nombre y apellido: Un widget textInput que acepta cadenas.
   • Fecha de nacimiento: Es un widget dateTimePicker que solo acepta fechas.
   • Tipo de contacto: Un widget de selectionInput de botones de selección que permite a los usuarios seleccionar y enviar un solo valor de cadena (Personal o Work).
   • Botón Revisar y enviar: Es un array buttonList con un widget button en el que el usuario hace clic para enviar los valores que ingresa.

4. La app de Google Chat invoca openConfirmationDialog para procesar los valores que ingresa el usuario y los muestra en una tarjeta de confirmación.

5. El usuario revisa la tarjeta de confirmación y hace clic en el botón Enviar para invocar submitForm y finalizar la información de contacto.

6. La app de Google Chat envía un mensaje de texto privado que confirma el envío.

Prepare el entorno

En esta sección, se muestra cómo configurar un proyecto de Google Cloud para la app de Chat.

Abre tu proyecto de Cloud en la consola de APIs de Google.

Si aún no está abierto, abre el proyecto de Cloud que deseas usar para esta muestra:

1. En la consola de APIs de Google, ve a la página Selecciona un proyecto.

   Selecciona un proyecto de Cloud

2. Selecciona el proyecto de Google Cloud que deseas usar. O bien haz clic en Crear proyecto y sigue las instrucciones en pantalla. Si creas un proyecto de Google Cloud, es posible que debas activar la facturación para el proyecto.

Configura la autenticación y la autorización

Las apps de Google Chat requieren que configures una pantalla de consentimiento de OAuth para que los usuarios puedan autorizar tu app en las aplicaciones de Google Workspace, incluido Google Chat.

En este instructivo, implementarás una app de Chat que solo se usará para pruebas y uso interno, por lo que puedes usar información de marcador de posición para la pantalla de consentimiento. Antes de publicar la app de Chat, reemplaza la información de marcador de posición por información real.

1. En la consola de APIs de Google, ve a Menú menu > Plataforma de Google Auth > Branding.

   Ir a Branding

2. Si ya configuraste la plataforma de Google Auth, puedes configurar los siguientes parámetros de configuración de la pantalla de consentimiento de OAuth en Branding, Audience y Data Access. Si ves un mensaje que dice Aún no se configuró Google Auth Platform, haz clic en Comenzar:

   1. En Información de la app, en Nombre de la app, escribe Contact Manager.
   2. En Correo electrónico de asistencia del usuario, selecciona tu dirección de correo electrónico o un grupo de Google adecuado.
   3. Haz clic en Siguiente.
   4. En Público, selecciona Interno. Si no puedes seleccionar Interno, selecciona Externo.
   5. Haz clic en Siguiente.
   6. En Información de contacto, ingresa una dirección de correo electrónico en la que puedas recibir notificaciones sobre cualquier cambio en tu proyecto.
   7. Haz clic en Siguiente.
   8. En Finalizar, revisa la Política de Datos del Usuario de los Servicios de las APIs de Google y, si la aceptas, selecciona Acepto la Política de Datos del Usuario de los Servicios de las APIs de Google.
   9. Haz clic en Continuar.
   10. Haz clic en Crear.
   11. Si seleccionaste Externo para el tipo de usuario, agrega usuarios de prueba:
       1. Haz clic en Público.
       2. En Usuarios de prueba, haz clic en Agregar usuarios.
       3. Ingresa tu dirección de correo electrónico y los demás usuarios de prueba autorizados, y haz clic en Guardar.

Crea e implementa la app de Chat

En la siguiente sección, crearás y actualizarás un proyecto de Apps Script con el código de la aplicación (Code.gs y appsscript.json) para tu app de Chat.

De manera opcional, puedes ver el proyecto completo en GitHub.

Ver en GitHub

A continuación, se incluye una descripción general de cada archivo:

Code.gs

Controla toda la lógica de la app, incluidas las interacciones del usuario (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog y submitForm) y los widgets de entrada de formularios que se muestran en las tarjetas de los mensajes y los diálogos.

Ver código de Code.gs

apps-script/chat/contact-form-app/Code.gs

Ver en GitHub

/**
 * Copyright 2025 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [
      { buttonList: { buttons: [{
        text: "ADD CONTACT",
        onClick: { action: {
          function: "openInitialDialog",
          interaction: "OPEN_DIALOG"
        }}
      }]}}
    ]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    { dateTimePicker: {
      name: "contactBirthdate",
      label: "Birthdate",
      type: "DATE_ONLY"
    }},
    { selectionInput: {
      name: "contactType",
      label: "Contact type",
      type: "RADIO_BUTTON",
      items: [
        { text: "Work", value: "Work", selected: false },
        { text: "Personal", value: "Personal", selected: false }
      ]
    }},
    { buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

appsscript.json

El manifiesto de Apps Script que define y configura el proyecto de Apps Script para la app de Chat.

Ver código de appsscript.json

apps-script/chat/contact-form-app/appsscript.json

Ver en GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

Crea el proyecto de Apps Script

Para crear un proyecto de Apps Script a partir de los archivos Code.gs y appsscript.json, haz lo siguiente:

1. Ve a Google Apps Script y haz clic en Nuevo proyecto.

2. Asigna un nombre a tu proyecto de Apps Script:

   1. Haz clic en Proyecto sin título.

   2. En Título del proyecto, escribe Contact Manager - Google Chat app.

   3. Haga clic en Cambiar nombre.

3. Reemplaza el contenido de Code.gs con el código de muestra de Code.gs anterior.

4. Haz clic en Configuración del proyecto y selecciona Mostrar el archivo de manifiesto "appsscript.json" en el editor.

5. Vuelve al Editor y reemplaza el contenido de appsscript.json por el código del manifiesto de appsscript.json que se mostró anteriormente. Luego, guarda tu proyecto.

En el futuro, si quieres usar ciertas APIs de Google o publicar tu app, deberás asociar tu proyecto de Cloud con tu proyecto de Apps Script. Para esta guía, no es necesario que lo hagas. Para obtener más información, consulta la guía de proyectos de Google Cloud.

Crea una implementación de Apps Script

Ahora que todo el código está en su lugar, implementa el proyecto de Apps Script. Usarás el ID de implementación cuando configures la app de Chat en Google Cloud.

1. En Apps Script, abre el proyecto de la app de Chat.

   Ir a Apps Script

2. Haz clic en Implementar > Nueva implementación.

3. Si Complemento aún no está seleccionado, junto a Seleccionar tipo, haz clic en los tipos de implementación y selecciona Complemento.

4. En Descripción, ingresa una descripción para esta versión, como Test of Contact Manager.

5. Haz clic en Implementar. Apps Script informa que la implementación se realizó correctamente y proporciona un ID de implementación.

6. Haz clic en content_copy Copiar para copiar el ID de implementación y, luego, en Listo.

Configura la app de Chat en la Consola de APIs de Google

En esta sección, se muestra cómo configurar la API de Google Chat en la Consola de APIs de Google con información sobre tu app de Chat, incluido el ID de la implementación que acabas de crear desde tu proyecto de Apps Script.

1. En la consola de APIs de Google, haz clic en Menú menu > APIs y servicios > APIs y servicios habilitados > API de Google Chat > Configuración.

   Ir a la configuración de la API de Chat

2. En Nombre de la app, escribe Contact Manager.

3. En URL del avatar, escribe https://developers.google.com/chat/images/contact-icon.png.

4. En Descripción, escribe Manage your personal and business contacts.

5. Haz clic en el botón de activación Habilitar funciones interactivas.

6. En Funcionalidad, selecciona Unirse a espacios y conversaciones grupales.

7. En Configuración de conexión, selecciona Apps Script.

8. En ID de implementación, pega el ID de implementación de Apps Script que copiaste en la sección anterior cuando creaste la implementación de Apps Script.

9. En Activadores, configura las funciones que responden a las interacciones del usuario:

   • En el activador Mensaje, ingresa onMessage.
   • Para el activador Comando de la app, ingresa onAppCommand.

10. En Comandos, configura los comandos de barra /about y /addContact:

    1. Haz clic en Agregar un comando para configurar el primer comando de barra.
    2. En ID de comando, escribe 1.
    3. En Descripción, escribe Learn how to use this Chat app to manage your contacts.
    4. En Tipo de comando, selecciona Slash command.
    5. En Nombre del comando de barra, escribe /about.
    6. Haz clic en Listo.
    7. Haz clic en Agregar un comando para configurar otro comando de barra.
    8. En ID de comando, escribe 2.
    9. En Descripción, escribe Submit information about a contact.
    10. En Tipo de comando, selecciona Slash command.
    11. En Nombre del comando de barra, escribe /addContact.
    12. Selecciona Abrir un diálogo.
    13. Haz clic en Listo.

11. En Visibilidad, selecciona la casilla de verificación Hacer que esta app de Chat esté disponible para personas y grupos específicos de YOUR DOMAIN y escribe tu dirección de correo electrónico.

12. En Registros, selecciona Registrar errores en Logging.

13. Haz clic en Guardar. Aparecerá un mensaje de configuración guardada.

La app de Chat está lista para instalarse y probarse en Chat.

Prueba la app de Chat

Para probar tu app de Chat, abre un espacio de mensajes directos con la app de Chat y envía un mensaje:

1. Abre Google Chat con la cuenta de Google Workspace que proporcionaste cuando te agregaste como verificador de confianza.

   Ir a Google Chat

2. Haz clic en add Nuevo chat.
3. En el campo Agregar 1 o más personas, escribe el nombre de tu app de Chat.

4. Selecciona la app de Chat en los resultados. Se abrirá un mensaje directo.

1. En el nuevo mensaje directo con la app de Chat, escribe /addContact y presiona Intro.

2. En el diálogo que se abre, ingresa la información de contacto:

   1. En el campo de texto Nombre y apellido, ingresa un nombre.
   2. En el selector de fecha Fecha de nacimiento, selecciona una fecha.
   3. En Tipo de contacto, selecciona el botón de selección Trabajo o Personal.

3. Haz clic en Revisar y enviar.

4. En el diálogo de confirmación, revisa la información que enviaste y haz clic en Enviar. La app de Chat responde con un mensaje de texto que dice ✅ CONTACT NAME has been added to your contacts..

5. De manera opcional, también puedes probar y enviar el formulario de contacto de las siguientes maneras:

   • Usa el comando de barra /about. La app de chat responde con un mensaje de texto y un botón de widget de accesorio que dice Add a contact. Puedes hacer clic en el botón para abrir un diálogo con el formulario de contacto.
   • Envía un mensaje directo a la app de Chat sin un comando de barra, como Hello. La app de Chat responde con un texto y una tarjeta que contiene el formulario de contacto.

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este instructivo, te recomendamos que borres el proyecto de Cloud.

1. En la consola de APIs de Google, ve a la página Administrar recursos. Haz clic en Menú menu > IAM y administración > Administrar recursos.

   Ir al administrador de recursos

2. En la lista de proyectos, selecciona el proyecto que deseas borrar y, luego, haz clic en Borrar delete.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

Temas relacionados

• Cómo responder a comandos
• Recopila y procesa información de los usuarios de Google Chat
• Abrir diálogos interactivos
• Explora otros ejemplos de apps de Google Chat