Recopila y administra contactos en Google Chat

En este instructivo, se muestra cómo compilar una app de Google Chat que ayude Los usuarios de Google Chat administran sus contactos personales y empresariales. Para recopilar la app de Chat les pedirá a los usuarios que completen un formulario de contacto en los mensajes y diálogos de tarjetas.

Mira la app de Chat en acción:

• 

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

• 
  Figura 2: El Chat abre un diálogo en el que los usuarios ingresar información sobre un contacto
• 
  Figura 3: El la app de Chat devuelve un diálogo de confirmación que los usuarios puedan revisar y confirmar la información antes en el envío.
• 
  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: El La app de Chat también les solicita a los usuarios que agreguen un contacto desde una tarjeta en un mensaje.

Requisitos previos

• Una empresa o empresa de Google Workspace 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.
• Recibe y procesa la información que envían los usuarios a través de widgets de entrada de formulario.
• Para responder a los comandos de barra, envía mensajes que contienen texto, tarjetas y widgets de accesorios.

Arquitectura

La app de Chat está integrada Google Apps Script y utiliza 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. agrega la app de Chat a un espacio existente.

2. La app de Chat le solicita al usuario que agregue un contacto crea y muestra un formulario de contacto como card . Para presentar el formulario de contacto, la app de Chat 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: Es 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 Administrador > 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. No se puede cambiar el ID del proyecto una vez creado el proyecto, así que elige un ID que se adapte a tus necesidades durante el ciclo de vida del en un proyecto final.

3. En el campo Ubicación, haz clic en Explorar para mostrar las posibles ubicaciones de tu en un proyecto final. 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
• Local Shell: Para usar un entorno de desarrollo local, instalar y inicializar con gcloud CLI.
  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 la pantalla de consentimiento de OAuth para los usuarios pueden autorizar tu app en aplicaciones de Google Workspace, incluidas 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. (El 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 de Apps Script que contiene toda la aplicación necesaria de Google Chat para tu app de Chat, de modo que no es necesario copiar y pegar cada archivo.

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:

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, haz clic en botones de un mensaje de la app de Chat o abrir y cerrar diálogos.

Ver código de 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: "openDialog",
              interaction: "OPEN_DIALOG"
            }}
          }]}}]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openDialog(event);
    }
  }

  // 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 : "openNextCard" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * 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 === "openDialog") {
    return openDialog(event);
  // Second dialog form page
  } else if (event.common.invokedFunction === "openNextCard") {
    return openNextCard(
      event.user,
      fetchFormValue(event, "contactName"),
      fetchFormValue(event, "contactBirthdate"),
      fetchFormValue(event, "contactType"),
      event.isDialogEvent
    );
  // Dialog form submission
  } else if (event.common.invokedFunction === "submitForm") {
    const userInputs = event.common.parameters;
    return submitForm(event.user, userInputs, event.dialogEventType);
  }
}

/**
 * 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;
}

/**
 * Opens a dialog that prompts users to add details about a contact.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openDialog() {
  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: "openNextCard" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns a dialog or card message that displays a confirmation of contact
 * details before users submit.
 *
 * @param {String} user the user who submitted the information.
 * @param {String} contactName the contact name from the previous dialog or card.
 * @param {String} contactBirthdate the birthdate from the previous dialog or card.
 * @param {String} contactType the contact type from the previous dialog or card.
 * @param {boolean} fromDialog whether the information was submitted from a dialog.
 *
 * @return {Object} returns a dialog or private card message.
 */
function openNextCard(user, contactName, contactBirthdate, contactType, fromDialog) {
  const name = contactName ?? "<i>Not provided</i>";
  const birthdate = contactBirthdate ?? "<i>Not provided</i>";
  const type = contactType ?? "<i>Not provided</i>";
  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 (fromDialog) {
    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: user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Submits information from a dialog or card message.
  *
  * @param {Object} user the person who submitted the information.
  * @param {Object} userInputs the form input values from event parameters.
  * @param {boolean} dialogEventType "SUBMIT_DIALOG" if from a dialog.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(user, userInputs, dialogEventType) {
  const contactName = userInputs["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 (dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: 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 (dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "NEW_MESSAGE",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + JSON.stringify(contactName)
        }}
      },
      privateMessageViewer: user,
      text: confirmationMessage
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: user,
      text: confirmationMessage
    };
  }
}

/**
 * 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. Ingresa el formulario los widgets se muestran en tarjetas que aparecen en mensajes y diálogos.

Ver código de 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 de 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 a tu Proyecto de Cloud:

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 Project Settings.
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 tu proyecto de Cloud.
4. Haz clic en Establecer el proyecto. El proyecto de Cloud y Apps Script proyecto están ahora conectados.

Crea una implementación de Apps Script

Ahora que está listo todo el código, implementa Apps Script en un proyecto final. El ID de implementación se usa para configurar App de Chat en Google Cloud.

1. En Apps Script, abre la ventana de la app de Chat en un proyecto final.

   Ir a Apps Script

2. Haz clic en Implementar > Implementación nueva.

3. Si Complemento aún no está seleccionado, junto a Selecciona el 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. Se realizaron correctamente los informes de Apps Script Deployment y proporciona un ID de implementación.

6. Haz clic en Copiar para copiar. el ID de implementación y, luego, haz clic 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 la app de Chat, incluida la ID de la implementación que acabas de crear desde Apps Script en un proyecto final.

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.

   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 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, Únete a espacios y conversaciones grupales.

7. En Configuración de la 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 Haz que esta app de Chat esté disponible para personas y grupos específicos en la casilla de verificación YOUR DOMAIN y, luego, ingresa 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 que se proporcionan cuando te agregaste como verificador de confianza.

   Ir 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 no ves tu app de Chat 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 de 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, elige 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 mensaje que dice ✅ CONTACT NAME has been added to your contacts.

5. También puedes probar y enviar el formulario de contacto de la siguiente manera maneras:

   • Usa el comando de barra /about. Respuestas de la app de Chat con un mensaje de texto y un botón de widget de accesorios que diga 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 respuestas 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 el recursos usados en este instructivo, te recomendamos que borres el 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, elige el proyecto que quieres borrar y haz clic en Borra .
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo. el proyecto.

Temas relacionados

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