Enviar WhatsApp desde Google Sheets con Apps Script

/**
 * FlujosChat — enviar WhatsApp desde una hoja de Google Sheets.
 *
 * Hoja "Envios" (la fila 1 son los encabezados):
 *   A = teléfono en E.164 con + (+51987654321); se admiten espacios y guiones
 *   B = texto del mensaje
 *   C = estado (lo escribe el script)
 *   D = id del mensaje, o la hora del intento mientras C dice ENVIANDO (lo escribe el script)
 *
 * Configuración del proyecto → Propiedades del script:
 *   FLUJOSCHAT_API_KEY      = fjc_live_...          (obligatoria)
 *   FLUJOSCHAT_TEMPLATE_ID  = id de GET /templates  (opcional: plantilla fuera de 24 h)
 */
var URL_BASE = 'https://www.flujoschat.foo/api/public/v1';
var NOMBRE_HOJA = 'Envios';
var PRIMERA_FILA = 2;
var PAUSA_MS = 1100;                  // ~54 envíos por minuto: por debajo de 60/min del plan PRO
var TIEMPO_MAX_MS = 5 * 60000;        // Apps Script corta cada ejecución a los 6 minutos
var REINTENTO_MAX_MS = 23 * 3600000;  // la Idempotency-Key dura 24 h: se deja 1 h de margen
var TELEFONO_E164 = /^\+[1-9][0-9]{7,14}$/;

function enviarDesdeHoja() {
  // Una sola ejecución a la vez: si un activador y una ejecución manual leyeran la
  // misma fila, la segunda podría pisar el ENVIADO de la primera.
  var lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) {
    Logger.log('Ya hay otra ejecución en curso');
    return;
  }
  try {
    recorrerHoja();
  } finally {
    lock.releaseLock();
  }
}

function recorrerHoja() {
  var libro = SpreadsheetApp.getActiveSpreadsheet();
  var hoja = libro.getSheetByName(NOMBRE_HOJA);
  if (!hoja) throw new Error('No existe la hoja "' + NOMBRE_HOJA + '"');
  leerApiKey(); // antes de marcar ninguna fila como ENVIANDO

  var ultima = hoja.getLastRow();
  if (ultima < PRIMERA_FILA) return;

  // Solo sirve para saltar rápido lo ya resuelto: lo que se envía se relee fila a fila.
  var estados = hoja.getRange(PRIMERA_FILA, 3, ultima - PRIMERA_FILA + 1, 1).getValues();
  var plantillaId = PropertiesService.getScriptProperties().getProperty('FLUJOSCHAT_TEMPLATE_ID');
  var inicio = Date.now();

  for (var i = 0; i < estados.length; i++) {
    if (resuelta(estados[i][0])) continue;

    var fila = PRIMERA_FILA + i;
    if (Date.now() - inicio > TIEMPO_MAX_MS) {
      Logger.log('Se acabó el tiempo en la fila ' + fila + ': vuelve a ejecutar y sigue desde ahí.');
      return;
    }

    var resultado = procesarFila(libro, hoja, fila, plantillaId);
    if (resultado === 'parar') return;
    if (resultado === 'llamada') Utilities.sleep(PAUSA_MS);
  }
}

// Devuelve 'saltada' (no llamó a la API), 'llamada' o 'parar'.
function procesarFila(libro, hoja, fila, plantillaId) {
  // Se relee justo antes de enviar: alguien pudo editar la hoja mientras corría el script.
  var v = hoja.getRange(fila, 1, 1, 4).getValues()[0];
  var telefono = String(v[0]).replace(/[\s-]/g, '');
  var texto = String(v[1]).trim();
  var estado = String(v[2]);

  if (resuelta(estado)) return 'saltada';
  if (telefono === '' && texto === '') return 'saltada';

  // ENVIANDO = una ejecución anterior se cortó con la llamada en curso: pudo salir.
  var reintento = estado.indexOf('ENVIANDO') === 0;
  if (reintento) {
    // La hora vuelve como texto ISO o, si la hoja la convirtió, como fecha. Lo que no
    // se entienda va a revisión.
    var desde = v[3] instanceof Date ? v[3].getTime() : Date.parse(String(v[3]));
    if (isNaN(desde)) {
      escribirEstado(hoja, fila, 'REVISAR: pudo salir (no hay hora del intento)');
      return 'saltada';
    }
    if (Date.now() - desde >= REINTENTO_MAX_MS) {
      // Con la clave a punto de caducar, la API volvería a enviar: decide una persona.
      escribirEstado(hoja, fila, 'REVISAR: pudo salir el ' +
        Utilities.formatDate(new Date(desde), Session.getScriptTimeZone(), 'yyyy-MM-dd HH:mm'));
      return 'saltada';
    }
  }

  // E.164 estricto. "+5.1987654321E+10" empieza por + pero NO es un teléfono: la API
  // le quitaría el punto y la E, y el mensaje iría a otro número.
  if (!TELEFONO_E164.test(telefono)) return fallo(hoja, fila, reintento, 'TELEFONO_INVALIDO');
  if (texto === '') return fallo(hoja, fila, reintento, 'TEXTO_VACIO');

  // Estable por fila: la misma fila manda siempre la misma clave.
  var clave = 'hoja-' + libro.getId() + '-' + hoja.getSheetId() + '-fila-' + fila;

  // Constancia ANTES de llamar, y guardada ya: si la ejecución se corta con el mensaje
  // enviado, la próxima sabe que pudo salir y desde cuándo. Un reintento conserva la
  // hora del primer intento, que es cuando empezó a contar la clave.
  if (!reintento) {
    hoja.getRange(fila, 4).setNumberFormat('@'); // formato texto: que la hora no se convierta en fecha
    hoja.getRange(fila, 3, 1, 2).setValues([['ENVIANDO', new Date().toISOString()]]);
    SpreadsheetApp.flush();
  }

  var r = llamarApi({ to: telefono, type: 'text', text: texto }, clave);

  // Fuera de la ventana de 24 h el texto no sirve: se cae a la plantilla, con OTRA
  // clave, porque la primera ya quedó asociada a la respuesta 422.
  if (!r.ok && r.code === 'WHATSAPP_24H_WINDOW_EXPIRED' && plantillaId) {
    Utilities.sleep(PAUSA_MS);
    r = enviarPlantilla(telefono, plantillaId, {}, clave + '-plantilla');
    if (r.ok) r.estado = 'ENVIADO (plantilla)';
  }

  if (r.ok) {
    hoja.getRange(fila, 3, 1, 2).setValues([[r.estado || 'ENVIADO', r.id]]);
  } else if (r.code === 'IDEMPOTENCY_IN_PROGRESS') {
    // Otra petición con esta clave la está resolviendo: la fila no se toca.
  } else if (reintento || r.incierto) {
    // Pudo salir: sigue en ENVIANDO y D conserva la hora del primer intento.
    escribirEstado(hoja, fila, 'ENVIANDO (último intento: ' + r.code + ')');
  } else {
    hoja.getRange(fila, 3, 1, 2).setValues([['ERROR: ' + r.code, '']]);
  }

  // Key inválida, sin permiso, suscripción bloqueada, límite alcanzado o respuesta
  // ilegible: las filas siguientes fallarían igual, así que se para aquí.
  if (r.incierto || r.status === 401 || r.status === 402 || r.status === 403 || r.status === 429) {
    return 'parar';
  }
  return 'llamada';
}

function llamarApi(cuerpo, clave) {
  var res = UrlFetchApp.fetch(URL_BASE + '/messages', {
    method: 'post',
    contentType: 'application/json',
    headers: { Authorization: 'Bearer ' + leerApiKey(), 'Idempotency-Key': clave },
    payload: JSON.stringify(cuerpo),
    muteHttpExceptions: true
  });

  var status = res.getResponseCode();
  var body = null;
  try {
    body = JSON.parse(res.getContentText());
  } catch (e) {
    // La respuesta no era JSON (por ejemplo, un error de un proxy intermedio)
  }

  if (status >= 200 && status < 300 && body && body.success) {
    return { ok: true, status: status, id: body.data.message.id };
  }
  if (body && body.error && body.error.code) {
    return { ok: false, status: status, code: body.error.code };
  }
  // Sin error.code no se sabe qué pasó al otro lado: pudo enviarse.
  return { ok: false, status: status, code: 'HTTP_' + status, incierto: true };
}

function leerApiKey() {
  var apiKey = PropertiesService.getScriptProperties().getProperty('FLUJOSCHAT_API_KEY');
  if (!apiKey) throw new Error('Falta FLUJOSCHAT_API_KEY en las propiedades del script');
  return apiKey;
}

function resuelta(estado) {
  estado = String(estado);
  return estado.indexOf('ENVIADO') === 0 || estado.indexOf('REVISAR') === 0;
}

function escribirEstado(hoja, fila, estado) {
  hoja.getRange(fila, 3).setValue(estado);
}

function fallo(hoja, fila, reintento, codigo) {
  escribirEstado(hoja, fila, reintento ? 'ENVIANDO (último intento: ' + codigo + ')' : 'ERROR: ' + codigo);
  return 'saltada';
}

Código.gs — bloque 1 de 2

/**
 * Envía una plantilla aprobada por Meta: la única forma de escribir primero
 * o de retomar una conversación fuera de la ventana de 24 h.
 *
 *   templateId → el "id" que devuelve GET /templates
 *   variables  → valores por posición, por ejemplo { "1": "4512" }
 *   clave      → Idempotency-Key; distinta de la que usó el envío de texto
 */
function enviarPlantilla(telefono, templateId, variables, clave) {
  return llamarApi({
    to: telefono,
    type: 'template',
    templateId: templateId,
    variables: variables || {}
  }, clave);
}

Código.gs — bloque 2 de 2