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 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 Business o Enterprise con acceso a Google Chat.
• Crea un proyecto de Google Cloud.

Objetivos

• Diseñar y crear interfaces de usuario (IU) como objetos card y mostrarlas en mensajes y diálogos.
• Recibir y procesar la información que los usuarios envían con widgets de entrada de formularios.
• Responder a los comandos con mensajes que contengan texto, tarjetas y widgets de accesorios

Arquitectura

La app de Chat se compila 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 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 solicita al usuario que agregue un contacto mediante la creación y la visualización de un formulario de contacto como un card objeto. 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 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 presenta el formulario de contacto, el usuario ingresa la información de contacto en los siguientes campos y widgets:

   • Nombre y apellido: Un textInput widget que acepta cadenas.
   • Fecha de nacimiento: Un dateTimePicker widget que solo acepta fechas.
   • Tipo de contacto: un selectionInput widget de botones de selección que permite a los usuarios seleccionar y enviar un solo valor de cadena (`Personal` o `Work`).PersonalWork
   • Botón Revisar y enviar: Un buttonList array con un 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 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 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 Seleccionar 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 que aparecen 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 cualquier 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 autenticación de Google > Branding.

   Ir a Branding

2. Si ya configuraste la plataforma de autenticación de Google, puedes configurar los siguientes parámetros de configuración de la pantalla de consentimiento de OAuth en Branding, Público, y Acceso a los datos. Si ves un mensaje que dice Aún no se configuró la plataforma de autenticación de Google, 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 estás de acuerdo, 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 como 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, copiarás y actualizarás un proyecto completo de Apps Script que contiene todo el código de aplicación necesario para tu app de Chat, por lo que no es necesario copiar y pegar cada archivo.

De manera 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 los botones de un mensaje de la app de Chat o abren y cierran diálogos.

Ver el 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.
  const errorMessage = "Don't forget to name your new contact!";
  if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  }
  if (!contactName) {
    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
        }}
      }
    };
  }
  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 el 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 el código appsscript.json

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

Ver en GitHub

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

Crea el proyecto de Apps Script

Para crear un proyecto de Apps Script, sigue estos pasos:

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 info_outline Descripción general.
3. En la página de descripción general, haz clic en Crear una copia.

4. Nombra 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.

En el futuro, si deseas usar ciertas APIs de Google o publicar tu app, debes 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 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, haz clic 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. Borra Crear esta app de Chat como complemento de Google Workspace. Se abrirá un diálogo en el que se te pedirá que confirmes. En el diálogo, haz clic en Inhabilitar.

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

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

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

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

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

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

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

10. En Comandos, 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. En Tipo de comando, selecciona Slash command.
    6. En Nombre del comando de barra, escribe /about.
    7. Selecciona Abrir un diálogo.
    8. Haz clic en Listo.
    9. Haz clic en Agregar un comando para configurar otro comando de barra.
    10. En Nombre, escribe Add a contact.
    11. En ID de comando, escribe 2.
    12. En Descripción, escribe Submit information about a contact.
    13. En Tipo de comando, selecciona Slash command.
    14. En Nombre del comando de barra, escribe /addContact.
    15. Selecciona Abrir un diálogo.
    16. Haz clic en Listo.

11. En Visibilidad, selecciona la Hacer que esta app de Chat esté disponible para personas y grupos específicos de YOUR DOMAIN casilla de verificación y, luego, ingresa 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 mensaje directo 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 evaluador 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 tu app de Chat en los resultados. Se abrirá un mensaje directo.

1. En el nuevo mensaje directo con la app de Chat, escribe /addContacty presiona enter.

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 a la app de Chat un mensaje directo 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 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

• Responder a los comandos
• Recopilar y procesar información de los usuarios de Google Chat
• Abrir diálogos interactivos
• Explorar otras muestras de apps de Google Chat