Programa respuestas automáticas con una app de Google Chat

1. Introducción

Las apps de Google Chat permiten que los servicios y recursos estén disponibles en Chat, donde los usuarios pueden obtener información y realizar acciones sin abandonar la conversación.

En este codelab, aprenderás a crear una app de Chat (“bot de asistencia”) que establece respuestas automáticas en Gmail y programa reuniones en Calendario de Google. Con un bot de asistencia compilado en Google Apps Script, podrás acceder con facilidad a otros servicios de Google, como Drive, Gmail, Calendario, Documentos, Hojas de cálculo y mucho más.

Qué aprenderás

• Cómo agregar controladores a eventos generados en Chat
• Cómo analizar objetos de eventos enviados desde Chat
• Cómo contestar a Chat mediante respuestas con formato de tarjeta
• Cómo definir las acciones personalizadas de los clics en botones de las tarjetas y cómo reaccionar ante esas acciones

Requisitos

• Acceso a Internet y un navegador web
• Una cuenta de Google Workspace con acceso a Google Chat
• Habilidades básicas de JavaScript, ya que Google Apps Script solo es compatible con JavaScript

Advertencia: Debes usar una cuenta de Google Workspace para completar este codelab. Usar una cuenta @gmail.com generará un error cuando intentes habilitar la API.

2. Obtén el código de muestra

Puedes descargar un archivo ZIP o clonar el repositorio de GitHub para ver el código de cada paso de esta muestra.

Las carpetas step-NN contienen el estado final deseado de cada paso de este codelab. Están disponibles como referencia.

Descarga el código

Para descargar el código de este codelab, haz clic en el siguiente botón:

Descargar código fuente

Descomprime el archivo ZIP descargado. Con esto se descomprime la carpeta raíz (hangouts-chat-apps-script-codelab), que contiene una carpeta de cada paso de este codelab.

Clona el repositorio de GitHub

Para clonar el repositorio de GitHub de este codelab, ejecuta el siguiente comando:

git clone https://github.com/googleworkspace/hangouts-chat-apps-script-codelab

3. Crea los controladores para eventos de Google Chat

Crea un proyecto de Apps Script

Para crear un proyecto Apps Script, sigue estos pasos:

1. Dirígete a script.new.
2. Haz clic en Proyecto sin título.
3. Cámbiale el nombre al Bot de asistencia de la secuencia de comandos y haz clic en Cambiar nombre.

Eventos en Google Chat

La mayoría de las interacciones de Apps Script con Chat se basan en eventos. Normalmente, la interacción entre el usuario, la app de Chat y Chat sigue esta secuencia:

1. Un usuario inicia una acción, por ejemplo, agregar una app de Chat a un espacio, lo que inicia un mensaje directo (MD) con una app de Chat, o quitar una app de Chat de un espacio.
2. La acción genera un evento dirigido a la app de Chat en Chat.
3. Chat llama al controlador del evento correspondiente definido en la secuencia de comandos de la app de Chat.

Chat genera 4 eventos que tu app puede escuchar:

• ADDED_TO_SPACE: Este evento ocurre cuando un usuario humano agrega una app de Chat a un espacio o a un mensaje directo (MD). En Apps Script, se define una función onAddToSpace() para controlar este evento.
• REMOVED_FROM_SPACE: Este evento ocurre cuando un usuario quita la app de Chat de un espacio o MD. Este evento no publica una respuesta en Chat. En Apps Script, se define una función onRemoveFromSpace() para controlar este evento.
• MESSAGE: Este evento ocurre cuando un usuario envía un mensaje a la app de Chat, ya sea directamente en un MD o como una mención con @ en un espacio. En Apps Script, se define una función onMessage() para responder a este evento.
• CARD_CLICKED: Este evento ocurre cuando un usuario hace clic en un botón con una acción personalizada asignada. En Apps Script, se define una función onCardClick() para responder a este evento.

Reemplaza el contenido del archivo Code.gs con el siguiente código que define controladores para los eventos ADDED_TO_SPACE y REMOVE_FROM_SPACE. Agregarás controladores para los eventos MESSAGE y CARD_CLICKED más adelante en este codelab.

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Publica y prueba la app de Chat

Actualiza el archivo de manifiesto de tu secuencia de comandos

Antes de que puedas publicar tu app en Chat, debes actualizar el manifiesto de la secuencia de comandos.

1. Haz clic en Configuración del proyecto .
2. Selecciona la casilla de verificación Mostrar el archivo de manifiesto "appsscript.json" en el editor.
3. Haz clic en Editor .
4. Haz clic en el archivo appsscript.json.
5. Agrega la línea "chat": {} a tu archivo de manifiesto.

Este archivo de manifiesto debería verse de manera similar al siguiente ejemplo:

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

Crea un proyecto de Google Cloud

Antes de que puedas ejecutar y probar la app de Chat, debes crear un proyecto de Google Cloud, habilitar y configurar la API de Chat y publicar tu app de Chat en tu organización de Google Workspace.

Nota: Si ejecutas este codelab desde un kiosco en un evento organizado por Google, significa que ya se creó un proyecto de la consola de Google Cloud por ti. Abre ese proyecto y avanza al tercer paso de la siguiente lista.

1. En la consola de Google Cloud, ve a Menú > IAM y administración > Crear un proyecto.
   Crear un proyecto
   
2. En el Nombre del proyecto, escribe un nombre descriptivo.
3. Si se te solicita, selecciona la Organización y Cuenta de facturación.
4. Haz clic en Crear.
5. Cuando se complete la creación del proyecto, aparecerá una notificación en la esquina superior derecha de la página. Haz clic en la entrada Crear proyecto: <Nombre del proyecto> para abrir el proyecto.
6. Haz clic en Menú > APIs y servicios > Credenciales.
7. Haz clic en la pantalla de consentimiento de OAuth.
8. En Nombre de la app, escribe Bot de asistencia.
9. Si se te solicita, escribe el correo electrónico de asistencia a los usuarios y la información de contacto del desarrollador.
10. Haz clic en Guardar y continuar.
11. Haz clic en Configuración y utilidades > Configuración del proyecto.
12. Copia el Número del proyecto.
13. En el editor de Apps Script, haz clic en Configuración del proyecto .
14. En Proyecto de Google Cloud Platform (GCP), haz clic en Cambiar proyecto.
15. Haz clic en número de proyecto de GCP y escribe el número del proyecto.
16. Haz clic en Establecer el proyecto.

Publica la app en Chat

Para publicar tu app de Chat en Google Chat, sigue estos pasos:

1. En el editor de Apps Script, haz clic en Implementar > Nueva implementación.
2. Junto a Seleccionar tipo, haz clic en Habilitar los tipos de implementación .
3. Selecciona Complemento y haz clic en Implementar.
4. Copia el ID de implementación y haz clic en Listo.
5. En la consola de Google Cloud, ve a Menú > APIs y servicios > Biblioteca.
   Ir a la biblioteca
   
6. Busca la API de Google Chat. Selecciona la API de la lista de resultados.
7. En la página de la API de Google Chat, haz clic en Habilitar.
8. Después de habilitar la API, haz clic en Configuración. Ignora los mensajes en los que se te solicita crear credenciales.
9. En la página Configuración, sigue estos pasos:

• En Nombre de la app, escribe Bot de asistencia.
• En URL del avatar, escribe https://goo.gl/kv2ENA.
• En Descripción, escribe App de chat del codelab de Apps Script.
• En Funcionalidad, selecciona Recibir mensajes 1:1.
• En Configuración de la conexión, selecciona Proyecto de Apps Script y pega el ID de implementación de tu secuencia de comandos en el cuadro de texto.
• En Permisos, selecciona Personas y grupos específicos de tu dominio. En el cuadro de texto debajo del menú desplegable, escribe tu dirección de correo electrónico asociada con tu organización de Google Workspace.
• Haz clic en Guardar.

Nota: Si intentas habilitar la API de Google Chat con una cuenta @gmail.com, recibirás el siguiente error:

La API "chat.googleapis.com" no existe o no tienes permiso para acceder a ella.

Asegúrate de haber accedido con una cuenta de Google Workspace o usa el selector de cuentas que está en la parte superior derecha de la consola de Cloud para cambiar a una cuenta de Google Workspace. Si creaste tu secuencia de comandos con una cuenta @gmail.com, debes compartirla con tu cuenta de Google Workspace.

Cuando guardes tus cambios, verifica que el estado en la página de la API de Google Chat muestre el Estado de la app como ACTIVA: disponible para los usuarios.

Prueba la app de Chat

Para probar tu app en Google Chat, sigue estos pasos:

1. Abre Google Chat.
2. Envía un nuevo mensaje directo a la app de Chat haciendo clic en Inicia un chat > Buscar apps.
3. En la página Buscar apps, busca Bot de asistencia.
4. Junto a Bot de asistencia, haz clic en Agregar > Chat.

Cuando se abre la conversación del mensaje directo, deberías ver un mensaje de la app de Chat en el que te agradece por agregarla a un MD, como se muestra en la siguiente imagen:

Nota: El código para esta app de Chat registra los objetos de eventos recibidos de Google Chat. Para ver la estructura de los objetos de eventos, consulta los registros. Para abrir los registros, en el editor de Apps Script, haz clic en Ver > Stackdriver Logging.

5. Define una respuesta con formato de tarjeta

En el paso anterior, tu app respondió a eventos de Google Chat con una respuesta de texto simple. En este paso, actualizarás tu app para que responda con tarjetas.

Respuestas con tarjeta

Google Chat admite el uso de tarjetas para crear respuestas. Las tarjetas son contenedores visuales que te permiten agrupar conjuntos de widgets de interfaz de usuario. Pueden mostrar encabezados, párrafos de texto, conjuntos de botones, imágenes y texto de par clave-valor. Tu app puede definir una o más tarjetas en la respuesta de JSON a Google Chat, que luego traduce tu respuesta en los elementos de la IU correspondientes.

En la siguiente imagen, se muestra una respuesta con tarjeta de tres secciones, que incluye un encabezado, un widget de clave-valor, un widget de imagen y un botón de texto.

Para responder los mensajes de los usuarios con una respuesta de tarjeta, agrega el siguiente código al archivo Code.gs de tu app de Chat.

Code.gs

var DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
var HEADER = {
  header: {
    title : 'Attendance Bot',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  var userMessage = event.message.text;

  var widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

La función onMessage(), que se agregó en este paso, lee el mensaje original del usuario y construye una respuesta como un widget TextParagragh simple. Luego, la función onMessage() llama a createCardResponse(), que coloca el widget TextParagraph dentro de una sección de una sola tarjeta. El bot envía el objeto JavaScript que se construyó mediante la respuesta con tarjeta de vuelta a Google Chat.

Prueba la app de Chat

Para probar esta app, vuelve a tu mensaje directo con la app en Google Chat y escribe un mensaje (cualquier mensaje servirá).

Ten en cuenta que el controlador del evento onMessage() analiza el objeto del evento que Google Chat le pasó para extraer el mensaje original del usuario. Además, puedes obtener otros tipos de información acerca del evento, como el nombre del usuario que inició el evento, su dirección de correo electrónico, el nombre del espacio en donde ocurrió el evento y mucho más.

Para obtener más información sobre la estructura de los objetos del evento que envió Google Chat, consulta Referencia sobre los formatos de eventos.

6. Reacciona ante clics en los botones de las tarjetas

En el paso anterior, tu app de Chat respondió a un mensaje de un usuario (un evento MESSAGE) con una tarjeta simple que contenía un widget TextParagragh. En este paso, crearás una respuesta que incluye botones, en la que cada uno tiene una acción personalizada definida.

Tarjetas interactivas

Las respuestas con tarjetas pueden contener uno de dos tipos de botones: widgets TextButton, que muestran botones con texto solamente, y widgets ImageButton, que muestran un botón con un ícono simple o una imagen sin texto. Tanto los widgets TextButton como ImageButton admiten uno de dos comportamientos onClick (como se define en la respuesta JSON enviada a Google Chat): ya sea openLink o action. Como implica el nombre, openLink abre un vínculo específico en una pestaña nueva del navegador.

El objeto action especifica una acción personalizada que debe realizar el botón. Puedes especificar diversos valores arbitrarios en el objeto de acción, como un actionMethodName único y un conjunto de pares de parámetros clave-valor.

Cuando especificas un objeto action para el botón, se crea una tarjeta interactiva. Cuando el usuario hace clic en el botón del mensaje, Google Chat genera un evento CARD_CLICKED y devuelve una solicitud a la app que envió el mensaje original. Luego, la app debe controlar el evento generado en Google Chat y devolver una respuesta al espacio.

Reemplaza la función onMessage() en Code.gs con el siguiente código. Este código crea 2 botones, Set vacation in Gmail y Block out day in Calendar, en la tarjeta enviada a Google Chat.

Code.gs

var REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  var reason = REASON.OTHER;
  var name = event.user.displayName;
  var userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  var widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Para controlar el evento CARD_CLICKED, debes agregar la función onCardClick() a la secuencia de comandos de tu app de Chat. Agrega el siguiente código que define la función Code.gs de onCardClick().

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/chat/api/guides/message-formats/events
 */
function onCardClick(event) {
  console.info(event);
  var message = '';
  var reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

Para responder a los clics del usuario, la app de Chat ahora realiza una de estas dos acciones: configura la respuesta automática del usuario en Gmail con una respuesta automática por estar fuera de la oficina o programa una reunión de todo el día en el Calendario del usuario. Para llevar a cabo estas tareas, la app llama al servicio avanzado de Gmail y al servicio de Calendario.

Agrega el siguiente código a tu secuencia de comandos para integrar la app de Chat en Gmail y Calendario.

Code.gs

var ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  var currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Bot!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

Por último, debes habilitar el servicio avanzado de Gmail en el proyecto. Para habilitar la API de Gmail, haz lo siguiente:

1. En el editor de Apps Script, junto a Servicios, haz clic en Agregar un servicio .
2. Selecciona API de Gmail.
3. Abajo, haz clic en Panel de la API de Google Cloud Platform, que abre la consola de Google Cloud.
4. Haz clic en Habilitar las APIs y los servicios.
5. Busca la API de Gmail y haz clic en ella.
6. En la página API de Gmail, haz clic en Habilitar.

Prueba la app de Chat

Para probar esta versión de tu app de Chat, abre el MD que iniciaste en los pasos anteriores en Google Chat y escribe Me tomaré vacaciones. La app debería responder con una tarjeta similar a la de la imagen de abajo.

Nota: Si se te solicita otorgar acceso a la app, es posible que debas escribir tu mensaje de nuevo.

7. ¡Felicitaciones!

Ahora, tu app de Chat puede responder mensajes del usuario, configurar la respuesta automática en Gmail y establecer un evento que dura todo el día en Calendario.

Temas abordados

• Cómo crear y publicar una app de Google Chat con Apps Script
• Cómo responder a mensajes de usuarios con una respuesta sencilla
• Cómo interactuar con otros servicios de Google Workspace en nombre del usuario mediante la app de Chat

Más información

• Sitio de documentación de Google Chat
• Guía de inicio rápido de la app de Chat en Apps Script
• Cómo crear apps de Chat
• Cómo publicar apps de Chat
• Cómo crear tarjetas interactivas
• Documentación de referencia sobre tarjetas
• Documentación de referencia sobre objetos de eventos
• Documentación de referencia sobre el servicio avanzado de Gmail
• Documentación de referencia sobre el servicio de Calendario