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 los diálogos y mensajes de tarjeta.

Mira la app de Chat en acción:

• 

  Figura 1: La app de chat responde al comando de barra /about con un mensaje de texto y un botón que abre un formulario de contacto.

• 
  Figura 2: La app de Chat abre un diálogo en el que los usuarios pueden ingresar información sobre un contacto.
• 
  Figura 3: La app de Chat muestra un diálogo de confirmación para que los usuarios puedan revisar y confirmar la información antes de enviarla.
• 
  Figura 4: Después de que el usuario envía el formulario, la app de Chat envía un mensaje de texto privado para confirmar el envío.
• 
  Figura 5: La app de Chat también les solicita a los usuarios que agreguen un contacto desde una tarjeta en un mensaje.

Requisitos previos

• Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat

Objetivos

• Diseña y compila interfaces de usuario (IU) como objetos card, y muestra las IUs en mensajes y diálogos.
• Recibir y procesar la información que los usuarios envían con widgets de entrada de formularios
• Responde a los comandos de barra mediante el envío de mensajes que contengan texto, tarjetas y widgets complementarios.

Arquitectura

La app de Chat está integrada en Google Apps Script y usa eventos de interacción para procesar y responder a los usuarios de Chat.

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

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

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

   • Responde a @menciones y mensajes directos con un mensaje de tarjeta que contiene el formulario de contacto.
   • Responde al comando de barra /addContact abriendo un diálogo con el formulario de contacto.
   • Responde al comando de barra /about con un mensaje de texto que tiene un botón Agregar un contacto en el que los usuarios pueden hacer clic para 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: Es un widget 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 el widget button en el que el usuario hace clic para enviar los valores que ingresa.

4. La app de Google Chat controla un evento de interacción CARD_CLICKED para procesar los valores que ingresa el usuario y mostrarlos en una tarjeta de confirmación.

5. El usuario revisa la tarjeta de confirmación y hace clic en el botón Enviar para 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 crear y configurar un proyecto de Google Cloud para la app de Chat.

Crea un proyecto de Google Cloud

Consola de Google Cloud

1. En la consola de Google Cloud, ve a Menú > IAM y administración > Crear un proyecto.

   Ir a Crear un proyecto

2. En el campo Nombre del proyecto, ingresa un nombre descriptivo para tu proyecto.

   Opcional: Para editar el ID del proyecto, haz clic en Editar. El ID del proyecto no se puede cambiar después de que se crea el proyecto. Por lo tanto, elige un ID que abarque tus necesidades durante todo el ciclo de vida del proyecto.

3. En el campo Ubicación, haz clic en Explorar para mostrar las posibles ubicaciones de tu proyecto. Luego, haga clic en Seleccionar.
   Precaución: ¿No encuentras tu organización de Google Workspace?
   Esto significa que no accediste a una cuenta de Google Workspace. Algunas de las funciones descritas en la documentación para desarrolladores de Google Workspace solo están disponibles para los proyectos asociados con una organización.
4. Haz clic en Crear. La consola de Google Cloud navega a la página Panel y se crea tu proyecto en pocos minutos.

gcloud CLI

En uno de los siguientes entornos de desarrollo, accede a Google Cloud CLI (gcloud):

• Cloud Shell: Para usar una terminal en línea con la CLI de gcloud ya configurada, activa Cloud Shell.
  Activar Cloud Shell
• Shell local: Para usar un entorno de desarrollo local, instala e inicializa la CLI de gcloud.
  Para crear un proyecto de Cloud, usa el comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID mediante la configuración del ID del proyecto que deseas crear.

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 solo para pruebas y uso interno, por lo que está bien 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 los marcadores de posición por información real.

1. En la consola de Google Cloud, ve a Menú > APIs y servicios > Pantalla de consentimiento de OAuth.

   Ir a la pantalla de consentimiento de OAuth

2. En Tipo de usuario, selecciona Interno y, luego, haz clic en Crear.

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

4. En Correo electrónico de asistencia al usuario, selecciona tu dirección de correo electrónico o un Grupo de Google apropiado.

5. En Información de contacto del desarrollador, ingresa tu dirección de correo electrónico.

6. Haga clic en Guardar y continuar.

7. En la página Permisos, haz clic en Guardar y continuar. (la app de Chat no requiere ningún permiso de OAuth).

8. Revisa el resumen y, luego, haz clic en Volver al panel.

Crea y, luego, implementa la app de Chat

En la siguiente sección, copiarás y actualizarás un proyecto completo de Apps Script que contiene todo el código de la aplicación requerido para tu app de chat, por lo que no es necesario copiar y pegar cada archivo.

De forma opcional, puedes ver todo el proyecto en GitHub.

Ver en GitHub

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

main.gs

Controla toda la lógica de la app, incluidos los eventos de interacción sobre cuándo los usuarios envían mensajes a la app de Chat, hacen clic en botones de un mensaje de la app de Chat o abren y cierran diálogos.

Ver código main.gs

apps-script/contact-form-app/main.gs

Ver en GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * 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 interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{
            buttonList: { buttons: [{
              text: "Add Contact",
              onClick: { action: {
                function: "openInitialDialog",
                interaction: "OPEN_DIALOG"
              }}
            }]}
          }]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openInitialDialog();
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openConfirmation" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openInitialDialog") {
    return openInitialDialog();
  // Confirmation dialog form page
  } else if (event.common.invokedFunction === "openConfirmation") {
    return openConfirmation(event);
  // Submission dialog form page
  } else if (event.common.invokedFunction === "submitForm") {
    return submitForm(event);
  }
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openInitialDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openConfirmation" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns the second step as a dialog or card message that lets users confirm details.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} returns a dialog or private card message.
 */
function openConfirmation(event) {
  const name = fetchFormValue(event, "contactName") ?? "";
  const birthdate = fetchFormValue(event, "contactBirthdate") ?? "";
  const type = fetchFormValue(event, "contactType") ?? "";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (event.isDialogEvent) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: event.user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Validates and submits information from a dialog or card message
  * and notifies status.
  *
  * @param {Object} event the interactive event with parameters.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(event) {
  const contactName = event.common.parameters["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (event.dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: event.user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + contactName
        }}
      }
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: event.user,
      text: confirmationMessage
    };
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}

contactForm.gs

Contiene los widgets que reciben datos de formularios de los usuarios. Estos widgets de entrada de formularios se muestran en tarjetas que aparecen en mensajes y diálogos.

Ver código contactForm.gs

apps-script/contact-form-app/contactForm.gs

Ver en GitHub

/**
 * Copyright 2024 Google Inc.
 *
 * 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.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_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
        }
      ]
    }
  }
];

appsscript.json

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

Ver código appsscript.json

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

Ver en GitHub

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Busca el número y el ID de tu proyecto de Cloud

1. En la consola de Google Cloud, ve a tu proyecto de Cloud.

   Ir a la consola de Google Cloud

2. Haz clic en Configuración y utilidades > Configuración del proyecto.

3. Anota los valores de los campos Número de proyecto y ID de proyecto. Los usarás en las siguientes secciones.

Crea el proyecto de Apps Script

Para crear un proyecto de Apps Script y conectarlo con tu proyecto de Cloud, haz lo siguiente:

1. Haz clic en el siguiente botón para abrir el proyecto de Apps Script Administrar contactos en Google Chat.
   Abrir el proyecto
2. Haz clic en Descripción general.
3. En la página de descripción general, haz clic en Crear una copia.

4. Asigna un nombre a tu copia del proyecto de Apps Script:

   1. Haz clic en Copia de Administrar contactos en Google Chat.

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

   3. Haga clic en Cambiar nombre.

Configura el proyecto de Cloud del proyecto de Apps Script

1. En tu proyecto de Apps Script, haz clic en Configuración del proyecto.
2. En Proyecto de Google Cloud Platform (GCP), haz clic en Cambiar proyecto.
3. En Número de proyecto de GCP, pega el número de proyecto de tu proyecto de Cloud.
4. Haz clic en Establecer el proyecto. El proyecto de Cloud y el proyecto de Apps Script ahora están conectados.

Crea una implementación de Apps Script

Ahora que todo el código está en su lugar, implementa el proyecto de Apps Script. Usas el ID de implementación cuando configuras 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 aún no se seleccionó Complemento, junto a Seleccionar tipo, haz clic en 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 Copiar para copiar el ID de implementación y, luego, en Listo.

Configura la app de Chat en la consola de Google Cloud

En esta sección, se muestra cómo configurar la API de Google Chat en la consola de Google Cloud 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 Google Cloud, haz clic en Menú > Más productos > Google Workspace > Biblioteca de productos > API de Google Chat > Administrar > Configuración.

   Ve 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 Description, escribe Manage your personal and business contacts.

5. Haz clic en el botón de activación Enable Interactive features.

6. En Funcionalidad, selecciona las casillas de verificación Recibir mensajes 1:1 y 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 Comandos de barra, configura los comandos de barra /about y /addContact:

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

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

11. En Registros, selecciona Registrar errores en Logging.

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

   Ve a Google Chat

2. Haz clic en Nuevo chat.
3. En el campo Add 1 or more people, escribe el nombre de tu app de Chat.

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

   Nota: Si tu app de Chat no aparece en la lista de resultados, asegúrate de haber incluido tu cuenta de Google Workspace en la configuración de Visibilidad de la página Configuración de la API de Chat en la consola de Google Cloud.

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 complementario 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 se usaron en este instructivo, te recomendamos borrar el proyecto de Cloud.

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo en el proyecto. Si utilizaste un proyecto existente para este instructivo, cuando lo borres, también borrarás cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL en appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de todo el proyecto.

Si planeas explorar varios instructivos y guías de inicio rápido, la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

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

   Ve al Administrador de recursos.

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

Temas relacionados

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