Se usó la API de Cloud Translation para traducir esta página.

Cómo desarrollar una app de Chat con Apps Script

Apps Script es una de las formas más rápidas de crear una app de chat para Google Chat.

Puedes poner una aplicación en funcionamiento en unos pocos minutos directamente en el navegador.
No tienes que preocuparte por ejecutar y administrar los servidores, los costos operativos o de mantenimiento continuos, o incluso por descargar y configurar un entorno de desarrollo.
Es muy fácil llamar a las API de Google, especialmente a las API deGoogle Workspace , ya que con Apps Script no hay descargas o configuraciones, la autenticación se maneja automáticamente y las llamadas a la API de Google son como llamadas a funciones nativas.

En esta guía, se explica cómo crear y registrar una app con Apps Script.

Primeros pasos

En esta sección, se muestra cómo crear rápidamente una aplicación de Chat con Apps Script.

Paso 1: Copia la plantilla de Apps Script

La forma más fácil de comenzar a crear una app de Apps Script es mediante la plantilla de Chat. Esto crea un proyecto de Apps Script con los métodos que necesita. Luego, propaga los métodos según sea necesario para implementar la lógica de tu app o integrarla con una app que hayas compilado. El siguiente código muestra un ejemplo de la plantilla propagada para una app simple.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}

Paso 2: Edita la función onMessage

De forma predeterminada, la función onMessage de la plantilla muestra un objeto Message que contiene texto y una tarjeta simple. Puedes editar esta función para que muestre texto o widgets de tarjetas específicos.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

Paso 3: Obtén el ID de implementación

A fin de poder registrar tu app, deberás obtener el ID de implementación para esta app específica.

Haga clic en Implementar > Nueva implementación.
En Seleccionar tipo, haz clic en Complemento.
Completa las opciones y haz clic en Implementar.
En "ID de implementación", haz clic en Copiar.

Consulta la guía de administración de versiones a fin de obtener información sobre las prácticas recomendadas para usar los ID de implementación.

Paso 4: Registra la app

Puedes registrar tu app desde Google Cloud Console. En la pantalla de registro de la app, ingresa el nombre, la URL del avatar y la descripción de la app. Para realizar pruebas, puedes habilitar "Se puede enviar un mensaje directamente a la app" y "La app funciona en espacios con varios usuarios". En la configuración de conexión, elige Apps Script y pega el ID de implementación que copiaste en el paso anterior.

Configuración de conexión para registrar tu app.

Paso 5: Prueba tu app

Para probar tu app, puedes iniciar un MD con ella o @mencionarlo en un espacio. Cuando le hables, responderá a la respuesta del mensaje del paso 2. Listo.

Conceptos de la app de Apps Script

Eventos

Apps Script admite varias funciones de controlador de eventos que tu app puede implementar. Cada función controla un tipo de evento diferente y cada función recibe un solo argumento e, que es un objeto Event.

onAddToSpace(e): Esta función se ejecuta cuando se agrega tu app a un espacio. Tu app se puede agregar directamente al espacio o mediante una @mención. En el segundo caso, el evento e también tendrá una propiedad message. Esta función debe mostrar un objeto Message, que suele ser un mensaje de bienvenida para informar a los usuarios finales sobre tu app o una respuesta a la @mención.
onMessage(e): Se llama a esta función cuando tu app ya está en el espacio y el usuario la @menciona. Debería mostrar un objeto Message que contenga la respuesta de tu app.
onRemoveFromSpace(e): Se llama a esta función cuando el usuario quita tu app de su lista de MD o de un espacio. El valor de retorno de esta función se ignora debido a que se quitó tu app y no puede publicar más mensajes.

En el siguiente ejemplo, se implementan onAddToSpace y onRemoveFromSpace:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

Ten en cuenta que e.space.displayName podría no estar presente en los mensajes directos entre personas.

Tarjetas interactivas

Al igual que otras apps, las apps de Apps Script pueden mostrar tarjetas interactivas. Para obtener información sobre cómo hacer que las tarjetas sean interactivas, consulta esa documentación sobre tarjetas interactivas. La principal diferencia para las apps de Apps Script es que pueden especificar un método específico para llamar cuando se activa el evento onClick mediante el uso de los pares clave-valor action.parameters y action.parameters.

Autorización

Las apps de Apps Script que acceden a recursos protegidos deben solicitar a los usuarios que autoricen este acceso la primera vez que se ejecuta para cada usuario. No es necesario que realices ninguna acción, pero debes tener en cuenta que es posible que los usuarios vean un diálogo de autorización la primera vez que usen tu app.

Apps Script controla la autorización a nivel de la secuencia de comandos. Las apps que requieren autorización no pueden realizar ninguna acción hasta que el usuario final lo autorice. Si deseas que tu app muestre un mensaje de bienvenida cuando no se haya autorizado y se agregue directamente a un espacio, puedes especificar un mensaje de resguardo en el manifiesto. Si tu app requiere una lógica de inicialización, es posible que debas duplicar esta lógica en la acción onMessage. Por ejemplo:

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

Mensajes asíncronos

Es posible que algunas apps necesiten enviar mensajes a Google Chat en función de un activador externo, como un activador basado en el tiempo en Apps Script.

En este caso práctico, tenemos pensado integrar de forma nativa la API de Google Chat en Apps Script. Mientras tanto, la única manera de lograr esto es a través de la API de HTTP externa (consulta la documentación). Esto requiere el uso de una cuenta de servicio de Cloud (consulta la documentación) a través de la biblioteca OAuth2 para Apps Script.

La siguiente app de ejemplo completa que publica un mensaje por minuto en cada espacio en el que se encuentra:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Archivo de manifiesto

El siguiente es un ejemplo del archivo manifest de Apps Script que debe acompañar a tu secuencia de comandos.

Si no iniciaste tu proyecto desde la plantilla de Chat, debes editar el archivo de manifiesto para agregar el objeto "chat": {}.

En el archivo de manifiesto, establece el entorno de ejecución en Rhino: "runtimeVersion": "DEPRECATED_ES5". Las apps de chat no son completamente compatibles con el entorno de ejecución de Apps Script V8, por lo que, si especificas "runtimeVersion": "V8", tu app de Chat podría generar un error errático. Por ejemplo, la estructura de respuesta de JSON puede cambiar situacionalmente de maneras impredecibles para las aplicaciones de Chat compiladas con el entorno de ejecución V8.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "DEPRECATED_ES5"
}

Es posible que un usuario agregue tu app a un espacio antes de autorizarla. En este caso, tu app no puede responder al evento de agregado al espacio. Si esto sucede, puedes proporcionar un mensaje de bienvenida para mostrar mediante el campo addToSpaceFallbackMessage.

El archivo de manifiesto se llama appsscript.json y forma parte de tu proyecto de Apps Script. Para ver el archivo de manifiesto en el editor de Apps Script, selecciona View > Show manifest file.